@nestjs-ssr/react 0.1.12 → 0.2.1

package/README.md

@@ -1,122 +1,90 @@
-# @nestjs-ssr/react
+# NestJS SSR
+
+[![npm version](https://badge.fury.io/js/%40nestjs-ssr%2Freact.svg)](https://www.npmjs.com/package/@nestjs-ssr/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 > **⚠️ Preview Release**
 > This package is currently in active development. The API may change between minor versions. Production use is not recommended yet.
 
-Server-side rendering for React in NestJS with full TypeScript support and type-safe props.
-
-## Features
+Server-rendered React for NestJS. Controllers return data, components render it.
 
-- **Type-Safe Props** - TypeScript validates controller returns match component props
-- **Zero Config** - Works out of the box with sensible defaults
-- **Streaming SSR** - Modern renderToPipeableStream support
-- **HMR in Development** - Powered by Vite for instant feedback
-- **Production Ready** - Code splitting, caching, and optimizations built-in
+Clean Architecture: layers separated, dependencies inward, business logic framework-agnostic.
 
-## Installation
+## When To Use
 
-```bash
-npm install @nestjs-ssr/react
-npx nestjs-ssr  # Set up your project automatically
-```
+**Use this when:**
 
-The CLI installs dependencies, creates entry files, and configures TypeScript/Vite for you.
+- You have NestJS and want React instead of Handlebars/EJS
+- Testable layers matter more than file-based routing
+- You want feature modules (controller + service + view together)
 
-## Usage
+**Use Next.js when:**
 
-**1. Register the module**
+- You're starting fresh without NestJS
+- You want the React ecosystem's defaults
+- File-based routing fits your mental model
 
-```typescript
-// app.module.ts
-import { RenderModule } from '@nestjs-ssr/react';
+## Quick Start
 
-@Module({
-  imports: [RenderModule],
-})
-export class AppModule {}
+```bash
+npx nestjs-ssr init
 ```
 
-**2. Create a view component**
-
 ```typescript
-// src/views/home.tsx
-import type { PageProps } from '@nestjs-ssr/react';
-
-export interface HomeProps {
-  message: string;
+@Get(':id')
+@Render(ProductDetail)
+async getProduct(@Param('id') id: string) {
+  return { product: await this.productService.findById(id) };
 }
+```
 
-export default function Home(props: PageProps<HomeProps>) {
-  return <h1>{props.message}</h1>;
+```tsx
+export default function ProductDetail({
+  data,
+}: PageProps<{ product: Product }>) {
+  return <h1>{data.product.name}</h1>;
 }
 ```
 
-**3. Use in a controller**
+Type mismatch = build fails.
+
+## Test in Isolation
 
 ```typescript
-// app.controller.ts
-import { Controller, Get } from '@nestjs/common';
-import { Render } from '@nestjs-ssr/react';
-import Home from './views/home';
-
-@Controller()
-export class AppController {
-  @Get()
-  @Render(Home)
-  getHome() {
-    return { message: 'Hello World' };  // TypeScript validates this!
-  }
-}
+// Controller: no React
+expect(await controller.getProduct('123')).toEqual({ product: { id: '123' } });
+
+// Component: no NestJS
+render(<ProductDetail data={{ product: mockProduct }} />);
 ```
 
-That's it! Run `npm run dev` and visit http://localhost:3000
+## Features
 
-## API
+**Rendering:**
 
-### React Hooks
+- Type-safe data flow from controller to component
+- Hierarchical layouts (module → controller → method)
+- Head tags via decorators (title, meta, OG, JSON-LD)
 
-```typescript
-import { usePageContext, useParams, useQuery } from '@nestjs-ssr/react';
+**Request Context:**
 
-function MyComponent() {
-  const context = usePageContext();  // { url, path, query, params, ... }
-  const params = useParams();        // Route params
-  const query = useQuery();          // Query string
-  return <div>User ID: {params.id}</div>;
-}
-```
+- Hooks: params, query, headers, session, user agent
+- Whitelist what reaches the client
 
-### Head Tags & SEO
+**Development:**
 
-```typescript
-import { Head } from '@nestjs-ssr/react';
-
-export default function MyPage(props: PageProps<MyProps>) {
-  return (
-    <>
-      <Head>
-        <title>My Page</title>
-        <meta name="description" content="Page description" />
-      </Head>
-      <div>{props.content}</div>
-    </>
-  );
-}
-```
+- Integrated mode: one process, full refresh
+- Proxy mode: separate Vite, true HMR
 
-## Documentation
+## Docs
 
-- [Full Documentation](https://georgialexandrov.github.io/nestjs-ssr/)
-- [Examples](https://github.com/georgialexandrov/nestjs-ssr/tree/main/examples)
-- [GitHub](https://github.com/georgialexandrov/nestjs-ssr)
+[Full documentation →](https://georgialexandrov.github.io/nest-ssr/)
 
-## Requirements
+## Examples
 
-- Node.js 20+
-- NestJS 11+
-- React 19+
-- TypeScript 5+
+**[Minimal](./examples/minimal/)** - Simplest setup with integrated Vite mode
+**[Minimal HMR](./examples/minimal-hmr/)** - Dual-server architecture for full HMR
 
 ## License
 
-MIT © [Georgi Alexandrov](https://github.com/georgialexandrov)
+MIT

package/dist/cli/init.js

@@ -32,6 +32,10 @@ var main = citty.defineCommand({
       type: "boolean",
       description: "Skip automatic dependency installation",
       default: false
+    },
+    integration: {
+      type: "string",
+      description: 'Integration type: "separate" (Vite as separate server) or "integrated" (Vite bundled with NestJS)'
     }
   },
   async run({ args }) {
@@ -39,6 +43,32 @@ var main = citty.defineCommand({
     const viewsDir = args.views;
     consola.consola.box("@nestjs-ssr/react initialization");
     consola.consola.start("Setting up your NestJS SSR React project...\n");
+    let integrationType = args.integration;
+    if (!integrationType) {
+      const response = await consola.consola.prompt("How do you want to run Vite during development?", {
+        type: "select",
+        options: [
+          {
+            label: "Separate server (Vite runs on its own port, e.g., 5173)",
+            value: "separate"
+          },
+          {
+            label: "Integrated with NestJS (Vite middleware runs within NestJS)",
+            value: "integrated"
+          }
+        ]
+      });
+      integrationType = response;
+    }
+    if (![
+      "separate",
+      "integrated"
+    ].includes(integrationType)) {
+      consola.consola.error(`Invalid integration type: "${integrationType}". Must be "separate" or "integrated"`);
+      process.exit(1);
+    }
+    consola.consola.info(`Using ${integrationType === "separate" ? "separate server" : "integrated"} mode
+`);
     const templateLocations = [
       path.resolve(__dirname$1, "../../src/templates"),
       path.resolve(__dirname$1, "../templates")
@@ -76,6 +106,15 @@ var main = citty.defineCommand({
       fs.copyFileSync(entryServerSrc, entryServerDest);
       consola.consola.success(`Created ${viewsDir}/entry-server.tsx`);
     }
+    consola.consola.start("Creating index.html...");
+    const indexHtmlSrc = path.join(templateDir, "index.html");
+    const indexHtmlDest = path.join(cwd, viewsDir, "index.html");
+    if (fs.existsSync(indexHtmlDest) && !args.force) {
+      consola.consola.warn(`${viewsDir}/index.html already exists (use --force to overwrite)`);
+    } else {
+      fs.copyFileSync(indexHtmlSrc, indexHtmlDest);
+      consola.consola.success(`Created ${viewsDir}/index.html`);
+    }
     consola.consola.start("Configuring vite.config.js...");
     const viteConfigPath = path.join(cwd, "vite.config.js");
     const viteConfigTs = path.join(cwd, "vite.config.ts");
@@ -85,12 +124,28 @@ var main = citty.defineCommand({
       consola.consola.warn(`${useTypeScript ? "vite.config.ts" : "vite.config.js"} already exists`);
       consola.consola.info("Please manually add to your Vite config:");
       consola.consola.log("  import { resolve } from 'path';");
+      if (integrationType === "separate") {
+        consola.consola.log("  server: {");
+        consola.consola.log("    port: 5173,");
+        consola.consola.log("    strictPort: true,");
+        consola.consola.log("    hmr: { port: 5173 },");
+        consola.consola.log("  },");
+      }
       consola.consola.log("  build: {");
       consola.consola.log("    rollupOptions: {");
       consola.consola.log(`      input: { client: resolve(__dirname, '${viewsDir}/entry-client.tsx') }`);
       consola.consola.log("    }");
       consola.consola.log("  }");
     } else {
+      const serverConfig = integrationType === "separate" ? `  server: {
+    port: 5173,
+    strictPort: true,
+    hmr: { port: 5173 },
+  },
+  ` : `  server: {
+    middlewareMode: true,
+  },
+  `;
       const viteConfig = `import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { resolve } from 'path';
@@ -102,12 +157,7 @@ export default defineConfig({
       '@': resolve(__dirname, 'src'),
     },
   },
-  server: {
-    port: 5173,
-    strictPort: true,
-    hmr: { port: 5173 },
-  },
-  build: {
+${serverConfig}build: {
     outDir: 'dist/client',
     manifest: true,
     rollupOptions: {
@@ -249,6 +299,16 @@ export default defineConfig({
           packageJson.scripts["build:server"] = `vite build --ssr ${viewsDir}/entry-server.tsx --outDir dist/server`;
           shouldUpdate = true;
         }
+        if (integrationType === "separate") {
+          if (!packageJson.scripts["dev:client"]) {
+            packageJson.scripts["dev:client"] = "vite";
+            shouldUpdate = true;
+          }
+          if (!packageJson.scripts["dev:server"]) {
+            packageJson.scripts["dev:server"] = "nest start --watch";
+            shouldUpdate = true;
+          }
+        }
         const existingBuild = packageJson.scripts.build;
         const recommendedBuild = "pnpm build:client && pnpm build:server && nest build";
         if (!existingBuild) {
@@ -269,9 +329,9 @@ export default defineConfig({
         if (!args["skip-install"]) {
           consola.consola.start("Checking dependencies...");
           const requiredDeps = {
-            "react": "^19.0.0",
+            react: "^19.0.0",
             "react-dom": "^19.0.0",
-            "vite": "^7.0.0",
+            vite: "^7.0.0",
             "@vitejs/plugin-react": "^4.0.0"
           };
           const missingDeps = [];
@@ -311,9 +371,26 @@ export default defineConfig({
     }
     consola.consola.success("\nInitialization complete!");
     consola.consola.box("Next steps");
-    consola.consola.info(`1. Create your first view component in ${viewsDir}/`);
-    consola.consola.info("2. Render it from a NestJS controller using render.render()");
-    consola.consola.info("3. Run your dev server with: pnpm start:dev");
+    consola.consola.info("1. Register RenderModule in your app.module.ts:");
+    consola.consola.log('   import { RenderModule } from "@nestjs-ssr/react";');
+    consola.consola.log("   @Module({");
+    consola.consola.log("     imports: [RenderModule.forRoot()],");
+    consola.consola.log("   })");
+    consola.consola.info(`
+2. Create your first view component in ${viewsDir}/`);
+    consola.consola.info("3. Add a controller method with the @Render decorator:");
+    consola.consola.log('   import { Render } from "@nestjs-ssr/react";');
+    consola.consola.log("   @Get()");
+    consola.consola.log('   @Render("YourComponent")');
+    consola.consola.log('   home() { return { props: { message: "Hello" } }; }');
+    if (integrationType === "separate") {
+      consola.consola.info("\n4. Start both servers:");
+      consola.consola.log("   Terminal 1: pnpm dev:client  (Vite on port 5173)");
+      consola.consola.log("   Terminal 2: pnpm dev:server  (NestJS)");
+    } else {
+      consola.consola.info("\n4. Start the dev server: pnpm start:dev");
+      consola.consola.info("   (Vite middleware will be integrated into NestJS)");
+    }
   }
 });
 citty.runMain(main);

package/dist/cli/init.mjs

@@ -29,6 +29,10 @@ var main = defineCommand({
       type: "boolean",
       description: "Skip automatic dependency installation",
       default: false
+    },
+    integration: {
+      type: "string",
+      description: 'Integration type: "separate" (Vite as separate server) or "integrated" (Vite bundled with NestJS)'
     }
   },
   async run({ args }) {
@@ -36,6 +40,32 @@ var main = defineCommand({
     const viewsDir = args.views;
     consola.box("@nestjs-ssr/react initialization");
     consola.start("Setting up your NestJS SSR React project...\n");
+    let integrationType = args.integration;
+    if (!integrationType) {
+      const response = await consola.prompt("How do you want to run Vite during development?", {
+        type: "select",
+        options: [
+          {
+            label: "Separate server (Vite runs on its own port, e.g., 5173)",
+            value: "separate"
+          },
+          {
+            label: "Integrated with NestJS (Vite middleware runs within NestJS)",
+            value: "integrated"
+          }
+        ]
+      });
+      integrationType = response;
+    }
+    if (![
+      "separate",
+      "integrated"
+    ].includes(integrationType)) {
+      consola.error(`Invalid integration type: "${integrationType}". Must be "separate" or "integrated"`);
+      process.exit(1);
+    }
+    consola.info(`Using ${integrationType === "separate" ? "separate server" : "integrated"} mode
+`);
     const templateLocations = [
       resolve(__dirname$1, "../../src/templates"),
       resolve(__dirname$1, "../templates")
@@ -73,6 +103,15 @@ var main = defineCommand({
       copyFileSync(entryServerSrc, entryServerDest);
       consola.success(`Created ${viewsDir}/entry-server.tsx`);
     }
+    consola.start("Creating index.html...");
+    const indexHtmlSrc = join(templateDir, "index.html");
+    const indexHtmlDest = join(cwd, viewsDir, "index.html");
+    if (existsSync(indexHtmlDest) && !args.force) {
+      consola.warn(`${viewsDir}/index.html already exists (use --force to overwrite)`);
+    } else {
+      copyFileSync(indexHtmlSrc, indexHtmlDest);
+      consola.success(`Created ${viewsDir}/index.html`);
+    }
     consola.start("Configuring vite.config.js...");
     const viteConfigPath = join(cwd, "vite.config.js");
     const viteConfigTs = join(cwd, "vite.config.ts");
@@ -82,12 +121,28 @@ var main = defineCommand({
       consola.warn(`${useTypeScript ? "vite.config.ts" : "vite.config.js"} already exists`);
       consola.info("Please manually add to your Vite config:");
       consola.log("  import { resolve } from 'path';");
+      if (integrationType === "separate") {
+        consola.log("  server: {");
+        consola.log("    port: 5173,");
+        consola.log("    strictPort: true,");
+        consola.log("    hmr: { port: 5173 },");
+        consola.log("  },");
+      }
       consola.log("  build: {");
       consola.log("    rollupOptions: {");
       consola.log(`      input: { client: resolve(__dirname, '${viewsDir}/entry-client.tsx') }`);
       consola.log("    }");
       consola.log("  }");
     } else {
+      const serverConfig = integrationType === "separate" ? `  server: {
+    port: 5173,
+    strictPort: true,
+    hmr: { port: 5173 },
+  },
+  ` : `  server: {
+    middlewareMode: true,
+  },
+  `;
       const viteConfig = `import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { resolve } from 'path';
@@ -99,12 +154,7 @@ export default defineConfig({
       '@': resolve(__dirname, 'src'),
     },
   },
-  server: {
-    port: 5173,
-    strictPort: true,
-    hmr: { port: 5173 },
-  },
-  build: {
+${serverConfig}build: {
     outDir: 'dist/client',
     manifest: true,
     rollupOptions: {
@@ -246,6 +296,16 @@ export default defineConfig({
           packageJson.scripts["build:server"] = `vite build --ssr ${viewsDir}/entry-server.tsx --outDir dist/server`;
           shouldUpdate = true;
         }
+        if (integrationType === "separate") {
+          if (!packageJson.scripts["dev:client"]) {
+            packageJson.scripts["dev:client"] = "vite";
+            shouldUpdate = true;
+          }
+          if (!packageJson.scripts["dev:server"]) {
+            packageJson.scripts["dev:server"] = "nest start --watch";
+            shouldUpdate = true;
+          }
+        }
         const existingBuild = packageJson.scripts.build;
         const recommendedBuild = "pnpm build:client && pnpm build:server && nest build";
         if (!existingBuild) {
@@ -266,9 +326,9 @@ export default defineConfig({
         if (!args["skip-install"]) {
           consola.start("Checking dependencies...");
           const requiredDeps = {
-            "react": "^19.0.0",
+            react: "^19.0.0",
             "react-dom": "^19.0.0",
-            "vite": "^7.0.0",
+            vite: "^7.0.0",
             "@vitejs/plugin-react": "^4.0.0"
           };
           const missingDeps = [];
@@ -308,9 +368,26 @@ export default defineConfig({
     }
     consola.success("\nInitialization complete!");
     consola.box("Next steps");
-    consola.info(`1. Create your first view component in ${viewsDir}/`);
-    consola.info("2. Render it from a NestJS controller using render.render()");
-    consola.info("3. Run your dev server with: pnpm start:dev");
+    consola.info("1. Register RenderModule in your app.module.ts:");
+    consola.log('   import { RenderModule } from "@nestjs-ssr/react";');
+    consola.log("   @Module({");
+    consola.log("     imports: [RenderModule.forRoot()],");
+    consola.log("   })");
+    consola.info(`
+2. Create your first view component in ${viewsDir}/`);
+    consola.info("3. Add a controller method with the @Render decorator:");
+    consola.log('   import { Render } from "@nestjs-ssr/react";');
+    consola.log("   @Get()");
+    consola.log('   @Render("YourComponent")');
+    consola.log('   home() { return { props: { message: "Hello" } }; }');
+    if (integrationType === "separate") {
+      consola.info("\n4. Start both servers:");
+      consola.log("   Terminal 1: pnpm dev:client  (Vite on port 5173)");
+      consola.log("   Terminal 2: pnpm dev:server  (NestJS)");
+    } else {
+      consola.info("\n4. Start the dev server: pnpm start:dev");
+      consola.info("   (Vite middleware will be integrated into NestJS)");
+    }
   }
 });
 runMain(main);