Development server for JSX Tool
npm install @jsx-tool/jsx-tool
A lightweight development server that bridges your browser and filesystem for real-time React component editing
---
JSX Tool Dev Server enables the JSX Tool Chrome extension to read and modify your React source code in real-time. It provides a WebSocket server scoped to your project directory, allowing secure file system access from the browser extension.
For example integrations, check out the jsx-tool-examples repository which demonstrates various setups including React Router with Vite, Next.js, and more.
For Vite projects, use the plugin-based approach:
``bashInstall
npm i @jsx-tool/jsx-tool
export default defineConfig({
plugins: [
react(),
jsxToolDevServer(),
],
});
`
For non-Vite projects, use the CLI with optional proxy:
`bashInitialize configuration
npx @jsx-tool/jsx-tool init
CLI API
$3
Initialize JSX Tool configuration in your project. Call this from next to your package.json. !!!not your root package.json if a monorepo!!!
`bash
npx @jsx-tool/jsx-tool init [options]
`Options:
-
-f, --from - Working directory (default: current directory)Interactive prompts:
- Vite project detection
- Server port configuration
- Proxy enablement
- WebSocket port setup
Creates:
-
.jsxtool/rules.md - Custom prompting rules (all projects)
- .jsxtool/config.json - Configuration file (non-Vite only)$3
Start the JSX Tool development server.
`bash
npx @jsx-tool/jsx-tool start [options]
`Options:
Working Directory:
-
-f, --from - Working directory (default: current directory)
- --node-modules-dir - node_modules directory (auto-detected or defaults to working directory)
- --additional-directories - Comma-separated list of additional directories to watchServer Configuration:
-
--server-port - Target server port (default: 4000)
- --server-host - Target server host (default: localhost)
- --server-protocol - Target server protocol: http or https (default: http)Proxy Configuration:
-
--proxy-port - Proxy server port (default: 3000)
- --proxy-host - Proxy server host (default: localhost)
- --proxy-protocol - Proxy server protocol: http or https (default: http)
- --no-proxy - Disable proxy serverWebSocket Configuration:
-
--ws-port - WebSocket server port (default: 12021)
- --ws-host - WebSocket server host (default: localhost)
- --ws-protocol - WebSocket protocol: ws or wss (default: ws)Development Options:
-
--insecure - Run dev server without signature check
- --logging - Enable logging
- -d, --debug - Enable debug loggingExamples:
`bash
Start with default settings (reads from .jsxtool/config.json)
npx @jsx-tool/jsx-tool startStart without proxy
npx @jsx-tool/jsx-tool start --no-proxyStart with custom ports
npx @jsx-tool/jsx-tool start --server-port 3000 --proxy-port 4000Start in monorepo with explicit node_modules path
npx @jsx-tool/jsx-tool start --node-modules-dir ../../node_modulesStart with additional directories to watch
npx @jsx-tool/jsx-tool start --additional-directories packages/ui,packages/sharedStart with debug logging
npx @jsx-tool/jsx-tool start --debug
`Vite Plugin API
For Vite projects, use the
jsxToolDevServer plugin instead of the CLI.`typescript
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { jsxToolDevServer } from "@jsx-tool/jsx-tool/vite";export default defineConfig({
plugins: [
react(),
jsxToolDevServer({
debug: false, // Enable debug logging
nodeModulesDir: undefined, // Path to node_modules (auto-detected)
additionalDirectories: [] // Additional directories to watch (for mono-repos)
}),
],
});
`Plugin Options:
-
debug?: boolean - Enable debug logging (default: false)
- nodeModulesDir?: string - Explicit path to node_modules directory (auto-detected by default)
- additionalDirectories?: string[] - Additional directories to watch relative to project rootWhat it does:
- Automatically starts WebSocket server with your Vite dev server
- Injects client script during development only
- Configures WebSocket URL based on Vite's server settings
- No proxy needed - works directly with Vite's dev server
Monorepo setup:
Install
@jsx-tool/jsx-tool in your app package (not monorepo root) and add the plugin to that app's vite.config.ts. The plugin will auto-detect the root node_modules directory.Configuration File
For non-Vite projects, create
.jsxtool/config.json:`json
{
"serverPort": 3000,
"serverHost": "localhost",
"serverProtocol": "http",
"noProxy": false,
"proxyPort": 4000,
"proxyHost": "localhost",
"proxyProtocol": "http",
"wsPort": 12021,
"wsHost": "localhost",
"wsProtocol": "ws",
"injectAt": ""
}
`Configuration priority:
1. CLI options (highest priority)
2. Config file values
3. Default values (lowest priority)
Custom Prompting Rules
Create
.jsxtool/rules.md to add project-specific prompting rules that will be included when using the JSX Tool extension:`markdown
Project Rules
- Always use TypeScript
- Follow the existing component structure in src/components
- Use Tailwind CSS for styling
`System Architecture

$3
1. Browser Extension - Receives the WebSocket address and connects to the JSX Tool dev server
2. JSX Tool WebSocket Server - Lightweight server scoped to your React project for secure file operations
3. Your Project Web Server - Communicates the WebSocket address either manually or via proxy
4. JSX Tool Proxy Server (optional) - Intercepts document requests to inject the WebSocket address
$3
With Vite:
- Plugin starts WebSocket server alongside Vite dev server
- Client script is automatically injected during development
- Extension connects directly to your dev server
Without Vite (using proxy):
- Proxy intercepts HTTP requests to your dev server
- Injects WebSocket connection script into HTML responses
- WebSocket server handles file system operations
- Extension connects via injected script
Without Vite (no proxy):
- Manually add WebSocket connection script to your HTML
- WebSocket server handles file system operations
- Extension connects via your script
$3
- File system scope - Server only accesses files within your project directory and configured additional directories
- Development only - Designed for local development environments
- Signature verification - Optional signature checking for enhanced security (disable with
--insecure)Troubleshooting
$3
"Cannot find module @jsx-tool/jsx-tool/vite"
- Ensure
@jsx-tool/jsx-tool is installed in the same workspace/package as your vite.config.tsExtension can't connect
- Confirm Vite dev server is running
- Check that JSX Tool extension is enabled in Chrome
- Verify no firewall blocking WebSocket connections
$3
"Invalid working directory" errors
- Ensure React is installed in your project
- For monorepos, use
--node-modules-dir to point to the correct node_modules (not common)Proxy connection issues
- Verify your app server is running on the configured port
- Check proxy and server ports don't conflict
- Ensure
serverPort matches your app's portWebSocket connection fails
- Check WebSocket port isn't blocked by firewall
- Verify no other service is using the WebSocket port
- Try with
--debug` flag to see detailed logsSee the jsx-tool-examples repository for complete working examples:
- React Router with Vite
- Next.js integration
- Custom webpack setups
- Monorepo configurations
For complete documentation, visit jsxtool.com/docs/dev-server