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 ⚡

---

🚀 Table of Contents

- Installation
- With Config
- Available Templates
- Core Features
- How It Works
- Local Development
- Troubleshooting
- Contributing
- Publishing
- Feedback
- License

---

🧩 Installation

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

---

⚙️ With Config

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()
✅ Supports .js, .mjs, .ts (auto-compiled)

---

🧰 Available Templates

| 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.

---

💎 Core Features

- ⚡ Custom Dev Server — Connect + WebSocket + esbuild
- 🔁 React Fast Refresh (HMR) — State-preserving reloads
- 💥 Overlay — Syntax-highlighted stack frames, clickable file links (vscode://file)
- 🔍 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 .ts configs dynamically
- 🔌 Plugin Hook System — Extendable with configResolved, transform, buildEnd

---

🧬 How It Works

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.

---

🧪 Local Development

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.

---

🧩 Troubleshooting

$3


Make sure react-client.config.js 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
- Auto-detecting config loader
- Built-in React Refresh runtime

---

💬 Feedback

Found an issue or have a feature request?
👉 Open an issue

---

🪪 License

MIT Licensed © Venkatesh Sundaram