@podosoft/podokit 0.3.0 → 0.5.0

package/dist/lockfile.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OWNED_GLOBS = exports.LOCK_SCHEMA_VERSION = void 0;
+exports.manifestPath = manifestPath;
+exports.filesLockPath = filesLockPath;
+exports.readManifest = readManifest;
+exports.writeManifest = writeManifest;
+exports.writeFilesLock = writeFilesLock;
+exports.podokitVersion = podokitVersion;
+exports.matchGlob = matchGlob;
+exports.classifyTier = classifyTier;
+exports.walkFiles = walkFiles;
+exports.computeFilesLock = computeFilesLock;
+exports.readFilesLock = readFilesLock;
+exports.computeDrift = computeDrift;
+exports.initLockfile = initLockfile;
+exports.recordModules = recordModules;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const podokit_template_engine_1 = require("@podosoft/podokit-template-engine");
+/**
+ * The generation lockfile (`.podokit/`) records how a project was assembled so
+ * `podo update` can rebuild the same inputs and detect user edits. See
+ * ADR-0009 (update mechanism) and ADR-0010 (ownership model).
+ */
+exports.LOCK_SCHEMA_VERSION = 1;
+const PODOKIT_DIR = ".podokit";
+const MANIFEST_FILE = "manifest.json";
+const FILES_LOCK_FILE = "files.lock";
+/** Marker that flags a file as assembled from base + module injections. */
+const INJECTION_MARKER = "// podokit:";
+/** Directories that never belong in the lockfile (generated / vendored). */
+const WALK_IGNORE = new Set([
+    "node_modules",
+    ".git",
+    PODOKIT_DIR,
+    "dist",
+    "build",
+    ".svelte-kit",
+    ".turbo",
+    "coverage",
+]);
+/** Default user-owned globs seeded into a new project. See ADR-0010. */
+exports.DEFAULT_OWNED_GLOBS = [
+    "apps/web/src/routes/**",
+    "apps/web/src/lib/components/ui/**",
+];
+const TEXT_EXT = /\.(json|md|ts|tsx|js|mjs|cjs|css|html|yml|yaml|txt|env|svelte|gitignore|example)$/i;
+function podokitDir(projectRoot) {
+    return (0, node_path_1.join)(projectRoot, PODOKIT_DIR);
+}
+function manifestPath(projectRoot) {
+    return (0, node_path_1.join)(podokitDir(projectRoot), MANIFEST_FILE);
+}
+function filesLockPath(projectRoot) {
+    return (0, node_path_1.join)(podokitDir(projectRoot), FILES_LOCK_FILE);
+}
+function readManifest(projectRoot) {
+    const file = manifestPath(projectRoot);
+    return (0, node_fs_1.existsSync)(file) ? JSON.parse((0, node_fs_1.readFileSync)(file, "utf8")) : null;
+}
+function writeManifest(projectRoot, manifest) {
+    (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
+    (0, node_fs_1.writeFileSync)(manifestPath(projectRoot), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function writeFilesLock(projectRoot, lock) {
+    (0, node_fs_1.mkdirSync)(podokitDir(projectRoot), { recursive: true });
+    (0, node_fs_1.writeFileSync)(filesLockPath(projectRoot), `${JSON.stringify(lock, null, 2)}\n`);
+}
+/** Read the PodoKit CLI's own version to stamp into the manifest. */
+function podokitVersion() {
+    try {
+        const pkg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Match a POSIX relative path against a simple glob supporting `*` and `**`. */
+function matchGlob(path, glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    // Single pass so replacement output is never re-scanned.
+    const pattern = escaped.replace(/\/\*\*$|\*\*\/|\*\*|\*/g, (token) => {
+        if (token === "/**")
+            return "(?:/.*)?"; // trailing `/**`: the dir itself or anything under it
+        if (token === "**/")
+            return "(?:.*/)?"; // `**/`: zero or more leading segments
+        if (token === "**")
+            return ".*"; // `**`: any characters
+        return "[^/]*"; // `*`: within a single segment
+    });
+    return new RegExp(`^${pattern}$`).test(path);
+}
+function isTextPath(relPath) {
+    return relPath.startsWith("dot-") || TEXT_EXT.test(relPath);
+}
+/** Classify a file's ownership tier. See ADR-0010 priority order. */
+function classifyTier(relPath, content, ownedGlobs) {
+    if (ownedGlobs.some((glob) => matchGlob(relPath, glob)))
+        return "owned";
+    if (isTextPath(relPath) && content.toString("utf8").includes(INJECTION_MARKER))
+        return "assembled";
+    return "managed";
+}
+/** List project files as POSIX-relative paths, skipping generated/vendored dirs. */
+function walkFiles(projectRoot, prefix = "") {
+    const out = [];
+    for (const entry of (0, node_fs_1.readdirSync)((0, node_path_1.join)(projectRoot, prefix))) {
+        if (WALK_IGNORE.has(entry))
+            continue;
+        const rel = prefix ? `${prefix}/${entry}` : entry;
+        if ((0, node_fs_1.statSync)((0, node_path_1.join)(projectRoot, rel)).isDirectory()) {
+            out.push(...walkFiles(projectRoot, rel));
+        }
+        else {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+/** Recompute the files.lock by hashing and classifying every project file. */
+function computeFilesLock(projectRoot, ownedGlobs) {
+    const files = {};
+    for (const rel of walkFiles(projectRoot).sort()) {
+        const content = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, rel));
+        files[rel] = { tier: classifyTier(rel, content, ownedGlobs), outHash: (0, podokit_template_engine_1.hashContent)(content) };
+    }
+    return { schemaVersion: exports.LOCK_SCHEMA_VERSION, files };
+}
+function readFilesLock(projectRoot) {
+    const file = filesLockPath(projectRoot);
+    return (0, node_fs_1.existsSync)(file) ? JSON.parse((0, node_fs_1.readFileSync)(file, "utf8")) : null;
+}
+/**
+ * Compare the current disk against the lock: report managed/assembled files the
+ * user has edited (hash mismatch) or deleted. Owned files are never reported —
+ * they belong to the user. Returns empty drift when there is no lock.
+ */
+function computeDrift(projectRoot) {
+    const lock = readFilesLock(projectRoot);
+    const drifted = [];
+    const missing = [];
+    if (!lock)
+        return { drifted, missing };
+    for (const [rel, entry] of Object.entries(lock.files)) {
+        if (entry.tier === "owned")
+            continue;
+        const abs = (0, node_path_1.join)(projectRoot, rel);
+        if (!(0, node_fs_1.existsSync)(abs)) {
+            missing.push(rel);
+            continue;
+        }
+        if ((0, podokit_template_engine_1.hashContent)((0, node_fs_1.readFileSync)(abs)) !== entry.outHash)
+            drifted.push(rel);
+    }
+    return { drifted: drifted.sort(), missing: missing.sort() };
+}
+/** Write the initial `.podokit/` lockfile for a freshly created project. */
+function initLockfile(projectRoot, options) {
+    const ownedGlobs = options.ownedGlobs ?? exports.DEFAULT_OWNED_GLOBS;
+    const manifest = {
+        schemaVersion: exports.LOCK_SCHEMA_VERSION,
+        podokitVersion: options.version ?? podokitVersion(),
+        template: options.template,
+        packageManager: options.packageManager,
+        answers: options.answers,
+        modules: [],
+        ownedGlobs,
+    };
+    writeManifest(projectRoot, manifest);
+    writeFilesLock(projectRoot, computeFilesLock(projectRoot, ownedGlobs));
+}
+/**
+ * Record applied modules in the manifest and recompute the files.lock. Modules
+ * already present are left in place (idempotent); the lock always reflects disk.
+ * No-op on projects without a manifest (pre-lockfile projects; see `podo adopt`).
+ */
+function recordModules(projectRoot, moduleNames, version) {
+    const manifest = readManifest(projectRoot);
+    if (!manifest)
+        return;
+    const stampedWith = version ?? podokitVersion();
+    const known = new Set(manifest.modules.map((m) => m.name));
+    for (const name of moduleNames) {
+        if (known.has(name))
+            continue;
+        manifest.modules.push({ name, order: manifest.modules.length, addedWith: stampedWith });
+        known.add(name);
+    }
+    writeManifest(projectRoot, manifest);
+    writeFilesLock(projectRoot, computeFilesLock(projectRoot, manifest.ownedGlobs));
+}

package/dist/templates/base/dot-env.example

@@ -1,15 +1,20 @@
 # Copy to .env and adjust. Never commit real secrets.
+
+# ── Required (runtime) ───────────────────────────────────────────────
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
 POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 
+APP_BASE_URL=http://localhost:5001
+API_BASE_URL=http://localhost:5002
+BACKEND_INTERNAL_URL=http://localhost:5002
+CORS_ORIGIN=http://localhost:5001
+PORT=5002
+
+# ── Optional / development ───────────────────────────────────────────
+# Redis — only needed by cache/queue modules. Start it with:
+# docker compose --profile cache up
 REDIS_HOST=localhost
 REDIS_PORT=6379
-
-APP_BASE_URL=http://localhost:5173
-API_BASE_URL=http://localhost:3000
-BACKEND_INTERNAL_URL=http://localhost:3000
-CORS_ORIGIN=http://localhost:5173
-PORT=3000

package/dist/templates/fullstack-nest-svelte/README.md

@@ -18,8 +18,8 @@ docker compose -f infra/docker/docker-compose.yml up -d
 {{packageManager}} run dev
 ```
 
-- API: http://localhost:3000 — health at `/health`, docs at `/api-docs`
-- Web: http://localhost:5173
+- API: http://localhost:5002 — health at `/health`, docs at `/api-docs`
+- Web: http://localhost:5001
 
 ## Database & migrations
 

package/dist/templates/fullstack-nest-svelte/apps/api/package.json

@@ -7,13 +7,14 @@
     "build": "nest build",
     "start": "node dist/main",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "jest",
+    "test": "jest --passWithNoTests",
     "typeorm": "typeorm-ts-node-commonjs -d src/database/data-source.ts",
     "migration:run": "npm run typeorm -- migration:run",
     "migration:revert": "npm run typeorm -- migration:revert",
     "migration:generate": "npm run typeorm -- migration:generate"
   },
   "dependencies": {
+    "@podosoft/podokit-contracts": "^0.1.0",
     "@nestjs/common": "^11.1.27",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.27",
@@ -39,6 +40,24 @@
     "supertest": "^7.0.0",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
-    "typescript": "^5.6.3"
+    "typescript": "^6.0.3"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.ts$": [
+        "ts-jest",
+        {
+          "tsconfig": "tsconfig.json"
+        }
+      ]
+    },
+    "testEnvironment": "node"
   }
 }

package/dist/templates/fullstack-nest-svelte/apps/api/src/app.module.ts

@@ -4,17 +4,20 @@ import { TypeOrmModule } from "@nestjs/typeorm";
 import { validateEnv } from "./config/env.validation";
 import { dataSourceOptions } from "./database/data-source";
 import { HealthModule } from "./health/health.module";
-// podokit:imports
+// podokit:begin:imports
+// podokit:end:imports
 
 @Module({
   imports: [
     ConfigModule.forRoot({ isGlobal: true, validate: validateEnv }),
     TypeOrmModule.forRoot(dataSourceOptions),
     HealthModule,
-    // podokit:module-imports
+    // podokit:begin:module-imports
+    // podokit:end:module-imports
   ],
   providers: [
-    // podokit:providers
+    // podokit:begin:providers
+    // podokit:end:providers
   ],
 })
 export class AppModule {}

package/dist/templates/fullstack-nest-svelte/apps/api/src/common/app-exception.ts

@@ -1,12 +1,4 @@
-// Stable, language-independent error codes. The frontend branches on `code`,
-// not on the human-readable message.
-export class AppException extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    readonly statusCode = 400,
-  ) {
-    super(message);
-    this.name = "AppException";
-  }
-}
+// AppException is a shared contract (stable, language-independent error `code`
+// the frontend branches on). Re-exported from @podosoft/podokit-contracts so the
+// backend and any other layer reference one definition.
+export { AppException } from "@podosoft/podokit-contracts";

package/dist/templates/fullstack-nest-svelte/apps/api/src/config/env.validation.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 // Schema-validated environment. Fails fast at boot if something is wrong.
 const schema = z.object({
   NODE_ENV: z.string().default("development"),
-  PORT: z.coerce.number().default(3000),
+  PORT: z.coerce.number().default(5002),
   CORS_ORIGIN: z.string().optional(),
   POSTGRES_HOST: z.string().default("localhost"),
   POSTGRES_PORT: z.coerce.number().default(5432),

package/dist/templates/fullstack-nest-svelte/apps/api/src/main.ts

@@ -22,7 +22,7 @@ async function bootstrap(): Promise<void> {
     .build();
   SwaggerModule.setup("api-docs", app, SwaggerModule.createDocument(app, config));
 
-  const port = Number(process.env.PORT ?? 3000);
+  const port = Number(process.env.PORT ?? 5002);
   await app.listen(port);
 }
 

package/dist/templates/fullstack-nest-svelte/apps/api/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
-    "module": "CommonJS",
+    "module": "nodenext",
     "target": "ES2022",
-    "moduleResolution": "Node",
+    "moduleResolution": "nodenext",
     "outDir": "dist",
     "rootDir": "src",
     "declaration": false,
@@ -14,8 +14,17 @@
     "noImplicitReturns": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
+    "forceConsistentCasingInFileNames": true,
+    "types": [
+      "node"
+    ]
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist", "test"]
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test"
+  ]
 }

package/dist/templates/fullstack-nest-svelte/apps/web/package.json

@@ -4,15 +4,16 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "vite dev --port 5173",
+    "dev": "vite dev --port 5001",
     "build": "vite build",
     "preview": "vite preview",
     "lint": "svelte-check --tsconfig ./tsconfig.json",
-    "test": "echo \"add Playwright tests here\" && exit 0"
+    "test": "echo \"unit: add vitest; e2e: npm run test:e2e (see tests/)\" && exit 0"
   },
   "dependencies": {
     "@internationalized/date": "^3.12.2",
     "@lucide/svelte": "^1.23.0",
+    "@podosoft/podokit-api-client": "^0.5.0",
     "bits-ui": "^2.18.1",
     "clsx": "^2.1.1",
     "mode-watcher": "^1.1.0",
@@ -29,7 +30,7 @@
     "svelte-check": "^4.0.0",
     "tailwindcss": "^4.0.0",
     "typesafe-i18n": "^5.26.2",
-    "typescript": "^5.6.3",
+    "typescript": "^6.0.3",
     "vite": "^5.4.0",
     "tw-animate-css": "^1.4.0"
   }

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/api.ts

@@ -0,0 +1,5 @@
+import { createApiClient } from "@podosoft/podokit-api-client";
+
+// Browser client: same-origin. REST calls go to /api/* and auth to /api/auth/*,
+// both proxied to the backend by the SvelteKit server (see routes/api/**).
+export const api = createApiClient();

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/ui/select/select-content.svelte

@@ -27,7 +27,7 @@
 		{preventScroll}
 		data-slot="select-content"
 		class={cn(
-			"bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 min-w-36 rounded-lg shadow-md ring-1 duration-100 data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 relative isolate z-50 overflow-x-hidden overflow-y-auto",
+			"bg-popover text-popover-foreground data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 min-w-36 rounded-lg p-1 shadow-md ring-1 duration-100 data-[side=inline-start]:slide-in-from-right-2 data-[side=inline-end]:slide-in-from-left-2 relative isolate z-50 max-h-96 overflow-x-hidden overflow-y-auto",
 			className
 		)}
 		{...restProps}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/ui/select/select-item.svelte

@@ -26,7 +26,7 @@
 	{#snippet children({ selected, highlighted })}
 		<span class="absolute end-2 flex size-3.5 items-center justify-center">
 			{#if selected}
-				<CheckIcon class="cn-select-item-indicator-icon" />
+				<CheckIcon class="size-3.5" />
 			{/if}
 		</span>
 		<span class="flex flex-1 gap-2 shrink-0 whitespace-nowrap">

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/ui/switch/index.ts

@@ -0,0 +1,7 @@
+import Root from "./switch.svelte";
+
+export {
+	Root,
+	//
+	Root as Switch,
+};

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/components/ui/switch/switch.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { Switch as SwitchPrimitive } from "bits-ui";
+	import { cn, type WithoutChildrenOrChild } from "$lib/utils.js";
+
+	let {
+		ref = $bindable(null),
+		checked = $bindable(false),
+		class: className,
+		...restProps
+	}: WithoutChildrenOrChild<SwitchPrimitive.RootProps> = $props();
+</script>
+
+<SwitchPrimitive.Root
+	bind:ref
+	data-slot="switch"
+	class={cn(
+		"peer focus-visible:border-ring focus-visible:ring-ring/50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+		className
+	)}
+	bind:checked
+	{...restProps}
+>
+	<SwitchPrimitive.Thumb
+		data-slot="switch-thumb"
+		class={cn(
+			"bg-background pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0"
+		)}
+	/>
+</SwitchPrimitive.Root>

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/api.ts

@@ -0,0 +1,19 @@
+import type { RequestEvent } from "@sveltejs/kit";
+import { createApiClient, type ApiClient } from "@podosoft/podokit-api-client";
+import { backendBaseUrl } from "./backend-proxy";
+
+// Server-side client for load functions and hooks: points at the internal
+// backend URL and forwards the incoming request's cookies.
+export function serverApiClient(event: RequestEvent): ApiClient {
+  const cookie = event.request.headers.get("cookie") ?? "";
+  const fetchWithCookies: typeof fetch = (input, init) => {
+    const headers = new Headers(init?.headers);
+    if (cookie) headers.set("cookie", cookie);
+    return event.fetch(input, { ...init, headers });
+  };
+  return createApiClient({
+    baseUrl: backendBaseUrl(),
+    apiBasePath: "",
+    fetch: fetchWithCookies,
+  });
+}

package/dist/templates/fullstack-nest-svelte/apps/web/src/lib/server/backend-proxy.ts

@@ -1,16 +1,55 @@
 // Server-side proxy boundary. The browser never talks to the API directly:
-// only these allowlisted headers are forwarded to BACKEND_INTERNAL_URL.
-const FORWARDED_HEADERS = ["authorization", "cookie", "content-type"];
+// requests go through SvelteKit server routes, which forward an allowlist of
+// headers to BACKEND_INTERNAL_URL and relay the response (including Set-Cookie).
+const FORWARDED_HEADERS = ["authorization", "cookie", "content-type", "accept", "origin", "referer"];
+const RELAYED_RESPONSE_HEADERS = ["content-type", "location", "cache-control"];
 
 export function backendBaseUrl(): string {
-  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:3000";
+  return process.env.BACKEND_INTERNAL_URL ?? "http://localhost:5002";
 }
 
-export function backendProxyHeaders(request: Request): Headers {
+// Normalize the resolved client IP for the forwarded header. better-auth stores
+// IPv4 as-is but anonymizes IPv6 (masks the host bits), so an IPv6 loopback would
+// be recorded as "::" — map loopback to 127.0.0.1 for a clean local value, and
+// unwrap IPv4-mapped addresses.
+function normalizeClientIp(address: string | undefined): string | undefined {
+  if (!address) return undefined;
+  if (address === "::1" || address === "::") return "127.0.0.1";
+  if (address.startsWith("::ffff:")) return address.slice("::ffff:".length);
+  return address;
+}
+
+export async function proxyRequest(
+  request: Request,
+  targetUrl: string,
+  clientAddress?: string,
+): Promise<Response> {
   const headers = new Headers();
   for (const name of FORWARDED_HEADERS) {
     const value = request.headers.get(name);
     if (value) headers.set(name, value);
   }
-  return headers;
+  // Forward the resolved client IP so the API (better-auth) can record it.
+  const forwardedIp = normalizeClientIp(clientAddress);
+  if (forwardedIp) headers.set("x-forwarded-for", forwardedIp);
+
+  const hasBody = request.method !== "GET" && request.method !== "HEAD";
+  const upstream = await fetch(targetUrl, {
+    method: request.method,
+    headers,
+    body: hasBody ? await request.text() : undefined,
+    redirect: "manual",
+  });
+
+  const responseHeaders = new Headers();
+  for (const name of RELAYED_RESPONSE_HEADERS) {
+    const value = upstream.headers.get(name);
+    if (value) responseHeaders.set(name, value);
+  }
+  // Relay Set-Cookie so auth session cookies reach the browser.
+  for (const cookie of upstream.headers.getSetCookie()) {
+    responseHeaders.append("set-cookie", cookie);
+  }
+
+  return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
 }

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/+page.svelte

@@ -1,14 +1,19 @@
 <script lang="ts">
   import { Button } from "$lib/components/ui/button";
   import * as Card from "$lib/components/ui/card";
+  import { api } from "$lib/api";
+  import { ApiError } from "@podosoft/podokit-api-client";
 
   type Health = { status: string } | { error: string };
 
   let health = $state<Health | null>(null);
 
   async function check(): Promise<void> {
-    const res = await fetch("/api/health");
-    health = res.ok ? await res.json() : { error: `HTTP ${res.status}` };
+    try {
+      health = await api.get<{ status: string }>("/health");
+    } catch (err) {
+      health = { error: err instanceof ApiError ? `${err.code} (${err.statusCode})` : "Request failed" };
+    }
   }
 </script>
 
@@ -21,7 +26,7 @@
   <Card.Root>
     <Card.Header>
       <Card.Title>API health</Card.Title>
-      <Card.Description>Check the NestJS API through the SvelteKit server proxy.</Card.Description>
+      <Card.Description>Check the NestJS API through the typed ApiClient.</Card.Description>
     </Card.Header>
     <Card.Content class="flex flex-col gap-4">
       <Button class="w-fit" onclick={check}>Check API health</Button>

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/api/[...path]/+server.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from "@sveltejs/kit";
+import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+
+// Proxy the app's REST API, stripping the /api prefix (backend routes are at root).
+const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+  proxyRequest(request, `${backendBaseUrl()}/${params.path}${url.search}`, getClientAddress());
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;

package/dist/templates/fullstack-nest-svelte/apps/web/src/routes/api/auth/[...all]/+server.ts

@@ -0,0 +1,12 @@
+import type { RequestHandler } from "@sveltejs/kit";
+import { backendBaseUrl, proxyRequest } from "$lib/server/backend-proxy";
+
+// Proxy the better-auth handler, keeping the /api/auth prefix.
+const handler: RequestHandler = ({ request, params, url, getClientAddress }) =>
+  proxyRequest(request, `${backendBaseUrl()}/api/auth/${params.all}${url.search}`, getClientAddress());
+
+export const GET = handler;
+export const POST = handler;
+export const PUT = handler;
+export const PATCH = handler;
+export const DELETE = handler;

package/dist/templates/fullstack-nest-svelte/dot-env.example

@@ -1,6 +1,8 @@
 # Copy to .env and adjust. Never commit real secrets.
+
+# ── Required (runtime) ───────────────────────────────────────────────
 NODE_ENV=development
-PORT=3000
+PORT=5002
 
 POSTGRES_HOST=localhost
 POSTGRES_PORT=5432
@@ -8,9 +10,12 @@ POSTGRES_USER=podokit
 POSTGRES_PASSWORD=podokit
 POSTGRES_DB=podokit
 
+# Web -> API boundary (server-side only; not exposed to the browser)
+BACKEND_INTERNAL_URL=http://localhost:5002
+CORS_ORIGIN=http://localhost:5001
+
+# ── Optional / development ───────────────────────────────────────────
+# Redis — only needed by cache/queue modules (redis, bullmq, rate-limit,
+# job-progress, sse). Start it with: docker compose --profile cache up
 REDIS_HOST=localhost
 REDIS_PORT=6379
-
-# Web -> API boundary (server-side only; not exposed to the browser)
-BACKEND_INTERNAL_URL=http://localhost:3000
-CORS_ORIGIN=http://localhost:5173

package/dist/templates/fullstack-nest-svelte/dot-gitignore

@@ -7,3 +7,8 @@ build/
 !.env.example
 .DS_Store
 *.log
+
+# e2e test artifacts
+tests/playwright/
+tests/playwright-report/
+tests/test-results/