create-lumen 2.0.0-alpha.2 → 2.0.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # create-lumen
 
-A scaffolder that generates production-ready React + Vite projects (feature-based, type-based, hybrid, or none).
+A scaffolder that generates production-ready **React + Vite** or **Next.js** projects (App Router / Pages Router), with a choice of architecture: feature-based, type-based, hybrid, or none.
 
 Note: this repository is the CLI scaffolder itself, not a generated app. Generated projects live in the target folder you create.
 
@@ -14,6 +14,8 @@ cd my-app
 npm run dev
 ```
 
+> The v2 line (React + Vite + Next.js, manifest v2) is available on the `beta` dist-tag while v2 is in prerelease: `npm create lumen@beta my-app`.
+
 ### Non-interactive flags
 
 Quick Setup (TypeScript + Tailwind + Feature-based + Router + ESLint + Prettier + Vitest), no prompts:
@@ -26,20 +28,28 @@ npm create lumen -- -y my-app
 npm create lumen my-app -- --yes
 ```
 
-Scaffold using a template preset (`react-ts`, `react-js`, `react-type-ts`, `react-type-js`):
+Scaffold using a template preset (`react-ts`, `react-js`, `react-type-ts`, `react-type-js`, `next-ts`, `next-js`, `next-pages-ts`, `next-pages-js`):
 
 ```bash
 npm create lumen my-app -- --template react-ts
 # or
-npm create lumen my-app -- -t react-type-js
+npm create lumen my-app -- -t next-ts
 ```
 
 Choose framework and architecture directly:
 
 ```bash
 npm create lumen my-app -- --framework react --arch none
+
+# Next.js — the router is asked interactively (App Router recommended):
+npm create lumen my-app -- -f next
+# ...or pin the variant outright:
+npm create lumen my-app -- -f next:app-router
+npm create lumen my-app -- -f next:pages-router
 ```
 
+Interactively, the framework is the first prompt (React + Vite / Next.js), followed by a router step when Next.js is selected; every later option gates on that choice.
+
 Drive scaffolding directly from a manifest file or inline JSON (manifest v2):
 
 ```bash
@@ -70,20 +80,25 @@ create-lumen my-app      # after npm link
 
 ## Features
 
+- **Two frameworks:** React + Vite (SPA) or Next.js (App Router / Pages Router) — selected interactively or via `-f`
 - Architecture choice: feature-based, type-based, hybrid, or none (per-framework availability)
 - TypeScript or JavaScript output
 - CSS frameworks: Tailwind CSS v4 (CSS-first `@theme`, v3 dropped) or none
+- **UI kit: shadcn/ui** (gated to Tailwind; primitives + `cn` helper land in the mapped `paths.ui`)
 - Optional state management: Zustand or Redux Toolkit
-- Optional router (React Router)
-- Optional testing: Vitest or Jest
+- Optional router (React Router — Vite only; Next.js uses filesystem routing)
+- Optional testing: Vitest or Jest (Next.js defaults to none until a Next-native overlay is verified)
+- **Next.js-native overlays:** server/client boundary demos + `no-server-imports-in-client` ESLint rule, `next/font` (Geist), `next/image`, filesystem routing examples, route handlers (`route.ts`) / API routes (`pages/api`)
+- **Next.js options:** `bundler: turbopack|webpack`, `adapter: node|vercel|cloudflare|static` (`next.config` overlays), `reactCompiler`, `linter: biome` — all validated against the capability model
 - Linting: ESLint (default), Oxlint, or Biome
 - Code formatter: Prettier or Oxfmt (chosen after the linter; `eslint-config-prettier` is auto-wired for the ESLint + Prettier combo)
-- Manifest v2: Emits a deterministic `lumen.config.json` (optional but recommended) validated against JSON Schema Draft 2020-12, including architecture validation modes and harness command configuration.
+- Manifest v2: Emits a deterministic `lumen.config.json` validated against JSON Schema Draft 2020-12, including architecture validation modes and harness command configuration.
 - Explicit path mapping: Target directories declared for `lumen-cli` code generation
 - Optional Axios setup and icon libraries
 - Auto `git init`, generated `README` (with a project description reflecting the chosen tooling) and `LICENSE`
 - `.env.example` scaffolded, and the generated `.gitignore` excludes env files (`.env`, `.env.*`) while keeping `.env.example`
 - `@/` path alias configured (`tsconfig`/`jsconfig` + Vite)
+- **Agent docs:** optional `.lumen/` context directory (project, architecture, conventions) via prompt or `--agent-docs`
 
 Your selected options are cached and offered as defaults on subsequent runs.
 
@@ -206,6 +221,9 @@ The manifest now includes:
 ### Ecosystem Documentation & Contracts
 
 - **[Documentation Index](./docs/README.md):** Complete overview of specifications, ADRs, and developer guides.
+- **[Next.js App Router Guide](./docs/next-app-router.md):** App Router scaffold, filesystem routing, route handlers, server/client boundaries, `next/font` and `next/image`.
+- **[Next.js Pages Router Guide](./docs/next-pages-router.md):** Pages Router scaffold, API routes, `_app`/`_document` wiring.
+- **[Deployment Adapters Guide](./docs/next-adapters.md):** Adapter matrix (Node, Vercel, Cloudflare, static), bundler choice and Biome setup for Next.js.
 - **[Generator Engine & Capabilities Guide (M2)](./docs/engine-capabilities.md):** Capability model, template composition, shadcn/ui on Tailwind v4, architecture presets, and Bootstrap removal.
 - **[Manifest v2 Overview](./docs/manifest-v2.md):** Specification of the nested schema, validation behavior, and the new harness and architecture validation fields.
 - **[Shared Contract: `create-lumen` ↔ `lumen-cli`](./docs/contracts/manifest-v2-contract.md):** The agreed contract for path mapping, barrel conventions, version negotiation, and the harness/configuration interface.

package/bin/cli.js

@@ -25,7 +25,7 @@ console.log(
   chalk.bold.cyan("\n  ✦ LUMEN") +
     chalk.gray(` v${version}`) +
     chalk.gray(
-      "\n  Scaffold a React + Vite project with architecture choice\n"
+      "\n  Scaffold a React, Vite, or Next.js project with architecture choice\n"
     )
 );
 
@@ -36,6 +36,7 @@ main({
   projectName: cliArgs.projectName,
   manifest: cliArgs.manifest,
   template: cliArgs.template,
+  framework: cliArgs.framework,
   arch: cliArgs.arch,
 }).catch((e) => {
   console.error(chalk.red("\nError:"), e.message || e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumen",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-beta.1",
   "description": "Scaffold a React + Vite project with architecture choice: feature-based, type-based, hybrid, or none.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/LUMEN-SH/create-lumen"
+    "url": "https://github.com/strophix-software/create-lumen"
   },
   "files": [
     "bin/",

package/src/cli-args.js

@@ -6,7 +6,6 @@ import { parseManifest } from "./manifest/schema.js";
 import {
   normalizeFramework,
   isPromptVisible,
-  getDefaultResponses,
 } from "./engine/capabilities.js";
 
 export const PRESETS = {
@@ -180,6 +179,78 @@ export const PRESETS = {
     gitInit: true,
     readme: true,
   },
+  "next-ts": {
+    frameworkName: "next",
+    frameworkVariant: "app-router",
+    architecture: "feature-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: false,
+    bundler: "turbopack",
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "next-js": {
+    frameworkName: "next",
+    frameworkVariant: "app-router",
+    architecture: "feature-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: false,
+    bundler: "turbopack",
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "next-pages-ts": {
+    frameworkName: "next",
+    frameworkVariant: "pages-router",
+    architecture: "feature-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: false,
+    bundler: "turbopack",
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "next-pages-js": {
+    frameworkName: "next",
+    frameworkVariant: "pages-router",
+    architecture: "feature-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: false,
+    bundler: "turbopack",
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
 };
 
 /**
@@ -207,6 +278,13 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
       framework: { type: "string", short: "f" },
       arch: { type: "string", short: "a" },
       architecture: { type: "string" },
+      bundler: { type: "string", short: "b" },
+      adapter: { type: "string" },
+      "react-compiler": { type: "boolean" },
+      reactCompiler: { type: "boolean" },
+      "agent-docs": { type: "boolean" },
+      agentDocs: { type: "boolean" },
+      linter: { type: "string" },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
     },
@@ -223,6 +301,12 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
     else if (arch === "component" || arch === "component-based" || arch === "type") arch = "type-based";
   }
 
+  const bundler = values.bundler ? values.bundler.trim().toLowerCase() : null;
+  const adapter = values.adapter ? values.adapter.trim().toLowerCase() : null;
+  const reactCompiler = values["react-compiler"] ?? values.reactCompiler ?? null;
+  const agentDocs = values["agent-docs"] ?? values.agentDocs ?? null;
+  const linter = values.linter ? values.linter.trim().toLowerCase() : null;
+
   return {
     projectName,
     quickSetup: Boolean(values.yes),
@@ -230,6 +314,11 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
     template: values.template || null,
     framework: values.framework ? values.framework.trim() : null,
     arch,
+    bundler,
+    adapter,
+    reactCompiler,
+    agentDocs,
+    linter,
     help: Boolean(values.help),
     version: Boolean(values.version),
     positionals,
@@ -278,6 +367,8 @@ export function manifestToResponses(manifest, projectName) {
   const framework = normalizeFramework({ name: frameworkName, variant: frameworkVariant });
   const canClientRoute = isPromptVisible(framework, "router");
   const supportsBundler = isPromptVisible(framework, "bundler");
+  const supportsAdapter = isPromptVisible(framework, "adapter");
+  const supportsCompiler = isPromptVisible(framework, "reactCompiler");
 
   return {
     projectName,
@@ -287,7 +378,10 @@ export function manifestToResponses(manifest, projectName) {
       supportsBundler && manifest.framework?.bundler
         ? manifest.framework.bundler
         : undefined,
-    adapter: manifest.framework?.adapter,
+    adapter:
+      supportsAdapter && manifest.framework?.adapter
+        ? manifest.framework.adapter
+        : undefined,
     architecture: manifest.architecture?.type || "feature-based",
     language: manifest.tooling?.language || "ts",
     cssFramework: manifest.styling?.engine || "tailwind",
@@ -295,10 +389,12 @@ export function manifestToResponses(manifest, projectName) {
     formatter: manifest.tooling?.formatter || "prettier",
     uiKit: manifest.ui?.kit || "none",
     docsLanguage: manifest.docs?.language || "en",
-    reactCompiler: manifest.reactCompiler,
+    reactCompiler: supportsCompiler ? manifest.reactCompiler : undefined,
     agentDocs: manifest.agentDocs,
-    // Sensible defaults for scaffolder conditional passes
-    testing: "vitest",
+    // Sensible defaults for scaffolder conditional passes (Next.js ships no
+    // verified test-runner overlay yet, so it defaults to none; explicit
+    // vitest/jest selection still applies the standard overlays)
+    testing: frameworkName === "next" ? "none" : "vitest",
     router: canClientRoute,
     stateManagement: "none",
     iconLibrary: "none",
@@ -335,6 +431,10 @@ ${chalk.bold("PRESETS")}
   ${chalk.cyan("react-type-js")}  React + Vite + JavaScript (type-based)
   ${chalk.cyan("react-none-ts")}  React + Vite + TypeScript (none)
   ${chalk.cyan("react-none-js")}  React + Vite + JavaScript (none)
+  ${chalk.cyan("next-ts")}         Next.js App Router + TypeScript (feature-based)
+  ${chalk.cyan("next-js")}         Next.js App Router + JavaScript (feature-based)
+  ${chalk.cyan("next-pages-ts")}   Next.js Pages Router + TypeScript (feature-based)
+  ${chalk.cyan("next-pages-js")}   Next.js Pages Router + JavaScript (feature-based)
 
 ${chalk.bold("EXAMPLES")}
   ${chalk.gray("# Interactive setup")}

package/src/configure.js

@@ -166,12 +166,16 @@ async function configurePackageJson(projectPath, language) {
 
     if (!pkg.scripts) pkg.scripts = {};
 
-    pkg.scripts.dev = "vite";
-    pkg.scripts.build = "vite build";
-    pkg.scripts.preview = "vite preview";
+    // Fill defaults only — never overwrite scripts owned by the base template
+    // (Next.js bases ship next dev/build/start) or merged overlay fragments
+    // (e.g. the bundler-aware dev script). React/Vite bases already carry the
+    // vite commands, so this is a no-op there too.
+    pkg.scripts.dev ??= "vite";
+    pkg.scripts.build ??= "vite build";
+    pkg.scripts.preview ??= "vite preview";
 
     if (language === "ts") {
-      pkg.scripts.typecheck = "tsc -b";
+      pkg.scripts.typecheck ??= "tsc -b";
     }
 
     await fsp.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");

package/src/dependencies.js

@@ -40,6 +40,10 @@ export async function installAllDeps(responses, pkg, cwd) {
 // the conditional wiring stays verifiable without a network install.
 export function computeDeps(responses) {
   const deps = [];
+  const fwName =
+    typeof responses.framework === "string"
+      ? responses.framework
+      : (responses.framework?.name ?? responses.frameworkName ?? "react");
   const cssDevDeps = [];
   const testingDevDeps = [];
   const linterDevDeps = [];
@@ -47,7 +51,7 @@ export function computeDeps(responses) {
 
   // CSS framework
   if (responses.cssFramework === "tailwind") {
-    if (responses.framework === "next") {
+    if (fwName === "next") {
       cssDevDeps.push("tailwindcss", "@tailwindcss/postcss", "postcss");
     } else {
       cssDevDeps.push("tailwindcss", "@tailwindcss/vite");
@@ -103,7 +107,7 @@ export function computeDeps(responses) {
 
   // Linter
   if (responses.linter === "eslint") {
-    if (responses.framework === "next") {
+    if (fwName === "next") {
       linterDevDeps.push("eslint", "eslint-config-next");
     } else {
       linterDevDeps.push("eslint", "@eslint/js", "eslint-plugin-react-hooks", "eslint-plugin-react-refresh", "globals");
@@ -113,6 +117,8 @@ export function computeDeps(responses) {
     }
   } else if (responses.linter === "oxlint") {
     linterDevDeps.push("oxlint");
+  } else if (responses.linter === "biome") {
+    linterDevDeps.push("@biomejs/biome");
   }
 
   // Formatter

package/src/engine/capabilities.js

@@ -153,6 +153,9 @@ export function isOptionCompatible(framework, optionKey, optionValue) {
     case "bundler":
       return desc.allowedBundlers.includes(optionValue);
     case "adapter":
+      if (optionValue === "none") {
+        return desc.allowedAdapters.length > 0;
+      }
       return desc.allowedAdapters.includes(optionValue);
     case "router":
       // If framework has filesystem routing, external router options (true) are incompatible
@@ -160,6 +163,11 @@ export function isOptionCompatible(framework, optionKey, optionValue) {
         return optionValue === false || optionValue === "none";
       }
       return true;
+    case "reactCompiler":
+      if (optionValue === true) {
+        return hasCapability(framework, CAPABILITIES.REACT_COMPILER);
+      }
+      return true;
     default:
       return true;
   }
@@ -318,10 +326,11 @@ export function getDefaultResponses(framework, { projectName = "my-app" } = {})
       architecture: "feature-based",
       language: "ts",
       cssFramework: "tailwind",
-      testing: "vitest",
+      testing: "none",
       router: false,
       bundler: "turbopack",
       adapter: "none",
+      uiKit: "none",
       stateManagement: "none",
       iconLibrary: "none",
       apiClient: "none",
@@ -342,6 +351,7 @@ export function getDefaultResponses(framework, { projectName = "my-app" } = {})
     cssFramework: "tailwind",
     testing: "vitest",
     router: true,
+    uiKit: "none",
     stateManagement: "none",
     iconLibrary: "none",
     apiClient: "none",
@@ -369,6 +379,17 @@ export function sanitizeResponsesForFramework(framework, responses = {}) {
   if (!isPromptVisible(fw, "router")) {
     sanitized.router = false;
   }
+  if (!isPromptVisible(fw, "bundler")) {
+    delete sanitized.bundler;
+  }
+  if (!isPromptVisible(fw, "adapter")) {
+    delete sanitized.adapter;
+  }
+  if (!isPromptVisible(fw, "reactCompiler")) {
+    if (sanitized.reactCompiler !== undefined) {
+      sanitized.reactCompiler = false;
+    }
+  }
 
   for (const [key, val] of Object.entries(sanitized)) {
     if (val === undefined || val === null) continue;

package/src/engine/composition.js

@@ -44,6 +44,7 @@ export const TOOLING_ORDER = [
   "testing",
   "linter",
   "feature-script",
+  "next-config",
   "formatter",
 ];
 
@@ -149,6 +150,15 @@ export function resolveFragments(responses = {}, templatesDir) {
       try { await fsp.rm(path.join(projectPath, "src", "App.jsx"), { force: true }); } catch {}
       try { await fsp.rm(path.join(projectPath, "src", "index.css"), { force: true }); } catch {}
       try { await fsp.rm(path.join(projectPath, "src", "App.css"), { force: true }); } catch {}
+      if (fw.name === "next") {
+        // Next cleanup: remove Vite defaults without touching app/
+        try { await fsp.rm(path.join(projectPath, "src", "main.tsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "src", "main.jsx"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "index.html"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "vite.config.ts"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "vite.config.js"), { force: true }); } catch {}
+        try { await fsp.rm(path.join(projectPath, "public", "vite.svg"), { force: true }); } catch {}
+      }
     },
   });
 
@@ -406,6 +416,23 @@ export function resolveFragments(responses = {}, templatesDir) {
         } catch {}
       },
     });
+  } else if (responses.linter === "biome") {
+    fragments.push({
+      scope: FRAGMENT_SCOPES.TOOLING,
+      category: "linter",
+      id: "tooling:linter:biome",
+      scripts: {
+        lint: "biome check .",
+        "lint:fix": "biome check --write .",
+      },
+      action: async ({ projectPath }) => {
+        const configSrc = path.join(templatesDir, "conditional", "linting", "biome", "biome.json");
+        try {
+          await fsp.access(configSrc);
+          await fsp.copyFile(configSrc, path.join(projectPath, "biome.json"));
+        } catch {}
+      },
+    });
   }
 
   // 5.7 Feature Script (Feature-based only)
@@ -437,6 +464,71 @@ export function resolveFragments(responses = {}, templatesDir) {
     });
   }
 
+  // 5.75 Next.js Configuration & Adapter Overlays
+  if (fw.name === "next") {
+    const nextScripts = {};
+    if (responses.bundler === "turbopack") {
+      nextScripts.dev = "next dev --turbopack";
+    } else if (responses.bundler === "webpack") {
+      nextScripts.dev = "next dev --webpack";
+    }
+
+    fragments.push({
+      scope: FRAGMENT_SCOPES.TOOLING,
+      category: "next-config",
+      id: "tooling:next:config",
+      scripts: nextScripts,
+      action: async ({ projectPath }) => {
+        const configExt = language === "ts" ? "ts" : "mjs";
+
+        // Apply adapter overlay if specified and not "none"
+        if (responses.adapter && responses.adapter !== "none") {
+          const adapterConfigSrc = path.join(
+            templatesDir,
+            "conditional",
+            "next",
+            "config",
+            responses.adapter,
+            `next.config.${configExt}`
+          );
+          try {
+            await fsp.access(adapterConfigSrc);
+            await fsp.copyFile(adapterConfigSrc, path.join(projectPath, `next.config.${configExt}`));
+          } catch {}
+        } else if (responses.bundler === "turbopack" || responses.bundler === "webpack") {
+          // If no adapter specified, but bundler config overlay exists, apply bundler overlay
+          const bundlerConfigSrc = path.join(
+            templatesDir,
+            "conditional",
+            "next",
+            "config",
+            responses.bundler,
+            `next.config.${configExt}`
+          );
+          try {
+            await fsp.access(bundlerConfigSrc);
+            await fsp.copyFile(bundlerConfigSrc, path.join(projectPath, `next.config.${configExt}`));
+          } catch {}
+        }
+
+        // Apply reactCompiler flag to next.config if enabled
+        if (responses.reactCompiler === true) {
+          const targetConfigPath = path.join(projectPath, `next.config.${configExt}`);
+          try {
+            let content = await fsp.readFile(targetConfigPath, "utf8");
+            if (!content.includes("reactCompiler")) {
+              content = content.replace(
+                /const nextConfig(?::\s*NextConfig)?\s*=\s*\{/,
+                (match) => `${match}\n  reactCompiler: true,`
+              );
+              await fsp.writeFile(targetConfigPath, content, "utf8");
+            }
+          } catch {}
+        }
+      },
+    });
+  }
+
   // 5.8 Formatter
   if (responses.formatter && responses.formatter !== "none") {
     const isPrettier = responses.formatter === "prettier";

package/src/engine/providers/base-provider.js

@@ -125,7 +125,7 @@ export class NextAppRouterProvider extends BaseProvider {
   getPackageSet({ options = {} } = {}) {
     const isTs = options.language === "ts";
     const deps = {
-      next: "^15.0.0",
+      next: "^16.0.0",
       react: "^19.0.0",
       "react-dom": "^19.0.0",
     };
@@ -134,7 +134,7 @@ export class NextAppRouterProvider extends BaseProvider {
       devDeps.typescript = "^5.7.0";
       devDeps["@types/react"] = "^19.0.0";
       devDeps["@types/react-dom"] = "^19.0.0";
-      devDeps["@types/node"] = "^20.0.0";
+      devDeps["@types/node"] = "^22.0.0";
     }
     return {
       dependencies: deps,
@@ -159,7 +159,7 @@ export class NextPagesRouterProvider extends BaseProvider {
   getPackageSet({ options = {} } = {}) {
     const isTs = options.language === "ts";
     const deps = {
-      next: "^15.0.0",
+      next: "^16.0.0",
       react: "^19.0.0",
       "react-dom": "^19.0.0",
     };
@@ -168,7 +168,7 @@ export class NextPagesRouterProvider extends BaseProvider {
       devDeps.typescript = "^5.7.0";
       devDeps["@types/react"] = "^19.0.0";
       devDeps["@types/react-dom"] = "^19.0.0";
-      devDeps["@types/node"] = "^20.0.0";
+      devDeps["@types/node"] = "^22.0.0";
     }
     return {
       dependencies: deps,

package/src/main.js

@@ -12,7 +12,7 @@ import { injectArchitecture, injectConditionals, injectFormatter } from "@/injec
 import { getPkgManager } from "@/utils/pkg-manager.js";
 import { handleDevServer } from "@/utils/dev-server.js";
 import { getUserInputs, onCancel } from "@/prompts.js";
-import { runBaseInstall, runGitInit, runViteCreate } from "@/scaffold.js";
+import { runBaseInstall, runGitInit, runViteCreate, scaffoldBase } from "@/scaffold.js";
 import { installAllDeps } from "@/dependencies.js";
 import { generateReadme } from "@/readme.js";
 import { runProjectFormat } from "@/format.js";
@@ -20,6 +20,8 @@ import { emitManifest } from "@/manifest/emit.js";
 import { emitAgentContext } from "@/agent-context.js";
 
 import { parseCliArgs, loadManifestSource, manifestToResponses, PRESETS } from "@/cli-args.js";
+import { getProvider } from "@/engine/providers/base-provider.js";
+import { normalizeFramework } from "@/engine/capabilities.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -48,6 +50,7 @@ export async function main(options = {}) {
     projectName: nameArg,
     manifest: manifestSource,
     template: templateName,
+    framework: frameworkArg,
     arch: archArg,
   } = options;
   const pkg = getPkgManager();
@@ -94,20 +97,40 @@ export async function main(options = {}) {
       ...preset,
     };
   } else {
-    responses = await getUserInputs(projectName, { quickSetup, initialArch: archArg });
+    responses = await getUserInputs(projectName, { quickSetup, initialArch: archArg, framework: frameworkArg });
   }
 
   const projectPath = path.resolve(CURRENT_DIR, projectName);
 
-  // 4. Scaffold via vite create
+  // 4. Scaffold the base project (provider-owned bases; Vite shells out, Next copies)
+  const fw = normalizeFramework(
+    responses.framework || { name: responses.frameworkName, variant: responses.frameworkVariant }
+  );
   const createSpin = spinner();
-  createSpin.start("Creating your Vite + React project...");
-  try {
-    await runViteCreate(projectPath, projectName, pkg, responses.language);
-    createSpin.stop(chalk.green("Project created successfully!"));
-  } catch (err) {
-    createSpin.stop(chalk.red("Failed to create project."));
-    throw err;
+  if (fw.name === "next") {
+    createSpin.start("Creating your Next.js project...");
+    try {
+      const provider = getProvider(fw.name, fw.variant);
+      const based = await scaffoldBase(projectPath, provider, responses.language, TEMPLATES_DIR);
+      if (!based) {
+        throw new Error(
+          `Next.js base template not found for variant "${fw.variant}" (${responses.language}).`
+        );
+      }
+      createSpin.stop(chalk.green("Project created successfully!"));
+    } catch (err) {
+      createSpin.stop(chalk.red("Failed to create project."));
+      throw err;
+    }
+  } else {
+    createSpin.start("Creating your Vite + React project...");
+    try {
+      await runViteCreate(projectPath, projectName, pkg, responses.language);
+      createSpin.stop(chalk.green("Project created successfully!"));
+    } catch (err) {
+      createSpin.stop(chalk.red("Failed to create project."));
+      throw err;
+    }
   }
 
   // 5. Install base dependencies

package/src/manifest/emit.js

@@ -64,7 +64,7 @@ export function buildManifest(responses, opts = {}) {
   };
   // Include optional axes only if present in responses (future overlays)
   if (responses.bundler) framework.bundler = responses.bundler;
-  if (responses.adapter) framework.adapter = responses.adapter;
+  if (responses.adapter && responses.adapter !== "none") framework.adapter = responses.adapter;
 
   const styling = {
     engine: responses.cssFramework || "tailwind",