react-client 1.0.6 → 1.0.8

package/README.md

@@ -2,140 +2,219 @@
 [![npm](https://img.shields.io/npm/dt/react-client.svg)](https://npm-stat.com/charts.html?package=react-client)
 [![GitHub issues](https://img.shields.io/github/issues/venkateshsundaram/react-client.svg)](https://github.com/venkateshsundaram/react-client/issues)
 
-react-client is a lightweight CLI and runtime for building React apps with fast iteration. It is designed to be esbuild-based, Node-native, and modular like Vite/Next.js while remaining minimal.
+**react-client** is a next-generation CLI and runtime for building React apps with instant feedback, fast iteration, and a beautiful developer experience.
 
-## Table of Contents
+Built for simplicity, designed for speed ⚡
+
+---
+
+## 🚀 Table of Contents
 - [Installation](#installation)
 - [With Config](#with-config)
-- [Wiki](#wiki)
-- [Available templates](#available-templates)
-- [Features supported by the CLI](#features-supported-by-the-cli)
-- [Template specifics](#template-specifics)
-   * [react-ssr-ts](#react-ssr-ts)
-   * [react-tailwind-ts](#react-tailwind-ts)
-- [How the CLI wires features](#how-the-cli-wires-features)
-- [Local testing checklist](#local-testing-checklist)
+- [Available Templates](#available-templates)
+- [Core Features](#core-features)
+- [How It Works](#how-it-works)
+- [Local Development](#local-development)
 - [Troubleshooting](#troubleshooting)
-- [Extending & Contributing](#extending-contributing)
 - [Contributing](#contributing)
 - [Publishing](#publishing)
-- [Feedbacks and Issues](#feedbacks-and-issues)
+- [Feedback](#feedback)
 - [License](#license)
 
-## Installation
+---
 
-The React-client package lives in npm.
+## 🧩 Installation
 
-To install the latest stable version, run the following command:
+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
 ```
 
-## With Config
+This launches the **custom dev server** — not Vite — 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  
 
-The `init` command supports a small set of helpers for scaffolding projects from the bundled templates. Notably:
+---
 
-- `--template <name>`: choose a template (defaults to `react-ts`).
-- `--with-config`: also create a `react-client.config.ts` file in the generated project with a minimal `defineConfig({})` stub.
+## ⚙️ With Config
 
-Example:
+You can generate a project-level configuration file using `--with-config`.
 
 ```bash
 react-client init myapp --template react-ts --with-config
-# creates `myapp/` and writes `myapp/react-client.config.ts`
 ```
 
-## Wiki
+Creates:
+
+```js
+// react-client.config.js
+import { defineConfig } from 'react-client/config';
+
+export default defineConfig({
+  root: './src',
+  server: { port: 5173 },
+  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-ssr` | JavaScript SSR |
+| `react-ssr-ts` | TypeScript SSR |
+| `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 (no Vite)** — Connect + WebSocket + esbuild  
+- 🔁 **React Fast Refresh (HMR)** — State-preserving reloads  
+- 💥 **Vite-style 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 5173 is occupied  
+- 🧠 **Smart Config Loader** — Detects project root, compiles `.ts` configs dynamically  
+- 🎨 **PrismJS Highlighting** — For pretty overlay code frames  
+- 🧱 **SSR Runtime Support** — For server-side templates (`react-ssr*`)  
+- 🧩 **Generators** — Create components, routes, and tests instantly  
+- 🔌 **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.  
+5. **Overlay UI** (via PrismJS) displays mapped stack frames with syntax highlighting.
+
+---
 
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/venkateshsundaram/react-client)
+## 🧪 Local Development
 
-## Available templates
+To test `react-client` locally:
 
-- react — JavaScript SPA
-- react-ts — TypeScript SPA
-- react-ssr — JavaScript SSR app
-- react-ssr-ts — TypeScript SSR app
-- react-tailwind — JavaScript + Tailwind
-- react-tailwind-ts — TypeScript + Tailwind
+```bash
+cd ~/Desktop/Workspace/Hoppy-projects/react-client
+npm run build
+npm link
+cd myapp
+react-client dev
+```
 
-## Features supported by the CLI
+If you run it from inside the CLI repo, it auto-detects and switches to `myapp/` as the root.
 
-- React Fast Refresh: HMR that preserves component state
-- PostCSS/Tailwind auto-injection and setup for Tailwind templates
-- CSS Modules support with hashing and AST-based import rewriting
-- Asset hashing and manifest generation for SSR runtime lookups
-- Plugin hook system (configResolved, transform, buildEnd)
-- Generators: component/route/test scaffolding
-- SSR runtime with server that consults manifest.json
+---
 
-## Template specifics
+## 🧩 Troubleshooting
 
-### react-ssr-ts
+### ❌ Config not loading
+Make sure `react-client.config.js` exists in your project root (not `.ts`).
+
+```bash
+/Users/<you>/myapp/react-client.config.js
+```
+
+### ❌ `react-refresh/runtime` not found
+Install in the CLI or the project:
+```bash
+npm install react-refresh
+```
 
-- `src/entry-client.tsx` — client hydration entry
-- `src/entry-server.tsx` — server rendering entry (exports `render(url)`)
-- `src/pages/` — route components
-- `index.html` — template used by build system
-- `package.json` lists devDependencies required for local testing (esbuild, react-refresh)
+### ⚠️ Port already in use
+CLI will auto-detect and prompt:
+```
+Port 5173 is occupied. Use 5174 instead? (Y/n)
+```
 
-### react-tailwind-ts
+### ⚠️ Permission denied
+Ensure your CLI entry file is executable:
+```bash
+chmod +x dist/cli/index.js
+npm link
+```
 
-- `postcss.config.cjs` and `tailwind.config.cjs` included
-- `src/index.css` with Tailwind directives
-- `package.json` includes tailwind/postcss devDependencies (install locally in the app)
+---
 
-## How the CLI wires features
+## 🧑‍💻 Contributing
 
-1. **HMR & React Refresh**: dev plugin injects `import '/@react-refresh-shim'` into files that import React. During build, the CLI attempts to `require.resolve('react-refresh/runtime')` and copy it into the client vendor folder to be included in bundles.
-2. **CSS Modules**: build step uses `postcss-modules` to produce JSON class maps and then uses `es-module-lexer` + `magic-string` to rewrite `.module.css` import specifiers to the hashed filenames emitted by the bundler.
-3. **Manifest**: after building, the CLI hashes outputs and writes `client/manifest.json` mapping original -> hashed filenames. The SSR server uses this manifest to serve correct hashed assets and update HTML script tags dynamically.
-4. **PostCSS/Tailwind**: if `postcss.config.cjs` or `tailwind.config.cjs` exists in the project, the build process runs `npx postcss` to process CSS and includes the output in the final client bundle.
+We welcome contributions!  
+Read the [Contributing Guide](./CONTRIBUTING.md) for setup instructions.
 
-## Local testing checklist
+```bash
+npm run lint
+npm run test
+npm run build
+```
 
-1. Node 20+ installed.
-2. Scaffold a new app using the CLI `init` command pointing to these templates.
-3. `npm install` in the new app to get dependencies.
-4. Run `node /path/to/react-client/dist/cli/index.js dev` for HMR-enabled dev server, or `build:ssr` to produce SSR build and run `node dist/server/server.js` to preview.
+---
 
-## Troubleshooting
+## 🚀 Publishing
 
-- If `react-refresh/runtime` isn't found during build, install in the environment running the CLI:
-  ```bash
-  npm install --save-dev react-refresh
-  ```
-- For PostCSS/Tailwind errors, ensure tailwind & postcss installed in the target app:
-  ```bash
-  npm install --save-dev tailwindcss postcss autoprefixer
-  ```
-- For AST rewriting, ensure `es-module-lexer` and `magic-string` are installed where the CLI runs:
-  ```bash
-  npm install --save-dev es-module-lexer magic-string
-  ```
+Before publishing:
+1. Update version in `package.json`  
+2. Run a full build  
+3. Ensure the entry file has execute permission  
 
-## Extending & Contributing
+```bash
+npm run build
+npm publish
+```
 
-- Add plugins under `src/plugins` with `configResolved` and `transform` hooks.
-- Tests: add Jest configurations inside templates and include `test` npm scripts.
+Your package now includes:
+- `#!/usr/bin/env node` shebang  
+- Auto-detecting config loader  
+- Built-in React Refresh runtime  
 
-## Contributing
+---
 
-Development of react-client happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving react-client.
+## 💬 Feedback
 
-- [Contributing Guide](./CONTRIBUTING.md)
+Found an issue or have a feature request?  
+👉 [Open an issue](https://github.com/venkateshsundaram/react-client/issues)
 
-## Publishing
+---
 
-Before pushing your changes to Github, make sure that `version` in `package.json` is changed to newest version. Then run `npm install` for synchronize it to `package-lock.json` and `pnpm install` for synchronize it to `pnpm-lock.yaml`
+## 🪪 License
 
-## Feedbacks and Issues
+**MIT Licensed** © [Venkatesh Sundaram](https://github.com/venkateshsundaram)
 
-Feel free to open issues if you found any feedback or issues on `react-client`. And feel free if you want to contribute too! 😄
+---
 
-## License
+## 🗺️ Architecture Overview (Bonus)
 
-React-client is [MIT licensed](./LICENSE).
+```text
+ ┌───────────────────────────┐
+ │ react-client (CLI)        │
+ │  ├── esbuild (watch/bundle)
+ │  ├── connect (dev server)
+ │  ├── websocket (HMR)
+ │  ├── prismjs overlay
+ │  └── chokidar (file watch)
+ └───────────────────────────┘
+             │
+             ▼
+   Browser ↔ Live HMR + Overlay
+```

package/dist/cli/commands/build.js

@@ -7,55 +7,38 @@ exports.default = build;
 const esbuild_1 = __importDefault(require("esbuild"));
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const child_process_1 = require("child_process");
-const crypto_1 = __importDefault(require("crypto"));
-function hash(buf) {
-    return crypto_1.default.createHash('sha256').update(buf).digest('hex').slice(0, 8);
-}
+const chalk_1 = __importDefault(require("chalk"));
+const loadConfig_1 = require("../../utils/loadConfig");
 async function build() {
     const root = process.cwd();
-    const entry = path_1.default.join(root, 'src', 'main.tsx');
-    const out = path_1.default.join(root, 'dist');
-    await fs_extra_1.default.remove(out);
-    const result = await esbuild_1.default.build({
-        entryPoints: [entry],
-        bundle: true,
-        outdir: path_1.default.join(out, 'client'),
-        metafile: true,
-        minify: true,
-        loader: {
-            '.ts': 'ts',
-            '.tsx': 'tsx',
-            '.js': 'jsx',
-            '.jsx': 'jsx',
-            '.png': 'file',
-            '.jpg': 'file',
-            '.svg': 'file',
-        },
-    });
-    const postcssConfig = path_1.default.join(root, 'postcss.config.cjs');
-    if (fs_extra_1.default.existsSync(postcssConfig)) {
-        try {
-            (0, child_process_1.execSync)('npx postcss ' + path_1.default.join(out, 'client', '*.css') + ' -d ' + path_1.default.join(out, 'client'));
-        }
-        catch (e) {
-            console.warn('PostCSS failed', e && e.message);
-        }
+    const config = await (0, loadConfig_1.loadReactClientConfig)(root);
+    const appRoot = path_1.default.resolve(root, config.root || '.');
+    const outDir = path_1.default.join(appRoot, config.build?.outDir || '.react-client/build');
+    console.log(chalk_1.default.cyan(`\n🏗️ Building project...`));
+    console.log(chalk_1.default.gray(`Root: ${appRoot}`));
+    console.log(chalk_1.default.gray(`Output: ${outDir}\n`));
+    const entry = path_1.default.join(appRoot, 'src', 'main.tsx');
+    if (!fs_extra_1.default.existsSync(entry)) {
+        console.error(chalk_1.default.red('❌ Entry not found: src/main.tsx'));
+        process.exit(1);
+    }
+    await fs_extra_1.default.ensureDir(outDir);
+    try {
+        await esbuild_1.default.build({
+            entryPoints: [entry],
+            bundle: true,
+            minify: true,
+            sourcemap: true,
+            outdir: outDir,
+            define: { 'process.env.NODE_ENV': '"production"' },
+            loader: { '.ts': 'ts', '.tsx': 'tsx', '.js': 'jsx', '.jsx': 'jsx' },
+        });
+        console.log(chalk_1.default.green(`✅ Build completed successfully!`));
+        console.log(chalk_1.default.gray(`Output directory: ${outDir}`));
     }
-    const manifest = {};
-    for (const outPath in result.metafile.outputs) {
-        const abs = path_1.default.join(root, outPath);
-        if (!fs_extra_1.default.existsSync(abs))
-            continue;
-        const data = await fs_extra_1.default.readFile(abs);
-        const h = hash(data);
-        const rel = outPath.replace(/^client\//, '');
-        const ext = path_1.default.extname(rel);
-        const hashed = rel.replace(ext, '.' + h + ext);
-        await fs_extra_1.default.ensureDir(path_1.default.join(out, 'client', path_1.default.dirname(hashed)));
-        await fs_extra_1.default.move(abs, path_1.default.join(out, 'client', hashed));
-        manifest[rel] = hashed;
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error('❌ Build failed:', msg);
+        process.exit(1);
     }
-    await fs_extra_1.default.writeFile(path_1.default.join(out, 'client', 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
-    console.log('Built client to', path_1.default.join(out, 'client'));
 }

package/dist/cli/commands/build.ssr.js

@@ -7,63 +7,40 @@ exports.default = buildSsr;
 const esbuild_1 = __importDefault(require("esbuild"));
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const crypto_1 = __importDefault(require("crypto"));
-function hash(buf) {
-    return crypto_1.default.createHash('sha256').update(buf).digest('hex').slice(0, 8);
-}
+const chalk_1 = __importDefault(require("chalk"));
+const loadConfig_1 = require("../../utils/loadConfig");
 async function buildSsr() {
     const root = process.cwd();
-    const clientEntry = path_1.default.join(root, 'src', 'entry-client.tsx');
-    const serverEntry = path_1.default.join(root, 'src', 'entry-server.tsx');
-    if (!fs_extra_1.default.existsSync(clientEntry) || !fs_extra_1.default.existsSync(serverEntry)) {
-        console.error('SSR entries missing');
+    const config = await (0, loadConfig_1.loadReactClientConfig)(root);
+    const appRoot = path_1.default.resolve(root, config.root || '.');
+    const outDir = path_1.default.join(appRoot, config.build?.outDir || '.react-client/ssr');
+    console.log(chalk_1.default.cyan(`\n🧱 Building SSR bundle...`));
+    console.log(chalk_1.default.gray(`Root: ${appRoot}`));
+    console.log(chalk_1.default.gray(`Output: ${outDir}\n`));
+    const entry = path_1.default.join(appRoot, 'src', 'server.tsx');
+    if (!fs_extra_1.default.existsSync(entry)) {
+        console.error(chalk_1.default.red('❌ SSR entry not found: src/server.tsx'));
         process.exit(1);
     }
-    const out = path_1.default.join(root, 'dist');
-    await fs_extra_1.default.remove(out);
-    const clientResult = await esbuild_1.default.build({
-        entryPoints: [clientEntry],
-        bundle: true,
-        outdir: path_1.default.join(out, 'client'),
-        metafile: true,
-        minify: true,
-        loader: {
-            '.ts': 'ts',
-            '.tsx': 'tsx',
-            '.js': 'jsx',
-            '.jsx': 'jsx',
-            '.png': 'file',
-            '.jpg': 'file',
-            '.svg': 'file',
-        },
-    });
-    const _serverResult = await esbuild_1.default.build({
-        entryPoints: [serverEntry],
-        bundle: true,
-        platform: 'node',
-        format: 'cjs',
-        outfile: path_1.default.join(out, 'server', 'entry-server.js'),
-        external: ['react', 'react-dom'],
-    });
-    const manifest = {};
-    for (const outPath in clientResult.metafile.outputs) {
-        if (!outPath.startsWith('client/'))
-            continue;
-        const abs = path_1.default.join(out, outPath);
-        if (!fs_extra_1.default.existsSync(abs))
-            continue;
-        const data = await fs_extra_1.default.readFile(abs);
-        const h = hash(data);
-        const rel = outPath.replace(/^client\//, '');
-        const ext = path_1.default.extname(rel);
-        const hashed = rel.replace(ext, '.' + h + ext);
-        await fs_extra_1.default.ensureDir(path_1.default.join(out, 'client', path_1.default.dirname(hashed)));
-        await fs_extra_1.default.move(abs, path_1.default.join(out, 'client', hashed));
-        manifest[rel] = hashed;
+    await fs_extra_1.default.ensureDir(outDir);
+    try {
+        await esbuild_1.default.build({
+            entryPoints: [entry],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node18',
+            external: ['react', 'react-dom'],
+            outdir: outDir,
+            define: { 'process.env.NODE_ENV': '"production"' },
+            loader: { '.ts': 'ts', '.tsx': 'tsx' },
+        });
+        console.log(chalk_1.default.green(`✅ SSR build completed successfully!`));
+        console.log(chalk_1.default.gray(`Output directory: ${outDir}`));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error('❌ SSR build failed:', msg);
+        process.exit(1);
     }
-    await fs_extra_1.default.writeFile(path_1.default.join(out, 'client', 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
-    const runtime = `const http = require('http');const fs = require('fs');const path=require('path');const { render } = require('./entry-server.js');const clientDir = path.join(__dirname,'..','client');const manifest = JSON.parse(fs.readFileSync(path.join(clientDir,'manifest.json'),'utf8'));const PORT = process.env.PORT||3000;const server = http.createServer(async (req,res)=>{ try{ if(req.url && req.url.startsWith('/client/')){ const rel = req.url.replace('/client/',''); const mapped = manifest[rel] || rel; const p = path.join(clientDir, mapped); if(fs.existsSync(p)) { res.writeHead(200); res.end(fs.readFileSync(p)); return; } } const htmlPath = path.join(clientDir,'index.html'); let html = '<!doctype html><html><head></head><body><div id="root"></div><script type="module" src="/client/bundle.js"></script></body></html>'; if(fs.existsSync(htmlPath)) html = fs.readFileSync(htmlPath,'utf8'); const content = await render(req.url||'/'); const outHtml = html.replace('<div id="root"></div>','<div id="root">'+content+'</div>'); res.writeHead(200,{'Content-Type':'text/html'}); res.end(outHtml);}catch(e){ console.error(e); res.writeHead(500); res.end('SSR error');}});server.listen(PORT,()=>console.log('SSR server running on port '+PORT));`;
-    await fs_extra_1.default.ensureDir(path_1.default.join(out, 'server'));
-    await fs_extra_1.default.writeFile(path_1.default.join(out, 'server', 'server.js'), runtime, 'utf8');
-    console.log('SSR build complete at', out);
 }