@nestjs-ssr/react 0.2.0 → 0.2.2

package/README.md

@@ -27,7 +27,7 @@ Clean Architecture: layers separated, dependencies inward, business logic framew
 ## Quick Start
 
 ```bash
-npx nestjs-ssr init
+npx @nestjs-ssr/react  init
 ```
 
 ```typescript

package/dist/cli/init.js

@@ -32,13 +32,80 @@ 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 }) {
     const cwd = process.cwd();
     const viewsDir = args.views;
+    const packageJsonPath = path.join(cwd, "package.json");
+    const tsconfigPath = path.join(cwd, "tsconfig.json");
     consola.consola.box("@nestjs-ssr/react initialization");
     consola.consola.start("Setting up your NestJS SSR React project...\n");
+    if (!fs.existsSync(packageJsonPath)) {
+      consola.consola.error("No package.json found in current directory");
+      consola.consola.info("Please run this command from your NestJS project root");
+      process.exit(1);
+    }
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+      const allDeps = {
+        ...packageJson.dependencies,
+        ...packageJson.devDependencies
+      };
+      const requiredNestDeps = [
+        "@nestjs/core",
+        "@nestjs/common"
+      ];
+      const missingNestDeps = requiredNestDeps.filter((dep) => !allDeps[dep]);
+      if (missingNestDeps.length > 0) {
+        consola.consola.error("This does not appear to be a NestJS project. Missing packages:");
+        consola.consola.info(`  ${missingNestDeps.join(", ")}`);
+        consola.consola.info("\nPlease install NestJS first:");
+        consola.consola.info("  npm install @nestjs/core @nestjs/common @nestjs/platform-express");
+        consola.consola.info("\nOr create a new NestJS project:");
+        consola.consola.info("  npm i -g @nestjs/cli");
+        consola.consola.info("  nest new my-project");
+        process.exit(1);
+      }
+      const mainTsPath2 = path.join(cwd, "src/main.ts");
+      if (!fs.existsSync(mainTsPath2)) {
+        consola.consola.warn("No src/main.ts file found");
+        consola.consola.info("Make sure your NestJS application has a main entry point");
+      }
+    } catch (error) {
+      consola.consola.error("Failed to validate package.json:", error);
+      process.exit(1);
+    }
+    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")
@@ -49,7 +116,6 @@ var main = citty.defineCommand({
       consola.consola.info("Searched:", templateLocations);
       process.exit(1);
     }
-    const tsconfigPath = path.join(cwd, "tsconfig.json");
     if (!fs.existsSync(tsconfigPath)) {
       consola.consola.error("No tsconfig.json found in project root");
       consola.consola.info("Please create a tsconfig.json file first");
@@ -76,21 +142,45 @@ var main = citty.defineCommand({
       fs.copyFileSync(entryServerSrc, entryServerDest);
       consola.consola.success(`Created ${viewsDir}/entry-server.tsx`);
     }
-    consola.consola.start("Configuring vite.config.js...");
-    const viteConfigPath = path.join(cwd, "vite.config.js");
+    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.ts...");
     const viteConfigTs = path.join(cwd, "vite.config.ts");
-    const useTypeScript = fs.existsSync(viteConfigTs);
-    const configPath = useTypeScript ? viteConfigTs : viteConfigPath;
-    if (fs.existsSync(configPath)) {
-      consola.consola.warn(`${useTypeScript ? "vite.config.ts" : "vite.config.js"} already exists`);
+    const viteConfigJs = path.join(cwd, "vite.config.js");
+    const existingConfig = fs.existsSync(viteConfigTs) || fs.existsSync(viteConfigJs);
+    if (existingConfig) {
+      consola.consola.warn("vite.config 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(`      input: { client: resolve(process.cwd(), '${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';
@@ -99,27 +189,34 @@ export default defineConfig({
   plugins: [react()],
   resolve: {
     alias: {
-      '@': resolve(__dirname, 'src'),
+      '@': resolve(process.cwd(), 'src'),
     },
   },
-  server: {
-    port: 5173,
-    strictPort: true,
-    hmr: { port: 5173 },
-  },
-  build: {
+${serverConfig}build: {
     outDir: 'dist/client',
     manifest: true,
     rollupOptions: {
       input: {
-        client: resolve(__dirname, '${viewsDir}/entry-client.tsx'),
+        client: resolve(process.cwd(), '${viewsDir}/entry-client.tsx'),
+      },
+      // Externalize optional native dependencies that shouldn't be bundled for browser
+      external: (id: string) => {
+        // Externalize fsevents - an optional macOS dependency
+        if (id.includes('/fsevents') || id.endsWith('fsevents')) {
+          return true;
+        }
+        // Externalize .node native addon files
+        if (id.endsWith('.node')) {
+          return true;
+        }
+        return false;
       },
     },
   },
 });
 `;
-      fs.writeFileSync(viteConfigPath, viteConfig);
-      consola.consola.success("Created vite.config.js");
+      fs.writeFileSync(viteConfigTs, viteConfig);
+      consola.consola.success("Created vite.config.ts");
     }
     consola.consola.start("Configuring tsconfig.json...");
     try {
@@ -141,14 +238,13 @@ export default defineConfig({
         ];
         updated = true;
       }
-      if (!tsconfig.include) {
-        tsconfig.include = [];
-      }
-      const hasTsx = tsconfig.include.some((pattern) => pattern.includes("**/*.tsx"));
-      if (!hasTsx) {
-        if (!tsconfig.include.includes("src/**/*.tsx")) {
-          tsconfig.include.push("src/**/*.tsx");
-          updated = true;
+      if (tsconfig.include && tsconfig.include.length > 0) {
+        const hasTsx = tsconfig.include.some((pattern) => pattern.includes("**/*.tsx"));
+        if (!hasTsx) {
+          if (!tsconfig.include.includes("src/**/*.tsx")) {
+            tsconfig.include.push("src/**/*.tsx");
+            updated = true;
+          }
         }
       }
       if (!tsconfig.exclude) {
@@ -230,90 +326,242 @@ export default defineConfig({
     } catch (error) {
       consola.consola.error("Failed to update nest-cli.json:", error);
     }
-    consola.consola.start("Configuring build scripts...");
-    const packageJsonPath = path.join(cwd, "package.json");
-    if (!fs.existsSync(packageJsonPath)) {
-      consola.consola.warn("No package.json found, skipping build script setup");
-    } else {
-      try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-        if (!packageJson.scripts) {
-          packageJson.scripts = {};
+    consola.consola.start("Configuring main.ts...");
+    const mainTsPath = path.join(cwd, "src/main.ts");
+    try {
+      if (fs.existsSync(mainTsPath)) {
+        let mainTs = fs.readFileSync(mainTsPath, "utf-8");
+        if (mainTs.includes("enableShutdownHooks")) {
+          consola.consola.info("main.ts already has enableShutdownHooks()");
+        } else {
+          const createPattern = /(const\s+app\s*=\s*await\s+NestFactory\.create[^;]+;)/;
+          const match = mainTs.match(createPattern);
+          if (match) {
+            const createLine = match[1];
+            const replacement = `${createLine}
+
+  // Enable graceful shutdown for proper Vite cleanup
+  app.enableShutdownHooks();`;
+            mainTs = mainTs.replace(createLine, replacement);
+            fs.writeFileSync(mainTsPath, mainTs);
+            consola.consola.success("Added enableShutdownHooks() to main.ts");
+          } else {
+            consola.consola.warn("Could not find NestFactory.create in main.ts, please add manually:");
+            consola.consola.log("  app.enableShutdownHooks();");
+          }
+        }
+      }
+    } catch (error) {
+      consola.consola.warn("Failed to update main.ts:", error);
+      consola.consola.info("Please manually add to your main.ts after NestFactory.create():");
+      consola.consola.log("  app.enableShutdownHooks();");
+    }
+    consola.consola.start("Configuring app.module.ts...");
+    const appModulePath = path.join(cwd, "src/app.module.ts");
+    try {
+      if (fs.existsSync(appModulePath)) {
+        let appModule = fs.readFileSync(appModulePath, "utf-8");
+        if (appModule.includes("RenderModule")) {
+          consola.consola.info("app.module.ts already has RenderModule");
+        } else {
+          let updated = false;
+          const importStatement = "import { RenderModule } from '@nestjs-ssr/react';";
+          if (!appModule.includes(importStatement)) {
+            const nestImportPattern = /(import\s+.*from\s+['"]@nestjs\/[^'"]+['"];?\n)/g;
+            const matches = [
+              ...appModule.matchAll(nestImportPattern)
+            ];
+            if (matches.length > 0) {
+              const lastMatch = matches[matches.length - 1];
+              const insertPos = lastMatch.index + lastMatch[0].length;
+              appModule = appModule.slice(0, insertPos) + importStatement + "\n" + appModule.slice(insertPos);
+              updated = true;
+            } else {
+              const anyImportPattern = /(import\s+.*from\s+['"][^'"]+['"];?\n)/g;
+              const anyMatches = [
+                ...appModule.matchAll(anyImportPattern)
+              ];
+              if (anyMatches.length > 0) {
+                const lastMatch = anyMatches[anyMatches.length - 1];
+                const insertPos = lastMatch.index + lastMatch[0].length;
+                appModule = appModule.slice(0, insertPos) + importStatement + "\n" + appModule.slice(insertPos);
+                updated = true;
+              }
+            }
+          }
+          const importsPattern = /(imports:\s*\[)([^\]]*)/;
+          const importsMatch = appModule.match(importsPattern);
+          if (importsMatch) {
+            const existingImports = importsMatch[2].trim();
+            const renderModuleConfig = integrationType === "separate" ? "RenderModule.register({ vite: { mode: 'proxy', port: 5173 } })" : "RenderModule.forRoot()";
+            if (existingImports === "") {
+              appModule = appModule.replace(importsPattern, `$1${renderModuleConfig}`);
+            } else {
+              appModule = appModule.replace(importsPattern, `$1$2, ${renderModuleConfig}`);
+            }
+            updated = true;
+          }
+          if (updated) {
+            fs.writeFileSync(appModulePath, appModule);
+            consola.consola.success("Added RenderModule to app.module.ts");
+          } else {
+            consola.consola.warn("Could not automatically update app.module.ts, please add manually:");
+            consola.consola.log(`  import { RenderModule } from '@nestjs-ssr/react';`);
+            consola.consola.log("  // In @Module imports:");
+            consola.consola.log("  RenderModule.forRoot()");
+          }
         }
-        let shouldUpdate = false;
-        if (!packageJson.scripts["build:client"]) {
-          packageJson.scripts["build:client"] = "vite build --ssrManifest --outDir dist/client";
+      } else {
+        consola.consola.warn("No src/app.module.ts found");
+        consola.consola.info("Please manually add RenderModule to your app module");
+      }
+    } catch (error) {
+      consola.consola.warn("Failed to update app.module.ts:", error);
+      consola.consola.info("Please manually add to your app.module.ts:");
+      consola.consola.log(`  import { RenderModule } from '@nestjs-ssr/react';`);
+      consola.consola.log("  // In @Module imports:");
+      consola.consola.log("  RenderModule.forRoot()");
+    }
+    consola.consola.start("Configuring build scripts...");
+    try {
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
+      if (!packageJson.scripts) {
+        packageJson.scripts = {};
+      }
+      let shouldUpdate = false;
+      if (!packageJson.scripts["build:client"]) {
+        packageJson.scripts["build:client"] = `vite build --ssrManifest --outDir dist/client && cp ${viewsDir}/index.html dist/client/index.html`;
+        shouldUpdate = true;
+      }
+      if (!packageJson.scripts["build:server"]) {
+        packageJson.scripts["build:server"] = `vite build --ssr ${viewsDir}/entry-server.tsx --outDir dist/server`;
+        shouldUpdate = true;
+      }
+      if (integrationType === "separate") {
+        if (!packageJson.scripts["dev:vite"]) {
+          packageJson.scripts["dev:vite"] = "vite --port 5173";
           shouldUpdate = true;
         }
-        if (!packageJson.scripts["build:server"]) {
-          packageJson.scripts["build:server"] = `vite build --ssr ${viewsDir}/entry-server.tsx --outDir dist/server`;
+        if (!packageJson.scripts["dev:nest"]) {
+          packageJson.scripts["dev:nest"] = "nest start --watch --watchAssets --preserveWatchOutput";
           shouldUpdate = true;
         }
-        const existingBuild = packageJson.scripts.build;
-        const recommendedBuild = "pnpm build:client && pnpm build:server && nest build";
-        if (!existingBuild) {
+        packageJson.scripts["start:dev"] = 'concurrently --raw -n vite,nest -c cyan,green "pnpm:dev:vite" "pnpm:dev:nest"';
+        shouldUpdate = true;
+      }
+      const existingBuild = packageJson.scripts.build;
+      const recommendedBuild = "nest build && pnpm build:client && pnpm build:server";
+      if (!existingBuild) {
+        packageJson.scripts.build = recommendedBuild;
+        shouldUpdate = true;
+        consola.consola.success("Created build script");
+      } else if (existingBuild !== recommendedBuild) {
+        if (!existingBuild.includes("build:client") || !existingBuild.includes("build:server")) {
+          consola.consola.warn(`Found existing build script: "${existingBuild}"`);
+          consola.consola.info(`Updating to: ${recommendedBuild}`);
           packageJson.scripts.build = recommendedBuild;
           shouldUpdate = true;
-        } else if (!existingBuild.includes("build:client") || !existingBuild.includes("build:server")) {
-          consola.consola.warn(`Found existing build script: "${existingBuild}"`);
-          consola.consola.info("SSR requires building client and server bundles");
-          consola.consola.info(`Recommended: ${recommendedBuild}`);
-          consola.consola.info("Please manually update your build script in package.json");
         } else {
           consola.consola.info("Build scripts already configured");
         }
-        if (shouldUpdate) {
-          fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
-          consola.consola.success("Updated build scripts in package.json");
+      } else {
+        consola.consola.info("Build scripts already configured");
+      }
+      if (shouldUpdate) {
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+        consola.consola.success("Updated build scripts in package.json");
+      }
+      if (!args["skip-install"]) {
+        consola.consola.start("Checking dependencies...");
+        const requiredDeps = {
+          react: "^19.0.0",
+          "react-dom": "^19.0.0",
+          vite: "^7.0.0",
+          "@vitejs/plugin-react": "^4.0.0"
+        };
+        const requiredDevDeps = {
+          "@types/react": "^19.0.0",
+          "@types/react-dom": "^19.0.0"
+        };
+        if (integrationType === "separate") {
+          requiredDeps["http-proxy-middleware"] = "^3.0.0";
+          requiredDevDeps["concurrently"] = "^9.0.0";
         }
-        if (!args["skip-install"]) {
-          consola.consola.start("Checking dependencies...");
-          const requiredDeps = {
-            react: "^19.0.0",
-            "react-dom": "^19.0.0",
-            vite: "^7.0.0",
-            "@vitejs/plugin-react": "^4.0.0"
-          };
-          const missingDeps = [];
-          const allDeps = {
-            ...packageJson.dependencies,
-            ...packageJson.devDependencies
-          };
-          for (const [dep, version] of Object.entries(requiredDeps)) {
-            if (!allDeps[dep]) {
-              missingDeps.push(`${dep}@${version}`);
-            }
+        const missingDeps = [];
+        const missingDevDeps = [];
+        const allDeps = {
+          ...packageJson.dependencies,
+          ...packageJson.devDependencies
+        };
+        for (const [dep, version] of Object.entries(requiredDeps)) {
+          if (!allDeps[dep]) {
+            missingDeps.push(`${dep}@${version}`);
           }
-          if (missingDeps.length > 0) {
-            consola.consola.info(`Missing dependencies: ${missingDeps.join(", ")}`);
-            let packageManager = "npm";
-            if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) packageManager = "pnpm";
-            else if (fs.existsSync(path.join(cwd, "yarn.lock"))) packageManager = "yarn";
-            const installCmd = packageManager === "npm" ? `npm install ${missingDeps.join(" ")}` : `${packageManager} add ${missingDeps.join(" ")}`;
-            try {
-              consola.consola.start(`Installing dependencies with ${packageManager}...`);
-              child_process.execSync(installCmd, {
-                cwd,
-                stdio: "inherit"
-              });
-              consola.consola.success("Dependencies installed!");
-            } catch (error) {
-              consola.consola.error("Failed to install dependencies:", error);
-              consola.consola.info(`Please manually run: ${installCmd}`);
-            }
-          } else {
-            consola.consola.success("All required dependencies are already installed");
+        }
+        for (const [dep, version] of Object.entries(requiredDevDeps)) {
+          if (!allDeps[dep]) {
+            missingDevDeps.push(`${dep}@${version}`);
+          }
+        }
+        let packageManager = "npm";
+        if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) packageManager = "pnpm";
+        else if (fs.existsSync(path.join(cwd, "yarn.lock"))) packageManager = "yarn";
+        if (missingDeps.length > 0) {
+          consola.consola.info(`Missing dependencies: ${missingDeps.join(", ")}`);
+          const installCmd = packageManager === "npm" ? `npm install ${missingDeps.join(" ")}` : `${packageManager} add ${missingDeps.join(" ")}`;
+          try {
+            consola.consola.start(`Installing dependencies with ${packageManager}...`);
+            child_process.execSync(installCmd, {
+              cwd,
+              stdio: "inherit"
+            });
+            consola.consola.success("Dependencies installed!");
+          } catch (error) {
+            consola.consola.error("Failed to install dependencies:", error);
+            consola.consola.info(`Please manually run: ${installCmd}`);
+          }
+        }
+        if (missingDevDeps.length > 0) {
+          consola.consola.info(`Missing dev dependencies: ${missingDevDeps.join(", ")}`);
+          const installDevCmd = packageManager === "npm" ? `npm install -D ${missingDevDeps.join(" ")}` : `${packageManager} add -D ${missingDevDeps.join(" ")}`;
+          try {
+            consola.consola.start(`Installing dev dependencies with ${packageManager}...`);
+            child_process.execSync(installDevCmd, {
+              cwd,
+              stdio: "inherit"
+            });
+            consola.consola.success("Dev dependencies installed!");
+          } catch (error) {
+            consola.consola.error("Failed to install dev dependencies:", error);
+            consola.consola.info(`Please manually run: ${installDevCmd}`);
           }
         }
-      } catch (error) {
-        consola.consola.error("Failed to update package.json:", error);
+        if (missingDeps.length === 0 && missingDevDeps.length === 0) {
+          consola.consola.success("All required dependencies are already installed");
+        }
       }
+    } catch (error) {
+      consola.consola.error("Failed to update package.json:", error);
     }
     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("2. 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(Home)");
+    consola.consola.log('   home() { return { message: "Hello" }; }');
+    if (integrationType === "separate") {
+      consola.consola.info("\n3. Start development with HMR:");
+      consola.consola.log("   pnpm start:dev");
+      consola.consola.info("   This runs both Vite (port 5173) and NestJS concurrently");
+      consola.consola.info("\n   Or run them separately:");
+      consola.consola.log("   Terminal 1: pnpm dev:vite");
+      consola.consola.log("   Terminal 2: pnpm dev:nest");
+    } else {
+      consola.consola.info("\n3. Start the dev server: pnpm start:dev");
+      consola.consola.info("   (Vite middleware will be integrated into NestJS)");
+    }
   }
 });
 citty.runMain(main);