npm package: @hotshot-it/vite-plugin
Description: Vite plugin for Hotshot - AI-powered conversational code editing with Claude
Latest version: 1.0.0

# @hotshot-it/vite-plugin

Vite plugin that enables visual React component editing powered by Claude Agent SDK.

## Installation

```bash
pnpm add -D @hotshot-it/vite-plugin
```

## Setup

### 1. Get an API Key

Get your Claude API key from [console.anthropic.com](https://console.anthropic.com/)

Create a `.env` file in your project root:

```bash
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
```

**IMPORTANT**: The API key must be valid and have access to the Claude models. Test your key:

```bash
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

If you see an "Invalid API key" error, your key is expired or incorrect.

### 2. Configure Vite

In your `vite.config.ts`:

```typescript
import { defineConfig } from 'vite';
import hotshot from '@hotshot-it/vite-plugin';

export default defineConfig({
  plugins: [
    hotshot({
      port: 3737, // Optional: WebSocket port (default: 3737)
      model: 'claude-sonnet-4-5', // Optional: Claude model (default: claude-sonnet-4-5)
    }),
  ],
});
```

### 3. Install Browser Extension

Build and load the Chrome extension from `packages/extension/dist`.

## Testing

### Integration Test

Run the integration test to verify your setup:

```bash
cd packages/vite-plugin
pnpm test:integration
```

This will:
- ✓ Load API key from `examples/hotshot/.env`
- ✓ Validate API key format
- ✓ Create a test workspace
- ✓ Test Agent SDK connectivity
- ✓ Execute a sample query

### Expected Output

```
=== Hotshot Integration Test ===

1. Loading API key from examples/hotshot/.env...
   ✓ API key loaded: sk-ant-oat01-dNeZGWs...KgAA

2. Validating API key format...
   ✓ API key format is valid

3. Setting up test environment...
   ✓ Test workspace created
   ✓ Test component created: TestComponent.tsx

4. Testing Agent SDK connectivity...
   ✓ AgentHandler initialized

5. Testing Agent SDK query...
   ✓ Agent query completed successfully
   ✓ Received 15 messages from agent
   ✓ Received 12 streaming chunks
   ✓ Stream completed with session ID: abc123

=== Test Summary ===
✓ All tests passed! The integration is working correctly.
```

## Troubleshooting

### Error: "Invalid API key"

**Cause**: The API key in `.env` is invalid, expired, or lacks permissions.

**Solution**:
1. Get a new API key from https://console.anthropic.com/
2. Update `examples/hotshot/.env` with the new key
3. Verify the key works with the curl command above

### Error: "Claude Code process exited with code 1"

**Cause**: The Agent SDK CLI failed to start, usually due to:
- Invalid API key
- Network connectivity issues
- Missing Node.js dependencies

**Solution**:
1. Verify your API key is valid
2. Check network connectivity to `api.anthropic.com`
3. Run `pnpm install` to reinstall dependencies

### Error: "ANTHROPIC_API_KEY is required"

**Cause**: No API key found in environment or plugin config.

**Solution**:
1. Create `.env` file with `ANTHROPIC_API_KEY=your-key`
2. Or pass `apiKey` directly to the plugin config

## Architecture

```
Browser Extension → WebSocket → Vite Plugin → Agent SDK → Claude
```

1. User clicks a component in the browser
2. Extension sends component info via WebSocket
3. Plugin constructs prompt with file context
4. Agent SDK spawns Claude Code CLI
5. Claude reads/edits files via Agent tools
6. Changes stream back via WebSocket
7. Vite HMR updates the component

## API

### `hotshot(config?: HotshotConfig)`

Vite plugin factory function.

**Config Options:**

- `apiKey?: string` - Anthropic API key (defaults to `process.env.ANTHROPIC_API_KEY`)
- `port?: number` - WebSocket port (default: `3737`)
- `model?: string` - Claude model to use (default: `'claude-sonnet-4-5'`)
- `systemPromptAdditions?: string` - Additional system prompt instructions

## Development

```bash
# Build plugin
pnpm build

# Watch mode
pnpm dev

# Run integration test
pnpm test:integration

# Clean build output
pnpm clean
```

## License

MIT