Manual Setup

For non-Vite projects, manual installation is the recommended approach. Instead of using a proxy server, you directly add a small script into your HTML that tells JSX Tool where to connect. This avoids redirect and routing issues while giving you complete control.

Reference example: Next.js Manual Setup

Recommended Approach

Manual setup avoids the redirect and routing issues that can occur with proxy-based setups. It's simpler to debug and gives you more control over when JSX Tool is loaded.

How It Works

Manual installation requires only two things:

WebSocket Server - Runs alongside your dev server for file-system communication
Inline Script Tag - A single line in your HTML <head> that sets the WebSocket URL

No proxy server means your dev server runs normally on its default port. The WebSocket connection runs on a separate port (e.g., 12022) and only handles file operations.

Install

Add the package to your project:

npm install @jsx-tool/jsx-tool

Configure

Create a .jsxtool/ directory next to your package.json with a config.json file:

.jsxtool/config.json

{
  "noProxy": true,              // Disable proxy mode
  "wsPort": 12022,              // WebSocket port
  "wsHost": "localhost",
  "wsProtocol": "ws",
  "logging": false
}

Key settings:

noProxy: true - Disables proxy mode (required for manual setup)
wsPort - The port for the WebSocket server (choose any available port)

Add the Script

Add a script to your HTML <head> that sets the WebSocket URL. The exact location depends on your framework:

Next.js (App Router)

In your root app/layout.tsx:

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        {process.env.NODE_ENV === 'development' && (
          <script
            dangerouslySetInnerHTML={{
              __html: `window.__JSX_TOOL_DEV_SERVER_WS_URL__ = 'ws://localhost:12022';`,
            }}
          />
        )}
      </head>
      <body>{children}</body>
    </html>
  );
}

Standard HTML

In your index.html or template file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My App</title>
    
    <script>
      if (process.env.NODE_ENV === 'development') {
        window.__JSX_TOOL_DEV_SERVER_WS_URL__ = 'ws://localhost:12022';
      }
    </script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

Other Frameworks

For Create React App, custom webpack setups, or other frameworks, add the script wherever your app serves the <head> tag. The key is to:

Set window.__JSX_TOOL_DEV_SERVER_WS_URL__ before your React app mounts
Only include it in development mode
Use the same port as configured in .jsxtool/config.json

Update Scripts

Modify your package.json scripts to run both servers:

package.json

{
  "scripts": {
    "dev": "your-dev-server-command --port 3002",
    "jsx-tool": "jsx-tool",
    "dev:jsx-tool": "npm run jsx-tool & npm run dev"
  }
}

Run

Start both servers:
```
npm run dev:jsx-tool
```
Open your app at your dev server's port:
Visit your normal dev server URL (e.g., http://localhost:3000). No proxy port needed!
Use the JSX Tool browser extension to inspect components and apply edits.

What to Expect

WebSocket server runs alongside your dev server
JSX Tool only loads in development mode
Your dev server runs on its normal port

Project Structure

package.json
.jsxtool/
├── config.json   # WebSocket configuration
└── rules.md      # Custom prompting rules (optional)

Can't Use Manual Setup?

If manual script installation is too cumbersome for your usecase, see the proxy approach.