@styleui/cli

The local AST mutation daemon and automated configuration setup utility for StyleUI.

This package provides the styleui command-line tool, which manages project initialization and controls the local WebSocket development daemon. The daemon synchronizes visual mutations from the StyleUI chrome extension back into your React/Next.js/Vite codebase in real-time.

Installation

You can install @styleui/cli globally to have the styleui command always available:

npm install -g @styleui/cli

Alternatively, you can run the CLI on-demand without prior installation using npx:

npx styleui <command> [options]

Commands & Usage

1. styleui init

Sets up the integration of StyleUI within your frontend project.

styleui init

What it does:

1. Detects Your Environment: Checks package.json and config files to determine if your project is running Next.js or Vite.
2. Installs Integration Plugins:
   • Installs @styleui/next-plugin as a devDependency in Next.js projects.
   • Installs @styleui/vite-plugin as a devDependency in Vite projects.
3. AST Config Wrapping: Uses AST parsing (recast) to non-destructively wrap your existing next.config.js/mjs/ts or vite.config.ts/js/mjs/cjs to enable StyleUI source-tracing compiling:
   • For Next.js: Wraps the config object using withStyleUI.
   • For Vite: Adds withStyleUI() to the plugins array.

2. styleui dev

Launches the StyleUI development synchronization engine.

styleui dev [options]

What it does:

1. License Gatekeeping: Prompts for a valid StyleUI License Key if not already authenticated. Saves the authenticated key locally at ~/.styleuikey.
2. Spawns WebSocket Server: Starts the mutation daemon locally (by default on port 8899).
3. Auto-Spawns Dev Server: Detects the package manager (npm, yarn, pnpm, or bun) and spawns the framework dev server (e.g. running npm run dev) in a concurrent child process, sharing standard I/O.
4. Launches Browser: Automatically launches your browser pointing to http://localhost:3000 (or your local address) to kickstart visual editing.

Options:

• -p, --port <number>: Port to run the WebSocket daemon server on. (Default: 8899)
• -b, --browser <type>: Target browser to spawn. Options: "chrome", "edge", "auto". (Default: "auto")
• -h, --help: Display command usage details.

Shell Help Output

To see all commands and globally available flags, run:

styleui --help

Output:

Usage: styleui [options] [command]

StyleUI Daemon - Local AST and WebSocket Engine

Options:
  -V, --version                output the version number
  -h, --help                   display help for command

Commands:
  init                         Automatically inject @styleui/next-plugin and wrap the Next.js config
  dev [options]                Start both the WebSocket daemon and the Next.js dev server concurrently
  help [command]               display help for command

To see detailed options for the dev command, run:

styleui dev --help

Output:

Usage: styleui dev [options]

Start both the WebSocket daemon and the Next.js dev server concurrently

Options:
  -p, --port <number>     port to run the WebSocket server on (default: "8899")
  -b, --browser <type>    Browser to launch ("chrome", "edge", "auto") (default: "auto")
  -h, --help              display help for command

Troubleshooting

Port Conflicts

If you see the error: ❌ Port 8899 is already in use. You can run the daemon on a custom port:

styleui dev -p 9000

Make sure to specify this same port in the StyleUI browser extension settings.

Dev Server Exited

If your React/Next.js dev server exits immediately upon run:

1. Ensure you have run dependency installation (npm install, pnpm install, etc.).
2. Verify that the port utilized by your Next.js/Vite application (typically 3000 or 5173) is not already bound by another process.