create-lacspace-app 2.3.0 → 2.4.0

package/dist/lib.cjs

@@ -40,7 +40,8 @@ function resolveContext(options = {}) {
   const seg = raw.split(/[\\/]/).filter(Boolean).pop() ?? "my-app";
   const name = seg.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/^-+|-+$/g, "") || "my-app";
   const features = normalizeFeatures(options.features);
-  return { name, template, features };
+  const mode = options.mode === "dynamic" ? "dynamic" : "static";
+  return { name, template, features, mode };
 }
 function normalizeFeatures(requested) {
   if (!requested || requested.length === 0) return [];
@@ -1913,6 +1914,10 @@ Because posts are just Markdown files, you can:
 Check the [first post](/blog/welcome) for the full Markdown reference.
 `;
 function buildFiles(ctx) {
+  if (ctx.mode === "dynamic") return buildFullStack(ctx);
+  return buildApp(ctx);
+}
+function buildApp(ctx) {
   const isBlog = ctx.template.key === "blog";
   const isDocs = ctx.template.key === "docs";
   const files = {
@@ -5094,6 +5099,918 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var scope = (ctx) => `@${ctx.name}`;
+var typesPkgJson = (ctx) => JSON.stringify({
+  name: `${scope(ctx)}/types`,
+  version: "0.1.0",
+  private: true,
+  // Type-only package: it ships a single .d.ts (no runtime code, nothing to build).
+  types: "./index.d.ts",
+  exports: { ".": { types: "./index.d.ts" } }
+}, null, 2) + "\n";
+var sharedTypes = () => `// Shared API contract \u2014 imported by BOTH the frontend and the backend, so the two
+// can never drift. These are TYPE-ONLY (no runtime code), so importing them adds
+// nothing to either bundle. Edit here once; both sides update. Use \`import type\`.
+
+/** A user, as returned by the API (no password; dates are ISO strings). */
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+/** The response from POST /auth/register and POST /auth/login. */
+export interface AuthResponse {
+  token: string;
+  user: User;
+}
+
+/** The shape of an error response from the API. */
+export interface ApiError {
+  error: string;
+  fields?: Record<string, string>;
+}
+
+/** The example CRUD resource. Rename "Note" to your real domain object. */
+export interface Note {
+  id: string;
+  title: string;
+  body: string;
+  userId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateNoteInput {
+  title: string;
+  body?: string;
+}
+
+export interface UpdateNoteInput {
+  title?: string;
+  body?: string;
+}
+`;
+var rootPkgJson = (ctx) => JSON.stringify({
+  name: ctx.name,
+  version: "0.1.0",
+  private: true,
+  workspaces: ["types", "backend", "frontend"],
+  scripts: {
+    // Run the API and the frontend together (concurrently), colourised + kill-all.
+    dev: 'concurrently -k -n api,web -c blue,magenta "npm:dev:api" "npm:dev:web"',
+    "dev:api": `npm run dev --workspace ${scope(ctx)}/backend`,
+    "dev:web": `npm run dev --workspace ${scope(ctx)}/frontend`,
+    build: `npm run build --workspace ${scope(ctx)}/backend && npm run build --workspace ${scope(ctx)}/frontend`,
+    start: 'concurrently -k -n api,web -c blue,magenta "npm:start:api" "npm:start:web"',
+    "start:api": `npm run start --workspace ${scope(ctx)}/backend`,
+    "start:web": `npm run start --workspace ${scope(ctx)}/frontend`,
+    typecheck: `npm run typecheck --workspace ${scope(ctx)}/backend`
+  },
+  devDependencies: { concurrently: "^9.1.0" },
+  engines: { node: ">=18" }
+}, null, 2) + "\n";
+var dockerCompose = (ctx) => `# Local infrastructure for ${ctx.name}. Start it with:  docker compose up -d
+# Optional \u2014 the API also runs with NO Redis, and against any MongoDB (e.g. Atlas).
+services:
+  mongo:
+    image: mongo:7
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo-data:/data/db
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+volumes:
+  mongo-data:
+`;
+var rootGitignore = () => `node_modules
+.env
+.env.local
+*.log
+.DS_Store
+dist
+.next
+`;
+var rootEnvExample = (ctx) => `# ${ctx.name} \u2014 ONE .env for the whole monorepo.  Copy it:  cp .env.example .env
+# The defaults below let the app run locally with zero changes.
+
+# --- Backend ---
+NODE_ENV=development
+PORT=4000
+
+# MongoDB. With Docker (docker compose up -d) the default just works. Or paste a
+# free MongoDB Atlas connection string here.
+MONGODB_URI=mongodb://localhost:27017/${ctx.name}
+
+# Signs JWTs. In production generate a strong value:  openssl rand -hex 32
+JWT_SECRET=dev-secret-change-me
+
+# Redis is OPTIONAL \u2014 leave empty to use the in-memory cache fallback.
+# With Docker, set it to:  redis://localhost:6379
+REDIS_URL=
+
+# Who may call the API (the frontend origin). Comma-separate for multiple.
+CORS_ORIGIN=http://localhost:3000
+
+# --- Frontend ---
+# Where the browser calls the API. Unset = http://localhost:4000 (local default).
+# NEXT_PUBLIC_API_URL=http://localhost:4000
+`;
+var rootReadme = (ctx) => `# ${ctx.name}
+
+A full-stack app scaffolded with [create-lacspace-app](https://www.npmjs.com/package/create-lacspace-app) \u2014 a **${ctx.template.label}** frontend + a real backend, wired together.
+
+\`\`\`
+${ctx.name}/
+\u251C\u2500 frontend/   Next.js 15 app (your UI) \u2014 talks to the API
+\u251C\u2500 backend/    Node \xB7 Express \xB7 MongoDB \xB7 Redis \xB7 TypeScript API
+\u251C\u2500 types/      Shared API types \u2014 imported by BOTH sides, so they can't drift
+\u2514\u2500 docker-compose.yml   Mongo + Redis for local dev (optional)
+\`\`\`
+
+## Quick start
+
+\`\`\`bash
+cp .env.example .env         # one env file for everything (sensible defaults)
+docker compose up -d         # optional: starts MongoDB + Redis locally
+npm install                  # installs all three workspaces at once
+npm run dev                  # runs the API (:4000) and the frontend (:3000) together
+\`\`\`
+
+Then open **http://localhost:3000** \u2192 visit **/register**, create an account, and you'll land on **/account** \u2014 a protected page that reads/writes the example "notes" resource through the API.
+
+**No Docker?** Point \`MONGODB_URI\` at any MongoDB (a free [Atlas](https://www.mongodb.com/atlas) cluster works). Redis is optional \u2014 leave \`REDIS_URL\` empty and the API uses an in-memory cache instead.
+
+## What's already built
+
+- **Auth** \u2014 \`POST /auth/register\`, \`POST /auth/login\` (JWT), \`GET /auth/me\`. Passwords hashed with \`@lacspace/password\`, tokens signed/verified with \`@lacspace/jwt\`.
+- **Example CRUD** \u2014 \`/notes\` (list \xB7 create \xB7 read \xB7 update \xB7 delete), protected, per-user, with a per-user cache (Redis or in-memory) that busts on writes.
+- **Validation** \u2014 request bodies validated with \`@lacspace/validate\`; failures return a clean 400.
+- **Rate limiting** \u2014 auth endpoints throttled with \`@lacspace/rate-limit\`.
+- **Typed env** \u2014 \`@lacspace/env\` fails fast at boot if config is wrong.
+
+Everything on the backend is built from zero-dependency \`@lacspace/*\` packages \u2192 https://lacspace.com/packages
+
+## Make it yours
+
+Rename the \`Note\` resource (in \`types/index.d.ts\`, \`backend/src/models/note.ts\`, \`backend/src/routes/notes.ts\`) to your real domain object, then follow the same pattern for more resources. The shared \`types/\` package keeps the frontend and backend in lock-step.
+`;
+var frontendApiClient = (ctx) => `import type { AuthResponse, User, Note, CreateNoteInput, ApiError } from "${scope(ctx)}/types";
+
+// how this works: a tiny typed fetch wrapper around the backend API. The response
+// shapes come from the shared "${scope(ctx)}/types" package \u2014 the SAME types the
+// backend uses \u2014 so the client and server can never disagree about the contract.
+const BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+const TOKEN_KEY = "${ctx.name}_token";
+
+export function getToken(): string | null {
+  if (typeof window === "undefined") return null;
+  try { return localStorage.getItem(TOKEN_KEY); } catch { return null; }
+}
+export function setToken(token: string | null): void {
+  if (typeof window === "undefined") return;
+  try { token ? localStorage.setItem(TOKEN_KEY, token) : localStorage.removeItem(TOKEN_KEY); } catch {}
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+  const token = getToken();
+  const res = await fetch(\`\${BASE}\${path}\`, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: \`Bearer \${token}\` } : {}),
+      ...(init?.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    let message = "Request failed";
+    try { message = ((await res.json()) as ApiError).error ?? message; } catch {}
+    throw new Error(message);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+
+export const api = {
+  register: (input: { name: string; email: string; password: string }) =>
+    request<AuthResponse>("/auth/register", { method: "POST", body: JSON.stringify(input) }),
+  login: (input: { email: string; password: string }) =>
+    request<AuthResponse>("/auth/login", { method: "POST", body: JSON.stringify(input) }),
+  me: () => request<User>("/auth/me"),
+  listNotes: () => request<Note[]>("/notes"),
+  createNote: (input: CreateNoteInput) =>
+    request<Note>("/notes", { method: "POST", body: JSON.stringify(input) }),
+  deleteNote: (id: string) => request<void>(\`/notes/\${id}\`, { method: "DELETE" }),
+};
+`;
+var frontendLoginPage = () => `"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { api, setToken } from "@/lib/api";
+
+// how this works: posts to the backend /auth/login, stores the returned JWT, then
+// redirects to /account. Every request after this sends the token automatically.
+export default function LoginPage() {
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true); setError(null);
+    try {
+      const { token } = await api.login({ email, password });
+      setToken(token);
+      router.push("/account");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+    } finally { setBusy(false); }
+  }
+
+  return (
+    <main className="mx-auto flex min-h-[70vh] max-w-sm flex-col justify-center px-6">
+      <h1 className="text-2xl font-bold">Welcome back</h1>
+      <p className="mt-1 text-muted">Sign in to your account.</p>
+      <form onSubmit={onSubmit} className="mt-6 space-y-4">
+        <input value={email} onChange={(e) => setEmail(e.target.value)} type="email" required placeholder="you@example.com" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={password} onChange={(e) => setPassword(e.target.value)} type="password" required placeholder="Password" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button disabled={busy} className="w-full rounded-full gradient-bg px-4 py-3 font-semibold on-accent transition hover:opacity-90 disabled:opacity-60">{busy ? "Signing in\u2026" : "Sign in"}</button>
+      </form>
+      <p className="mt-4 text-sm text-muted">No account? <Link href="/register" className="underline">Create one</Link></p>
+    </main>
+  );
+}
+`;
+var frontendRegisterPage = () => `"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { api, setToken } from "@/lib/api";
+
+// how this works: posts to /auth/register, stores the JWT, redirects to /account.
+export default function RegisterPage() {
+  const router = useRouter();
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true); setError(null);
+    try {
+      const { token } = await api.register({ name, email, password });
+      setToken(token);
+      router.push("/account");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+    } finally { setBusy(false); }
+  }
+
+  return (
+    <main className="mx-auto flex min-h-[70vh] max-w-sm flex-col justify-center px-6">
+      <h1 className="text-2xl font-bold">Create your account</h1>
+      <p className="mt-1 text-muted">It takes a few seconds.</p>
+      <form onSubmit={onSubmit} className="mt-6 space-y-4">
+        <input value={name} onChange={(e) => setName(e.target.value)} required placeholder="Your name" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={email} onChange={(e) => setEmail(e.target.value)} type="email" required placeholder="you@example.com" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={password} onChange={(e) => setPassword(e.target.value)} type="password" required minLength={8} placeholder="Password (min 8 chars)" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button disabled={busy} className="w-full rounded-full gradient-bg px-4 py-3 font-semibold on-accent transition hover:opacity-90 disabled:opacity-60">{busy ? "Creating\u2026" : "Create account"}</button>
+      </form>
+      <p className="mt-4 text-sm text-muted">Already have one? <Link href="/login" className="underline">Sign in</Link></p>
+    </main>
+  );
+}
+`;
+var frontendAccountPage = (ctx) => `"use client";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { api, getToken, setToken } from "@/lib/api";
+import type { User, Note } from "${scope(ctx)}/types";
+
+// how this works: a PROTECTED page. On mount it calls /auth/me with the stored
+// token; if that fails it bounces to /login. Notes are the example CRUD resource.
+export default function AccountPage() {
+  const router = useRouter();
+  const [user, setUser] = useState<User | null>(null);
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!getToken()) { router.push("/login"); return; }
+    (async () => {
+      try {
+        setUser(await api.me());
+        setNotes(await api.listNotes());
+      } catch { setToken(null); router.push("/login"); }
+    })();
+  }, [router]);
+
+  async function addNote(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      const note = await api.createNote({ title, body });
+      setNotes((prev) => [note, ...prev]);
+      setTitle(""); setBody("");
+    } catch (err) { setError(err instanceof Error ? err.message : "Failed to save"); }
+  }
+  async function remove(id: string) {
+    await api.deleteNote(id);
+    setNotes((prev) => prev.filter((n) => n.id !== id));
+  }
+  function signOut() { setToken(null); router.push("/login"); }
+
+  if (!user) return <main className="mx-auto max-w-2xl px-6 py-16 text-muted">Loading\u2026</main>;
+
+  return (
+    <main className="mx-auto max-w-2xl px-6 py-16">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-bold">Hi, {user.name}</h1>
+          <p className="text-muted">{user.email}</p>
+        </div>
+        <button onClick={signOut} className="rounded-full border border-hairline px-4 py-2 text-sm transition hover:bg-surface">Sign out</button>
+      </div>
+
+      <form onSubmit={addNote} className="mt-8 space-y-3 rounded-2xl border border-hairline bg-surface p-5">
+        <h2 className="font-semibold">Add a note</h2>
+        <input value={title} onChange={(e) => setTitle(e.target.value)} required placeholder="Title" className="w-full rounded-xl border border-hairline bg-app px-4 py-2 outline-none" />
+        <textarea value={body} onChange={(e) => setBody(e.target.value)} placeholder="Write something\u2026" rows={3} className="w-full rounded-xl border border-hairline bg-app px-4 py-2 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button className="rounded-full gradient-bg px-4 py-2 text-sm font-semibold on-accent">Save note</button>
+      </form>
+
+      <ul className="mt-6 space-y-3">
+        {notes.length === 0 && <li className="text-muted">No notes yet \u2014 add your first above.</li>}
+        {notes.map((n) => (
+          <li key={n.id} className="flex items-start justify-between rounded-2xl border border-hairline p-4">
+            <div>
+              <p className="font-medium">{n.title}</p>
+              {n.body && <p className="mt-1 text-sm text-muted">{n.body}</p>}
+            </div>
+            <button onClick={() => remove(n.id)} className="shrink-0 text-sm text-muted transition hover:text-red-400">Delete</button>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+`;
+function buildFullStack(ctx) {
+  const out = {};
+  const s = scope(ctx);
+  const app = buildApp(ctx);
+  for (const [rel, content] of Object.entries(app)) out[`frontend/${rel}`] = content;
+  const fpkg = JSON.parse(out["frontend/package.json"]);
+  fpkg.name = `${s}/frontend`;
+  fpkg.dependencies[`${s}/types`] = "*";
+  out["frontend/package.json"] = JSON.stringify(fpkg, null, 2) + "\n";
+  const fts = JSON.parse(out["frontend/tsconfig.json"]);
+  fts.compilerOptions.paths[`${s}/types`] = ["../types/index.d.ts"];
+  out["frontend/tsconfig.json"] = JSON.stringify(fts, null, 2) + "\n";
+  const fenv = out["frontend/.env.example"] ?? "";
+  out["frontend/.env.example"] = (fenv.endsWith("\n") || fenv === "" ? fenv : fenv + "\n") + "\n# The backend API base URL. Unset = http://localhost:4000 (local default).\n# NEXT_PUBLIC_API_URL=http://localhost:4000\n";
+  out["frontend/lib/api.ts"] = frontendApiClient(ctx);
+  out["frontend/app/login/page.tsx"] = frontendLoginPage();
+  out["frontend/app/register/page.tsx"] = frontendRegisterPage();
+  out["frontend/app/account/page.tsx"] = frontendAccountPage(ctx);
+  Object.assign(out, backendFiles(ctx));
+  out["types/package.json"] = typesPkgJson(ctx);
+  out["types/index.d.ts"] = sharedTypes();
+  out["package.json"] = rootPkgJson(ctx);
+  out["docker-compose.yml"] = dockerCompose(ctx);
+  out[".gitignore"] = rootGitignore();
+  out[".env.example"] = rootEnvExample(ctx);
+  out["README.md"] = rootReadme(ctx);
+  return out;
+}
+var backendPkgJson = (ctx) => JSON.stringify({
+  name: `${scope(ctx)}/backend`,
+  version: "0.1.0",
+  private: true,
+  type: "module",
+  main: "dist/index.js",
+  scripts: {
+    dev: "tsx watch src/index.ts",
+    build: "tsc -p tsconfig.json",
+    start: "node dist/index.js",
+    typecheck: "tsc -p tsconfig.json --noEmit"
+  },
+  dependencies: {
+    express: "^4.21.2",
+    cors: "^2.8.5",
+    mongoose: "^8.9.0",
+    ioredis: "^5.4.2",
+    dotenv: "^16.4.7",
+    // ✨ Backend built on zero-dep @lacspace/* packages instead of the usual grab-bag.
+    "@lacspace/env": "^1.1.0",
+    "@lacspace/jwt": "^1.4.0",
+    "@lacspace/password": "^1.1.0",
+    "@lacspace/validate": "^1.1.0",
+    "@lacspace/id": "^1.1.0",
+    "@lacspace/rate-limit": "^1.2.0",
+    "@lacspace/cache": "^1.1.0",
+    [`${scope(ctx)}/types`]: "*"
+  },
+  devDependencies: {
+    typescript: "^5.7.0",
+    tsx: "^4.19.2",
+    "@types/node": "^22.10.0",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17"
+  }
+}, null, 2) + "\n";
+var backendTsconfig = (ctx) => JSON.stringify({
+  compilerOptions: {
+    target: "ES2022",
+    module: "NodeNext",
+    moduleResolution: "NodeNext",
+    lib: ["ES2022"],
+    esModuleInterop: true,
+    allowSyntheticDefaultImports: true,
+    strict: true,
+    skipLibCheck: true,
+    resolveJsonModule: true,
+    outDir: "dist",
+    rootDir: "src",
+    sourceMap: true,
+    types: ["node"],
+    baseUrl: ".",
+    paths: { [`${scope(ctx)}/types`]: ["../types/index.d.ts"] }
+  },
+  include: ["src/**/*"],
+  exclude: ["node_modules", "dist"]
+}, null, 2) + "\n";
+var backendGitignore = () => `node_modules
+dist
+.env
+*.log
+`;
+var backendReadme = (ctx) => `# ${ctx.name} \u2014 API
+
+Node \xB7 Express \xB7 MongoDB \xB7 Redis (optional) \xB7 TypeScript. Built on zero-dependency \`@lacspace/*\` packages.
+
+Run it from the repo root with \`npm run dev\` (starts this API + the frontend). Standalone: \`npm run dev\` inside this folder.
+
+## Endpoints
+
+| Method | Path             | Auth | Description                    |
+|--------|------------------|------|--------------------------------|
+| GET    | \`/health\`        | \u2014    | Liveness check                 |
+| POST   | \`/auth/register\` | \u2014    | Create an account \u2192 JWT + user |
+| POST   | \`/auth/login\`    | \u2014    | Log in \u2192 JWT + user            |
+| GET    | \`/auth/me\`       | \u2713    | The current user               |
+| GET    | \`/notes\`         | \u2713    | List your notes (cached)       |
+| POST   | \`/notes\`         | \u2713    | Create a note                  |
+| GET    | \`/notes/:id\`     | \u2713    | Read one note                  |
+| PATCH  | \`/notes/:id\`     | \u2713    | Update a note                  |
+| DELETE | \`/notes/:id\`     | \u2713    | Delete a note                  |
+
+Send \`Authorization: Bearer <token>\` for the \u2713 routes (you get the token from register/login).
+
+## Layout
+
+\`\`\`
+src/
+\u251C\u2500 index.ts        boot: load env \u2192 connect Mongo \u2192 listen
+\u251C\u2500 load-env.ts     loads the root .env (imported first)
+\u251C\u2500 env.ts          typed, validated env (@lacspace/env)
+\u251C\u2500 app.ts          the Express app (CORS, routes, error handler)
+\u251C\u2500 db.ts           Mongoose connection
+\u251C\u2500 cache.ts        Redis, or an in-memory fallback (@lacspace/cache)
+\u251C\u2500 http.ts         HttpError + asyncHandler
+\u251C\u2500 validation.ts   request schemas (@lacspace/validate)
+\u251C\u2500 middleware/     auth (@lacspace/jwt) + error handling
+\u251C\u2500 models/         Mongoose models (User, Note)
+\u2514\u2500 routes/         auth + notes (the example CRUD resource)
+\`\`\`
+`;
+var backendLoadEnv = () => `import { config } from "dotenv";
+import { resolve } from "node:path";
+
+// how this works: the whole monorepo shares ONE .env at the repo root. When this
+// API runs via \`npm run dev\` its working directory is backend/, so the root .env
+// is one level up. This module is imported FIRST (before env.ts) so the variables
+// exist by the time anything reads them.
+config({ path: resolve(process.cwd(), "../.env") });
+config(); // also load backend/.env if you keep one (root values already set win)
+`;
+var backendEnv = (ctx) => `import { createEnv, str, port, oneOf } from "@lacspace/env";
+
+// how this works: fail-fast, TYPED environment variables (@lacspace/env). Bad or
+// missing values throw at boot with a clear message. Sensible dev defaults mean it
+// runs with zero config against a local MongoDB; set real values in the root .env.
+export const env = createEnv({
+  NODE_ENV: oneOf(["development", "production", "test"], { default: "development" }),
+  PORT: port({ default: 4000 }),
+  MONGODB_URI: str({ default: "mongodb://localhost:27017/${ctx.name}" }),
+  JWT_SECRET: str({ default: "dev-secret-change-me" }),
+  REDIS_URL: str({ optional: true }),
+  CORS_ORIGIN: str({ default: "http://localhost:3000" }),
+});
+
+if (env.NODE_ENV === "production" && env.JWT_SECRET === "dev-secret-change-me") {
+  throw new Error("Set a strong JWT_SECRET in production (see .env.example).");
+}
+`;
+var backendIndex = (ctx) => `import "./load-env.js"; // MUST be first: fills process.env before anything reads it
+import { env } from "./env.js";
+import { connectDb } from "./db.js";
+import { createApp } from "./app.js";
+
+// how this works: connect to MongoDB, build the Express app, then listen.
+async function main(): Promise<void> {
+  await connectDb(env.MONGODB_URI);
+  const app = createApp();
+  app.listen(env.PORT, () => {
+    console.log(\`\u{1F680} ${ctx.name} API ready on http://localhost:\${env.PORT}\`);
+  });
+}
+
+main().catch((err) => {
+  console.error("Failed to start the API:", err);
+  process.exit(1);
+});
+`;
+var backendDb = () => `import mongoose from "mongoose";
+
+// how this works: opens the Mongoose connection. Call once at boot.
+export async function connectDb(uri: string): Promise<void> {
+  mongoose.set("strictQuery", true);
+  await mongoose.connect(uri);
+  console.log("\u2714 MongoDB connected");
+}
+`;
+var backendCache = () => `import { createCache } from "@lacspace/cache";
+import { Redis } from "ioredis";
+import { env } from "./env.js";
+
+// how this works: one cache interface, TWO backends. If REDIS_URL is set we use
+// Redis; otherwise we fall back to @lacspace/cache (zero-dep, in-memory) so the app
+// runs with NO Redis at all. The rest of the code doesn't care which is active.
+export interface Cache {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+  del(key: string): Promise<void>;
+  readonly kind: "redis" | "memory";
+}
+
+function redisCache(url: string): Cache {
+  const client = new Redis(url, { maxRetriesPerRequest: 2 });
+  client.on("error", (e: Error) => console.warn("\u26A0 Redis error:", e.message));
+  return {
+    kind: "redis",
+    async get(key) { return client.get(key); },
+    async set(key, value, ttl) { if (ttl) await client.set(key, value, "EX", ttl); else await client.set(key, value); },
+    async del(key) { await client.del(key); },
+  };
+}
+
+function memoryCache(): Cache {
+  const mem = createCache<string>({ max: 5000 });
+  return {
+    kind: "memory",
+    async get(key) { return mem.get(key) ?? null; },
+    async set(key, value, ttl) { mem.set(key, value, ttl ? ttl * 1000 : undefined); },
+    async del(key) { mem.delete(key); },
+  };
+}
+
+export const cache: Cache = env.REDIS_URL ? redisCache(env.REDIS_URL) : memoryCache();
+console.log(\`\u2714 Cache: \${cache.kind}\${cache.kind === "memory" ? " (no REDIS_URL \u2014 in-memory fallback)" : ""}\`);
+`;
+var backendHttp = () => `import type { Request, Response, NextFunction, RequestHandler } from "express";
+
+/** A simple HTTP error with a status code \u2014 throw it from any handler. */
+export class HttpError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+    this.name = "HttpError";
+  }
+}
+
+// how this works: Express v4 doesn't catch rejected Promises from async handlers,
+// so wrap them \u2014 any thrown error is forwarded to the error middleware.
+export const asyncHandler =
+  (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler =>
+  (req, res, next) => { fn(req, res, next).catch(next); };
+`;
+var backendExpressTypes = () => `// Adds req.user (populated by requireAuth) to Express's Request type.
+import "express";
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: { sub: string; email: string; iat?: number; exp?: number; iss?: string };
+    }
+  }
+}
+
+export {};
+`;
+var backendErrorMw = () => `import type { Request, Response, NextFunction } from "express";
+import { ValidationError } from "@lacspace/validate";
+import { HttpError } from "../http.js";
+
+// how this works: ONE place that turns thrown errors into clean JSON responses.
+// Register it LAST (after all routes). Express identifies it by its 4 arguments.
+export function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction): void {
+  if (err instanceof ValidationError) {
+    res.status(400).json({ error: "Validation failed", fields: err.flatten() });
+    return;
+  }
+  if (err instanceof HttpError) {
+    res.status(err.status).json({ error: err.message });
+    return;
+  }
+  console.error(err);
+  res.status(500).json({ error: "Internal server error" });
+}
+`;
+var backendAuthMw = (ctx) => `import type { RequestHandler } from "express";
+import { expressJwt } from "@lacspace/jwt";
+import { env } from "../env.js";
+
+// how this works: verifies the "Authorization: Bearer <token>" header with
+// @lacspace/jwt and attaches the decoded payload to req.user (see express.d.ts).
+// Missing/invalid token \u2192 it responds 401 automatically. Put it on any route you
+// want protected:  router.get("/secret", requireAuth, handler)
+// (@lacspace/jwt's middleware is framework-agnostic, so we cast it to Express's
+//  RequestHandler \u2014 it's a standard (req, res, next) function underneath.)
+export const requireAuth = expressJwt(env.JWT_SECRET, { issuer: "${ctx.name}-api" }) as unknown as RequestHandler;
+`;
+var backendUserModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+
+// how this works: the User fields. _id is a time-sortable UUID (@lacspace/id)
+// instead of an ObjectId, so ids are readable and orderable. We store only a
+// password HASH, never the raw password. (We DON'T extend mongoose.Document \u2014 that
+// would force _id to be an ObjectId; a plain interface lets _id be our string.)
+export interface UserDoc {
+  _id: string;
+  email: string;
+  name: string;
+  passwordHash: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const userSchema = new mongoose.Schema<UserDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    email: { type: String, required: true, unique: true, lowercase: true, trim: true },
+    name: { type: String, required: true, trim: true },
+    passwordHash: { type: String, required: true },
+  },
+  { timestamps: true },
+);
+
+export const User =
+  (mongoose.models.User as mongoose.Model<UserDoc>) ?? mongoose.model<UserDoc>("User", userSchema);
+`;
+var backendNoteModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+
+// how this works: the example CRUD resource. Rename "Note" to your real domain
+// object (Task, Post, Product\u2026) and add fields \u2014 the routes follow the same shape.
+// (Plain interface, not mongoose.Document, so _id can be our string UUID.)
+export interface NoteDoc {
+  _id: string;
+  title: string;
+  body: string;
+  userId: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const noteSchema = new mongoose.Schema<NoteDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    title: { type: String, required: true, trim: true },
+    body: { type: String, default: "" },
+    userId: { type: String, required: true, index: true },
+  },
+  { timestamps: true },
+);
+
+export const Note =
+  (mongoose.models.Note as mongoose.Model<NoteDoc>) ?? mongoose.model<NoteDoc>("Note", noteSchema);
+`;
+var backendValidation = () => `import { v, type Infer } from "@lacspace/validate";
+
+// how this works: Zod-like schemas (@lacspace/validate). .parse(body) throws a
+// ValidationError on bad input, which the error middleware turns into a clean 400
+// with per-field messages.
+export const RegisterInput = v.object({
+  name: v.string().min(2).max(80),
+  email: v.string().email(),
+  password: v.string().min(8).max(200),
+});
+
+export const LoginInput = v.object({
+  email: v.string().email(),
+  password: v.string().min(1),
+});
+
+export const NoteInput = v.object({
+  title: v.string().min(1).max(200),
+  body: v.string().max(10_000).default(""),
+});
+
+export type RegisterBody = Infer<typeof RegisterInput>;
+export type LoginBody = Infer<typeof LoginInput>;
+export type NoteBody = Infer<typeof NoteInput>;
+`;
+var backendAuthRoutes = (ctx) => `import express from "express";
+import { hash, verify as verifyPassword } from "@lacspace/password";
+import { sign } from "@lacspace/jwt";
+import { asyncHandler, HttpError } from "../http.js";
+import { requireAuth } from "../middleware/auth.js";
+import { User, type UserDoc } from "../models/user.js";
+import { env } from "../env.js";
+import { RegisterInput, LoginInput } from "../validation.js";
+import type { AuthResponse, User as UserDTO } from "${scope(ctx)}/types";
+
+const ISSUER = "${ctx.name}-api";
+const WEEK = 60 * 60 * 24 * 7; // token lifetime, in seconds
+const router = express.Router();
+
+function toDTO(u: UserDoc): UserDTO {
+  return { id: String(u._id), email: u.email, name: u.name, createdAt: u.createdAt.toISOString() };
+}
+function tokenFor(u: UserDoc): Promise<string> {
+  return sign({ sub: String(u._id), email: u.email }, env.JWT_SECRET, { expiresIn: WEEK, issuer: ISSUER });
+}
+
+// POST /auth/register \u2014 create an account, return a JWT + the user.
+router.post("/register", asyncHandler(async (req, res) => {
+  const { name, email, password } = RegisterInput.parse(req.body);
+  if (await User.findOne({ email })) throw new HttpError(409, "That email is already registered");
+  const passwordHash = await hash(password); // PBKDF2 via @lacspace/password
+  const user = await User.create({ name, email, passwordHash });
+  const out: AuthResponse = { token: await tokenFor(user), user: toDTO(user) };
+  res.status(201).json(out);
+}));
+
+// POST /auth/login \u2014 verify credentials, return a JWT + the user.
+router.post("/login", asyncHandler(async (req, res) => {
+  const { email, password } = LoginInput.parse(req.body);
+  const user = await User.findOne({ email });
+  if (!user || !(await verifyPassword(password, user.passwordHash))) {
+    throw new HttpError(401, "Invalid email or password");
+  }
+  const out: AuthResponse = { token: await tokenFor(user), user: toDTO(user) };
+  res.json(out);
+}));
+
+// GET /auth/me \u2014 the current user (requires a valid token).
+router.get("/me", requireAuth, asyncHandler(async (req, res) => {
+  const user = await User.findById(req.user!.sub);
+  if (!user) throw new HttpError(404, "User not found");
+  res.json(toDTO(user));
+}));
+
+export default router;
+`;
+var backendNoteRoutes = (ctx) => `import express from "express";
+import { asyncHandler, HttpError } from "../http.js";
+import { requireAuth } from "../middleware/auth.js";
+import { Note, type NoteDoc } from "../models/note.js";
+import { cache } from "../cache.js";
+import { NoteInput } from "../validation.js";
+import type { Note as NoteDTO } from "${scope(ctx)}/types";
+
+const router = express.Router();
+router.use(requireAuth); // every /notes route requires a valid token
+
+function toDTO(n: NoteDoc): NoteDTO {
+  return {
+    id: String(n._id),
+    title: n.title,
+    body: n.body,
+    userId: String(n.userId),
+    createdAt: n.createdAt.toISOString(),
+    updatedAt: n.updatedAt.toISOString(),
+  };
+}
+const listKey = (userId: string): string => \`notes:\${userId}\`;
+
+// GET /notes \u2014 this user's notes. Cached for 30s (Redis or in-memory); every write
+// below busts the cache, so reads are fast but never stale after a change.
+router.get("/", asyncHandler(async (req, res) => {
+  const userId = req.user!.sub;
+  const cached = await cache.get(listKey(userId));
+  if (cached) { res.json(JSON.parse(cached) as NoteDTO[]); return; }
+  const notes = await Note.find({ userId }).sort({ createdAt: -1 });
+  const dto = notes.map(toDTO);
+  await cache.set(listKey(userId), JSON.stringify(dto), 30);
+  res.json(dto);
+}));
+
+// POST /notes \u2014 create a note.
+router.post("/", asyncHandler(async (req, res) => {
+  const userId = req.user!.sub;
+  const { title, body } = NoteInput.parse(req.body);
+  const note = await Note.create({ title, body, userId });
+  await cache.del(listKey(userId));
+  res.status(201).json(toDTO(note));
+}));
+
+// GET /notes/:id \u2014 one note (only if it's yours).
+router.get("/:id", asyncHandler(async (req, res) => {
+  const note = await Note.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!note) throw new HttpError(404, "Note not found");
+  res.json(toDTO(note));
+}));
+
+// PATCH /notes/:id \u2014 update a note.
+router.patch("/:id", asyncHandler(async (req, res) => {
+  const patch = NoteInput.partial().parse(req.body);
+  const note = await Note.findOneAndUpdate({ _id: req.params.id, userId: req.user!.sub }, { $set: patch }, { new: true });
+  if (!note) throw new HttpError(404, "Note not found");
+  await cache.del(listKey(req.user!.sub));
+  res.json(toDTO(note));
+}));
+
+// DELETE /notes/:id \u2014 delete a note.
+router.delete("/:id", asyncHandler(async (req, res) => {
+  const note = await Note.findOneAndDelete({ _id: req.params.id, userId: req.user!.sub });
+  if (!note) throw new HttpError(404, "Note not found");
+  await cache.del(listKey(req.user!.sub));
+  res.status(204).end();
+}));
+
+export default router;
+`;
+var backendApp = (ctx) => `import express from "express";
+import type { RequestHandler } from "express";
+import cors from "cors";
+import { rateLimit, expressRateLimit } from "@lacspace/rate-limit";
+import { env } from "./env.js";
+import { errorHandler } from "./middleware/error.js";
+import authRoutes from "./routes/auth.js";
+import noteRoutes from "./routes/notes.js";
+
+// how this works: assembles the Express app \u2014 CORS for the frontend, JSON parsing,
+// a health check, the auth + notes routers, then the error handler LAST.
+export function createApp(): express.Express {
+  const app = express();
+
+  app.use(cors({ origin: env.CORS_ORIGIN.split(",").map((o) => o.trim()), credentials: true }));
+  app.use(express.json());
+
+  // Brute-force protection on auth: 20 requests / minute / IP (@lacspace/rate-limit).
+  const authLimiter = expressRateLimit(rateLimit({ limit: 20, windowMs: 60_000 })) as unknown as RequestHandler;
+
+  app.get("/health", (_req, res) => { res.json({ ok: true, service: "${ctx.name}-api" }); });
+  app.use("/auth", authLimiter, authRoutes);
+  app.use("/notes", noteRoutes);
+
+  app.use(errorHandler);
+  return app;
+}
+`;
+function backendFiles(ctx) {
+  return {
+    "backend/package.json": backendPkgJson(ctx),
+    "backend/tsconfig.json": backendTsconfig(ctx),
+    "backend/.gitignore": backendGitignore(),
+    "backend/README.md": backendReadme(ctx),
+    "backend/src/index.ts": backendIndex(ctx),
+    "backend/src/load-env.ts": backendLoadEnv(),
+    "backend/src/env.ts": backendEnv(ctx),
+    "backend/src/db.ts": backendDb(),
+    "backend/src/cache.ts": backendCache(),
+    "backend/src/app.ts": backendApp(ctx),
+    "backend/src/http.ts": backendHttp(),
+    "backend/src/express.d.ts": backendExpressTypes(),
+    "backend/src/validation.ts": backendValidation(),
+    "backend/src/middleware/auth.ts": backendAuthMw(ctx),
+    "backend/src/middleware/error.ts": backendErrorMw(),
+    "backend/src/models/user.ts": backendUserModel(),
+    "backend/src/models/note.ts": backendNoteModel(),
+    "backend/src/routes/auth.ts": backendAuthRoutes(ctx),
+    "backend/src/routes/notes.ts": backendNoteRoutes(ctx)
+  };
+}
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
   const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
@@ -5107,7 +6024,15 @@ function parseArgs(list) {
     else if (arg === "--pm") a.pm = next();
     else if (arg === "--theme" || arg === "--accent") a.theme = next();
     else if (arg === "--with" || arg === "--features") a.features.push(...splitList(next()));
-    else if (arg === "-h" || arg === "--help") a.help = true;
+    else if (arg === "--fullstack" || arg === "--full-stack" || arg === "--dynamic") a.mode = "dynamic";
+    else if (arg === "--static") a.mode = "static";
+    else if (arg === "--mode") {
+      const m = next().toLowerCase();
+      a.mode = m === "dynamic" ? "dynamic" : "static";
+    } else if (arg.startsWith("--mode=")) {
+      const m = arg.slice(7).toLowerCase();
+      a.mode = m === "dynamic" ? "dynamic" : "static";
+    } else if (arg === "-h" || arg === "--help") a.help = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
@@ -5207,6 +6132,9 @@ ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
 
 ${c("bold", "Options")}
   -t, --template <key>   Template (${TEMPLATES.map((t) => t.key).join(" | ")})
+  --fullstack            Full-stack monorepo: Next.js frontend + Node/Express/
+                         MongoDB/Redis backend (JWT auth + CRUD) + shared types
+                         ${c("dim", "(alias --dynamic; default is --static, a single Next.js app)")}
   --with <a,b>           Feature add-ons, comma-separated (alias --features)
   --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (e.g. --theme lacspace)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
@@ -5598,6 +6526,7 @@ ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a go
 `);
   let name = args.name;
   let templateKey = args.template;
+  let mode = args.mode ?? "static";
   const featureKeys = [...args.features];
   if (!args.yes && process$1.stdin.isTTY) {
     const rl = promises.createInterface({ input: process$1.stdin, output: process$1.stdout });
@@ -5614,6 +6543,18 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
         const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : TEMPLATES.findIndex((t) => t.key === ans);
         templateKey = TEMPLATES[idx]?.key ?? "personal";
       }
+      if (args.mode === void 0) {
+        process$1.stdout.write(`
+  What kind of app?
+`);
+        process$1.stdout.write(`   ${c("cyan", "1")}. ${c("bold", "Static / frontend only")} ${c("dim", "\u2014 a single Next.js app (SEO site, marketing, blog, docs). Fast, deploy anywhere.")}
+`);
+        process$1.stdout.write(`   ${c("cyan", "2")}. ${c("bold", "Dynamic / full-stack")} ${c("dim", "\u2014 frontend + a Node\xB7Express\xB7MongoDB\xB7Redis API with working auth & CRUD, wired together.")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Type ${c("dim", "(1)")}: `)).trim() || "1";
+        mode = ans === "2" || ans.toLowerCase().startsWith("dyn") || ans.toLowerCase().startsWith("full") ? "dynamic" : "static";
+      }
       if (featureKeys.length === 0) {
         process$1.stdout.write(`
   Add feature add-ons? ${c("dim", "(free & keyless \u2014 local AI by default)")}
@@ -5655,14 +6596,15 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
     return;
   }
   const features = normalizeFeatures(featureKeys);
-  const files = buildFiles({ name: projectName, template, features });
+  const files = buildFiles({ name: projectName, template, features, mode });
   for (const [rel, content] of Object.entries(files)) {
     const full = path.join(dir, rel);
     fs.mkdirSync(path.dirname(full), { recursive: true });
     fs.writeFileSync(full, content);
   }
+  const shape = mode === "dynamic" ? " \xB7 full-stack" : "";
   process$1.stdout.write(`
-  ${c("green", "\u2714")} Created ${c("bold", name)} ${c("dim", `(${template.label})`)}
+  ${c("green", "\u2714")} Created ${c("bold", name)} ${c("dim", `(${template.label}${shape})`)}
 `);
   if (features.length) process$1.stdout.write(`  ${c("green", "\u2714")} Feature add-ons: ${features.map((f) => c("cyan", f.key)).join(", ")}
 `);
@@ -5692,11 +6634,25 @@ ${c("bold", "Done! Next steps")}
 `);
   if (!args.install) process$1.stdout.write(`  ${c("cyan", `${args.pm} install`)}
 `);
-  process$1.stdout.write(`  ${c("cyan", run)}
+  if (mode === "dynamic") {
+    process$1.stdout.write(`  ${c("cyan", "cp .env.example .env")} ${c("dim", "\u2014 then, optionally:")} ${c("cyan", "docker compose up -d")} ${c("dim", "(Mongo + Redis)")}
 `);
-  process$1.stdout.write(`
+    process$1.stdout.write(`  ${c("cyan", run)} ${c("dim", "\u2014 runs the API (:4000) and the frontend (:3000) together")}
+`);
+    process$1.stdout.write(`
+  ${c("dim", "backend \u2192")} ${c("cyan", "backend/src/")} ${c("dim", "(Express \xB7 MongoDB \xB7 Redis \xB7 JWT auth \xB7 example CRUD)")}
+`);
+    process$1.stdout.write(`  ${c("dim", "frontend \u2192")} ${c("cyan", "frontend/app/")} ${c("dim", "\xB7 shared API types \u2192")} ${c("cyan", "types/src/")}
+`);
+    process$1.stdout.write(`  ${c("dim", "No Docker? Point")} ${c("cyan", "MONGODB_URI")} ${c("dim", "at any MongoDB (e.g. free Atlas); Redis is optional.")}
+`);
+  } else {
+    process$1.stdout.write(`  ${c("cyan", run)}
+`);
+    process$1.stdout.write(`
   Edit ${c("cyan", "lib/site.ts")} (your SEO config) and ${c("cyan", "app/page.tsx")}.
 `);
+  }
   if (features.length) {
     const hasAi = features.some((f) => f.key === "ai-chat" || f.key === "rag");
     process$1.stdout.write(`