react-client is a lightweight CLI and runtime for building React apps with fast iteration.
npm install react-client


react-client is a next-generation CLI and runtime for building React apps with instant feedback, fast iteration, and a beautiful developer experience.
Built for simplicity, designed for speed โก
---
---
Install globally and scaffold your first app:
``bash`
npm install -g react-client
react-client init myapp --template react-ts
cd myapp
npm install
npm run dev
This launches the custom dev server โ built on Connect + WebSocket + esbuild, featuring:
- Instant rebuilds
- React Fast Refresh (HMR)
- Auto port detection & confirmation prompt
- In-browser overlay with syntax-highlighted code frames
---
You can generate a project-level configuration file using --with-config.
`bash`
react-client init myapp --template react-ts --with-config
Creates:
`js
// react-client.config.js
import { defineConfig } from 'react-client/config';
export default defineConfig({
root: './src',
server: { port: 2202 },
build: { outDir: '.react-client/build' }
});
`
โ
Loaded automatically by the CLI
โ
Type-safe with IntelliSense via defineConfig() .js
โ
Supports , .mjs, .ts (auto-compiled)
---
| Template | Description |
|-----------|-------------|
| react | JavaScript SPA |react-ts
| | TypeScript SPA |react-tailwind
| | JS + Tailwind |react-tailwind-ts
| | TS + Tailwind |
Each template is pre-configured for esbuild, HMR, and fast bootstrapping.
---
- โก Custom Dev Server โ Connect + WebSocket + esbuild
- ๐ React Fast Refresh (HMR) โ State-preserving reloads
- ๐ฅ Overlay โ Syntax-highlighted stack frames, clickable file links (vscode://file) .ts
- ๐ Source Map Stack Mapping โ Maps runtime errors to original TS/JS source lines
- ๐ฌ Auto Port Detection โ Prompts when default port 2202 is occupied
- ๐ง Smart Config Loader โ Detects project root, compiles configs dynamically configResolved
- ๐ Plugin Hook System โ Extendable with , transform, buildEnd
---
Under the hood:
1. esbuild handles bundling, incremental rebuilds, and sourcemaps.
2. Connect serves files and APIs (React Refresh runtime, overlay, source-map).
3. WebSocket pushes HMR updates and overlay messages.
4. Chokidar watches /src for changes and triggers rebuilds.
---
To test react-client locally:
`bash`
cd ~/Desktop/Workspace/Hoppy-projects/react-client
npm run build
npm link
cd myapp
react-client dev
If you run it from inside the CLI repo, it auto-detects and switches to myapp/ as the root.
---
exists in your project root (not .ts).`bash
/Users//myapp/react-client.config.js
`$3
Install in the CLI or the project:
`bash
npm install react-refresh
`$3
CLI will auto-detect and prompt:
`
Port 2202 is occupied. Use 5174 instead? (Y/n)
`$3
Ensure your CLI entry file is executable:
`bash
chmod +x dist/cli/index.js
npm link
`---
๐งโ๐ป Contributing
We welcome contributions!
Read the Contributing Guide for setup instructions.
`bash
npm run lint
npm run test
npm run build
`---
๐ Publishing
Before publishing:
1. Update version in
package.json
2. Run a full build
3. Ensure the entry file has execute permission `bash
npm run build
npm publish
`Your package now includes:
-
#!/usr/bin/env node` shebang ---
Found an issue or have a feature request?
๐ Open an issue
---
MIT Licensed ยฉ Venkatesh Sundaram