next-vite-router 1.0.4 → 1.0.5

package/README.md

@@ -16,6 +16,51 @@ yarn add next-vite-router
 
 The package has peer dependencies: React, React DOM and React Router DOM. Make sure your project already includes compatible versions (React 18+ is recommended).
 
+## CLI / Getting Started
+
+The quickest way to start a new project with `next-vite-router` is to use the interactive CLI:
+
+```bash
+npx next-vite-router init
+# or
+pnpm dlx next-vite-router init
+# or
+yarn dlx next-vite-router init
+# or
+bunx next-vite-router init
+```
+
+The CLI will prompt you for:
+
+1. **Project name**  name of the folder to create
+2. **Template**  which React Vite variant to use:
+   - `react-ts` (React + TypeScript)
+   - `react-swc-ts` (React + SWC + TypeScript)
+   - `react-compiler-ts` (React Compiler + TypeScript)
+3. **Src folder**  whether to keep source files in `src/` (recommended) or place them at the project root
+4. **Tailwind CSS**  whether to add and configure Tailwind CSS (with `@tailwindcss/vite`)
+
+### What the CLI does
+
+The CLI automates the entire setup:
+
+- Scaffolds a new Vite + React project using `create-vite`
+- Installs `next-vite-router` and `react-router-dom@latest`
+- Configures the Vite plugin in `vite.config.ts`
+- Sets up path aliases (`@/*`) in `tsconfig.json` and Vite config
+- Creates TypeScript declarations for the virtual module (`virtual:next-vite-router`)
+- Generates example pages (`app/page.tsx`, `app/layout.tsx`, `app/example/page.tsx`)
+- Optionally configures Tailwind CSS with `@tailwindcss/vite` and creates `global.css`
+
+After the CLI finishes:
+
+```bash
+cd <your-project-name>
+pnpm dev
+```
+
+Your app is ready with file-based routing!
+
 ## Quick Start  Vite plugin
 
 The recommended and easiest way to use this library in a Vite app is via the Vite plugin. The plugin exposes a virtual module `virtual:next-vite-router` that provides a `generateRoutes()` function and re-exports `useRoutes` from `react-router-dom` for convenience.

package/dist/cli.cjs

@@ -0,0 +1,527 @@
+"use strict";
+const commander = require("commander");
+const node_child_process = require("node:child_process");
+const child_process = require("child_process");
+const prompts = require("prompts");
+const fs = require("fs");
+const path = require("path");
+function isAvailable(cmd) {
+  try {
+    node_child_process.execSync(`${cmd} --version`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function detectFromUserAgent() {
+  const ua = process.env.npm_config_user_agent;
+  if (!ua) return null;
+  if (ua.startsWith("pnpm")) return "pnpm";
+  if (ua.startsWith("bun")) return "bun";
+  if (ua.startsWith("yarn")) return "yarn";
+  if (ua.startsWith("npm")) return "npm";
+  return null;
+}
+function detectPackageManager() {
+  const preferred = process.env.PREFERRED_PM ?? void 0;
+  const fromUA = detectFromUserAgent();
+  const candidates = [];
+  if (fromUA) candidates.push(fromUA);
+  if (preferred && !candidates.includes(preferred)) candidates.push(preferred);
+  ["pnpm", "bun", "yarn", "npm"].forEach((p) => {
+    const pm2 = p;
+    if (!candidates.includes(pm2)) candidates.push(pm2);
+  });
+  let chosen = null;
+  for (const pm2 of candidates) {
+    if (isAvailable(pm2)) {
+      chosen = pm2;
+      break;
+    }
+  }
+  if (!chosen) {
+    chosen = "npm";
+  }
+  switch (chosen) {
+    case "pnpm":
+      return {
+        name: "pnpm",
+        createProjectCommand: (projectName, template) => `pnpm create vite@latest ${projectName} --template ${template} --no-rolldown`,
+        addDepsCommand: (deps) => `pnpm add ${deps.join(" ")}`,
+        addDevDepsCommand: (deps) => `pnpm add -D ${deps.join(" ")}`,
+        installCommand: "pnpm install"
+      };
+    case "bun":
+      return {
+        name: "bun",
+        createProjectCommand: (projectName, template) => `bun create vite ${projectName} --template=${template} --no-rolldown`,
+        addDepsCommand: (deps) => `bun add ${deps.join(" ")}`,
+        addDevDepsCommand: (deps) => `bun add -d ${deps.join(" ")}`,
+        installCommand: "bun install"
+      };
+    case "yarn":
+      return {
+        name: "yarn",
+        createProjectCommand: (projectName, template) => `yarn create vite ${projectName} --template=${template} --no-rolldown`,
+        addDepsCommand: (deps) => `yarn add ${deps.join(" ")}`,
+        addDevDepsCommand: (deps) => `yarn add -D ${deps.join(" ")}`,
+        installCommand: "yarn install"
+      };
+    case "npm":
+    default:
+      return {
+        name: "npm",
+        createProjectCommand: (projectName, template) => `npm create vite@latest ${projectName} -- --template ${template} --no-rolldown`,
+        addDepsCommand: (deps) => `npm install ${deps.join(" ")}`,
+        addDevDepsCommand: (deps) => `npm install -D ${deps.join(" ")}`,
+        installCommand: "npm install"
+      };
+  }
+}
+let FORCE_COLOR, NODE_DISABLE_COLORS, NO_COLOR, TERM, isTTY = true;
+if (typeof process !== "undefined") {
+  ({ FORCE_COLOR, NODE_DISABLE_COLORS, NO_COLOR, TERM } = process.env || {});
+  isTTY = process.stdout && process.stdout.isTTY;
+}
+const $ = {
+  enabled: !NODE_DISABLE_COLORS && NO_COLOR == null && TERM !== "dumb" && (FORCE_COLOR != null && FORCE_COLOR !== "0" || isTTY)
+};
+function init$1(x, y) {
+  let rgx = new RegExp(`\\x1b\\[${y}m`, "g");
+  let open = `\x1B[${x}m`, close = `\x1B[${y}m`;
+  return function(txt) {
+    if (!$.enabled || txt == null) return txt;
+    return open + (!!~("" + txt).indexOf(close) ? txt.replace(rgx, close + open) : txt) + close;
+  };
+}
+const red = init$1(31, 39);
+const green = init$1(32, 39);
+const yellow = init$1(33, 39);
+const cyan = init$1(36, 39);
+const highlighter = {
+  error: red,
+  warn: yellow,
+  info: cyan,
+  success: green
+};
+const logger = {
+  error(...args) {
+    console.log(highlighter.error(args.join(" ")));
+  },
+  warn(...args) {
+    console.log(highlighter.warn(args.join(" ")));
+  },
+  info(...args) {
+    console.log(highlighter.info(args.join(" ")));
+  },
+  success(...args) {
+    console.log(highlighter.success(args.join(" ")));
+  },
+  log(...args) {
+    console.log(args.join(" "));
+  },
+  break() {
+    console.log("");
+  }
+};
+function getViteConfigPath(projectDir) {
+  const tsPath = path.join(projectDir, "vite.config.ts");
+  const jsPath = path.join(projectDir, "vite.config.js");
+  if (fs.existsSync(tsPath)) return tsPath;
+  if (fs.existsSync(jsPath)) return jsPath;
+  return null;
+}
+function readViteConfig(projectDir) {
+  const configPath = getViteConfigPath(projectDir);
+  if (!configPath) return null;
+  return fs.readFileSync(configPath, "utf-8");
+}
+function writeViteConfig(projectDir, content) {
+  const configPath = getViteConfigPath(projectDir);
+  if (!configPath) throw new Error("Vite config not found");
+  fs.writeFileSync(configPath, content, "utf-8");
+}
+function stripJsonComments(jsonString) {
+  jsonString = jsonString.replace(/\/\/.*$/gm, "");
+  jsonString = jsonString.replace(/\/\*[\s\S]*?\*\//g, "");
+  jsonString = jsonString.replace(/,(\s*[}\]])/g, "$1");
+  return jsonString;
+}
+function updateAppTsConfig(projectDir) {
+  const tsConfigAppPath = path.join(projectDir, "tsconfig.app.json");
+  if (!fs.existsSync(tsConfigAppPath)) return;
+  const content = fs.readFileSync(tsConfigAppPath, "utf-8");
+  const cleanedContent = stripJsonComments(content);
+  const tsConfigApp = JSON.parse(cleanedContent);
+  tsConfigApp.include = [
+    "./**/*.ts",
+    "./**/*.tsx",
+    "virtual-next-vite-router.d.ts"
+  ];
+  fs.writeFileSync(
+    tsConfigAppPath,
+    JSON.stringify(tsConfigApp, null, 2),
+    "utf-8"
+  );
+}
+function updateTsConfigJson(projectDir, src) {
+  const tsConfigPath = path.join(projectDir, "tsconfig.json");
+  if (!fs.existsSync(tsConfigPath)) return;
+  const content = fs.readFileSync(tsConfigPath, "utf-8");
+  const cleanedContent = stripJsonComments(content);
+  const tsConfig = JSON.parse(cleanedContent);
+  if (!tsConfig.compilerOptions) {
+    tsConfig.compilerOptions = {};
+  }
+  tsConfig.compilerOptions.baseUrl = ".";
+  tsConfig.compilerOptions.paths = {
+    "@/*": [src ? "./src/*" : "./*"]
+  };
+  fs.writeFileSync(tsConfigPath, JSON.stringify(tsConfig, null, 2), "utf-8");
+}
+function createVirtualDTS(projectDir, useSrc) {
+  const targetDir = useSrc ? path.join(projectDir, "src") : projectDir;
+  if (useSrc && !fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  const filePath = path.join(targetDir, "virtual-next-vite-router.d.ts");
+  const content = `declare module 'virtual:next-vite-router' {
+  import type { RouteObject } from 'react-router-dom';
+
+  export const generateRoutes: () => RouteObject[];
+  export { useRoutes } from 'react-router-dom';
+}
+`;
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function createMainTSX(projectDir, useSrc) {
+  const targetDir = useSrc ? path.join(projectDir, "src") : projectDir;
+  if (useSrc && !fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  const mainPath = path.join(targetDir, "main.tsx");
+  const content = `import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from "react-router-dom";
+import { generateRoutes, useRoutes } from 'virtual:next-vite-router';
+
+const routes = generateRoutes();
+
+function App() {
+  const element = useRoutes(routes);
+  return element;
+}
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+);
+`;
+  fs.writeFileSync(mainPath, content, "utf-8");
+}
+function createGlobalsCss({ projectDir, src, tailwind }) {
+  const cssDir = src ? path.join(projectDir, "src") : projectDir;
+  const cssPath = path.join(cssDir, "globals.css");
+  if (!fs.existsSync(cssDir)) {
+    fs.mkdirSync(cssDir, { recursive: true });
+  }
+  let content;
+  if (tailwind) {
+    content = '@import "tailwindcss";\n';
+  } else {
+    content = `* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen",
+    "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+html,
+body,
+#root {
+  width: 100%;
+  height: 100%;
+}
+`;
+  }
+  fs.writeFileSync(cssPath, content, "utf-8");
+}
+const layoutContentNoTailwind = `import { Outlet } from "react-router-dom";
+import "@/globals.css";
+
+export default function Layout() {
+  return (
+    <main>
+      <Outlet />
+    </main>
+  );
+}
+`;
+const layoutContentTailwind = `import { Outlet } from "react-router-dom";
+import "@/globals.css";
+
+export default function Layout() {
+  return (
+    <main className="min-h-screen bg-background">
+      <Outlet />
+    </main>
+  );
+}
+`;
+const pageContentNoTailwind = `export default function Page() {
+  return <h1>Welcome to the next-vite-router project!</h1>;
+}
+`;
+const pageContentTailwind = `export default function Page() {
+  return <h1 className="text-2xl font-bold">Welcome to the next-vite-router project!</h1>;
+}
+`;
+const examplePageContent = `export default function ExamplePage() {
+  return <h1>Welcome to the example page!</h1>;
+}
+`;
+function createExampleStructure(projectDir, src, tailwindcss) {
+  const appDir = src ? path.join(projectDir, "src", "app") : path.join(projectDir, "app");
+  if (!fs.existsSync(appDir)) {
+    fs.mkdirSync(appDir, { recursive: true });
+  }
+  const layoutContent = tailwindcss ? layoutContentTailwind : layoutContentNoTailwind;
+  fs.writeFileSync(path.join(appDir, "layout.tsx"), layoutContent, "utf-8");
+  const pageContent = tailwindcss ? pageContentTailwind : pageContentNoTailwind;
+  fs.writeFileSync(path.join(appDir, "page.tsx"), pageContent, "utf-8");
+  const exampleDir = path.join(appDir, "example");
+  if (!fs.existsSync(exampleDir)) {
+    fs.mkdirSync(exampleDir, { recursive: true });
+  }
+  fs.writeFileSync(
+    path.join(exampleDir, "page.tsx"),
+    examplePageContent,
+    "utf-8"
+  );
+}
+function addTailwindToViteConfig(projectDir) {
+  const content = readViteConfig(projectDir);
+  if (!content) throw new Error("Vite config not found");
+  if (content.includes("@tailwindcss/vite")) {
+    return;
+  }
+  let updatedContent = content;
+  const importRegex = /(import\s+.*from\s+['"].*['"];?\s*\n)+/;
+  const match = updatedContent.match(importRegex);
+  if (match) {
+    const lastImportEnd = match[0].length;
+    updatedContent = updatedContent.slice(0, lastImportEnd) + "import tailwindcss from '@tailwindcss/vite';\n" + updatedContent.slice(lastImportEnd);
+  } else {
+    updatedContent = "import tailwindcss from '@tailwindcss/vite';\n\n" + updatedContent;
+  }
+  const pluginsArrayRegex = /plugins:\s*\[([^\]]*)\]/s;
+  const pluginsMatch = updatedContent.match(pluginsArrayRegex);
+  if (pluginsMatch) {
+    const pluginsContent = pluginsMatch[1];
+    const newPluginsContent = pluginsContent.trim() ? pluginsContent.trimEnd() + ",\n    tailwindcss()" : "\n    tailwindcss()\n  ";
+    updatedContent = updatedContent.replace(
+      pluginsArrayRegex,
+      `plugins: [${newPluginsContent}
+  ]`
+    );
+  } else {
+    const defineConfigRegex = /defineConfig\(\{/;
+    updatedContent = updatedContent.replace(
+      defineConfigRegex,
+      "defineConfig({\n  plugins: [tailwindcss()],"
+    );
+  }
+  writeViteConfig(projectDir, updatedContent);
+}
+const pm$1 = detectPackageManager();
+function startNextViteRouterConfig({
+  projectDir = process.cwd(),
+  src,
+  tailwindcss
+}) {
+  startViteConfig(projectDir, src);
+  const srcPath = path.join(projectDir, "src");
+  if (fs.existsSync(srcPath)) {
+    fs.rmSync(srcPath, { recursive: true, force: true });
+  }
+  updateTsConfigJson(projectDir, src);
+  if (!src) {
+    updateAppTsConfig(projectDir);
+  }
+  createVirtualDTS(projectDir, src);
+  createMainTSX(projectDir, src);
+  if (tailwindcss) {
+    logger.info("Setting up Tailwind CSS...");
+    const addDevDepsCmd = pm$1.addDevDepsCommand([
+      "tailwindcss",
+      "@tailwindcss/vite"
+    ]);
+    child_process.execSync(addDevDepsCmd, { stdio: "inherit", cwd: projectDir });
+    addTailwindToViteConfig(projectDir);
+  }
+  createGlobalsCss({ projectDir, src, tailwind: tailwindcss });
+  createExampleStructure(projectDir, src, tailwindcss);
+}
+function startViteConfig(projectDir, src) {
+  const viteConfigPath = getViteConfigPath(projectDir);
+  if (!viteConfigPath) throw new Error("Vite config not found");
+  let viteConfigContent = readViteConfig(projectDir);
+  if (!viteConfigContent) throw new Error("Vite config empty");
+  if (!viteConfigContent.includes("import { resolve }")) {
+    viteConfigContent = `import { resolve } from "path";
+` + viteConfigContent;
+  }
+  if (!viteConfigContent.includes("import { nextViteRouter }")) {
+    viteConfigContent = `import { nextViteRouter } from "next-vite-router/plugin";
+` + viteConfigContent;
+  }
+  const resolveConfig = `  resolve: {
+    alias: {
+      "@": resolve(__dirname, "./${src ? "src" : "."}"),
+    },
+  },`;
+  const defineConfigRegex = /defineConfig\(\s*{/;
+  if (!viteConfigContent.includes("resolve:")) {
+    viteConfigContent = viteConfigContent.replace(
+      defineConfigRegex,
+      `defineConfig({
+${resolveConfig}
+`
+    );
+  }
+  const pluginsRegex = /plugins\s*:\s*\[(.*?)\]/s;
+  const match = viteConfigContent.match(pluginsRegex);
+  const pluginString = `nextViteRouter({ pagesDir: "${src ? "src/app" : "app"}", pageFile: "page.tsx", layoutFile: "layout.tsx", notFoundFile: "not-found.tsx" })`;
+  if (match) {
+    const existing = match[1].trim();
+    const newPlugins = existing ? `${existing}, ${pluginString}` : pluginString;
+    viteConfigContent = viteConfigContent.replace(
+      pluginsRegex,
+      `plugins: [${newPlugins}]`
+    );
+  } else {
+    viteConfigContent = viteConfigContent.replace(
+      /defineConfig\(\s*{/,
+      `defineConfig({
+  plugins: [${pluginString}],`
+    );
+  }
+  writeViteConfig(projectDir, viteConfigContent);
+}
+const pm = detectPackageManager();
+const init = new commander.Command().name("init").description(
+  "Initialize a new Vite project with next-vite-router configuration"
+).action(async () => {
+  const projectNameResponse = await prompts(
+    {
+      type: "text",
+      name: "projectName",
+      message: "Enter your project name:",
+      initial: "my-next-vite-router-app"
+    },
+    {
+      onCancel: () => {
+        logger.error("Project creation cancelled.");
+        process.exit(1);
+      }
+    }
+  );
+  const projectName = projectNameResponse.projectName;
+  const variantResponse = await prompts(
+    {
+      type: "select",
+      name: "template",
+      message: "Select a template:",
+      choices: [
+        { title: "React + TypeScript", value: "react-ts" },
+        {
+          title: "React + TypeScript (React Compiler)",
+          value: "react-compiler-ts"
+        },
+        { title: "React + SWC (Recommended)", value: "react-swc-ts" }
+      ],
+      initial: 0
+    },
+    {
+      onCancel: () => {
+        logger.error("Template selection cancelled.");
+        process.exit(1);
+      }
+    }
+  );
+  const variant = variantResponse.template;
+  const srcFolderResponse = await prompts(
+    {
+      type: "confirm",
+      name: "useSrc",
+      message: "Do you want to use a 'src' folder?",
+      initial: true
+    },
+    {
+      onCancel: () => {
+        logger.error("Src folder selection cancelled.");
+        process.exit(1);
+      }
+    }
+  );
+  const useSrc = srcFolderResponse.useSrc;
+  const tailwindResponse = await prompts(
+    {
+      type: "confirm",
+      name: "useTailwind",
+      message: "Do you want to set up Tailwind CSS?",
+      initial: true
+    },
+    {
+      onCancel: () => {
+        logger.error("Tailwind CSS setup cancelled.");
+        process.exit(1);
+      }
+    }
+  );
+  const useTailwind = tailwindResponse.useTailwind;
+  const createCommand = pm.createProjectCommand(projectName, variant);
+  logger.info(`Creating project "${projectName}" using ${pm.name}...`);
+  try {
+    child_process.execSync(createCommand, {
+      stdio: ["pipe", "inherit", "inherit"],
+      input: "n\n"
+    });
+  } catch (error) {
+  }
+  logger.info("Installing dependencies...");
+  child_process.execSync(pm.installCommand, { stdio: "inherit", cwd: projectName });
+  logger.info(
+    "Adding next-vite-router and react-router-dom as dependencies..."
+  );
+  const addDepsCmd = pm.addDepsCommand([
+    "next-vite-router",
+    "react-router-dom@latest"
+  ]);
+  child_process.execSync(addDepsCmd, { stdio: "inherit", cwd: projectName });
+  logger.info("Configuring next-vite-router in the project...");
+  startNextViteRouterConfig({
+    projectDir: `./${projectName}`,
+    src: useSrc,
+    tailwindcss: useTailwind
+  });
+  logger.success(`
+Project "${projectName}" is ready!
+`);
+});
+async function main() {
+  const program = new commander.Command();
+  program.name("next-vite-router").version("1.0.5").addCommand(init);
+  program.parse(process.argv);
+}
+main();

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "next-vite-router",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Next.js-like file-based routing for React + Vite",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "next-vite-router": "./dist/cli.cjs"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -44,16 +47,23 @@
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "@types/prompts": "^2.4.9",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
     "typescript": "^5.0.0",
     "vite": "^5.0.0",
     "vite-plugin-dts": "^3.0.0"
   },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  },
   "scripts": {
     "dev": "vite build --watch",
-    "build": "vite build",
+    "build": "vite build && vite build -c vite.config.cli.ts",
     "test:local": "node test/test-package.js",
-    "preview": "pnpm pack --dry-run"
+    "preview": "pnpm pack --dry-run",
+    "cli": "cd test && node ../dist/cli.cjs init"
   }
 }