create-basalt 1.14.2 → 1.16.0

package/README.md

@@ -505,7 +505,7 @@ Outside an interactive terminal (no TTY) the questions are skipped. Always pass
 Automatic installation failed (network, Node version, etc.). Go into the folder and run `pnpm install` (or the indicated manager) to see the real error.
 
 **I started the app and `GET /auth/login` gives a secret error.**
-With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). For development the scaffold's `.env` carries a generated one; in production export your own (`openssl rand -base64 48`) — `pnpm start` does not read `.env`.
+With auth on, `src/env.ts` requires `APP_SECRET` — read as `MY_SAAS_APP_SECRET`, with at least 32 characters (`secret()` supplies a development default only when `NODE_ENV` is explicitly `development`/`test`). For development the scaffold's `.env` carries a generated one; in production export your own (`openssl rand -base64 48`) or put it in the server's `.env` — `pnpm start` loads `.env` (an exported variable wins) and, with `NODE_ENV` unset, runs as production.
 
 **`The app cannot start — the database did not answer`.**
 PostgreSQL is not running, or `MY_SAAS_DATABASE_URL` points at the wrong host/port (the message shows which, without credentials). Start it (`docker compose up -d`, or your local service) or fix the URL in `.env`; on a fresh database, `pnpm db:migrate`. `pnpm dev` still prints the raw error (the explainer lives in `bin/basalt.ts` only, so `src/dev.ts` stays a few lines); `pnpm basalt routes` gives the explained version.

package/dist/bin-template.d.ts

@@ -4,6 +4,8 @@ export declare const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'inf
 export declare const DEV_PRELUDE_MARKER = "process.loadEnvFile(envFile)";
 /** Marker proving a bin/basalt.ts already runs the generators without booting the app. */
 export declare const GENERATORS_PRELUDE_MARKER = "process.argv[2]?.startsWith('make:')";
+/** Marker proving a bin/basalt.ts already starts `dev` without booting the app. */
+export declare const DEV_SERVER_PRELUDE_MARKER = "if (process.argv[2] === 'dev')";
 export declare function basaltBin(): string;
 /**
  * Hashes of every bin/basalt.ts an earlier create-basalt release generated
@@ -14,6 +16,7 @@ export declare const LEGACY_BIN_HASHES: ReadonlySet<string>;
 export declare const hasProjectCommands: (content: string) => boolean;
 export declare const hasDevPrelude: (content: string) => boolean;
 export declare const hasGeneratorsPrelude: (content: string) => boolean;
+export declare const hasDevServerPrelude: (content: string) => boolean;
 /**
  * Upgrades a template-generated bin/basalt.ts to the current template, step by
  * step: (1) without the project commands, inserts their prelude after the
@@ -21,8 +24,9 @@ export declare const hasGeneratorsPrelude: (content: string) => boolean;
  * longer run before it); (2) without the dev prelude, inserts it right after
  * the project commands and routes the app import through `explainBootFailure`;
  * (3) without the generators prelude, inserts it right before the dev tools
- * are imported for the booted CLI.
- * Deterministic for the known templates — for the latest ones (1.9 to 1.14) the
+ * are imported for the booted CLI; (4) without the dev server prelude, inserts
+ * it at the same place, after the generators prelude.
+ * Deterministic for the known templates — for the latest ones (1.9 to 1.15) the
  * result is exactly {@link basaltBin}.
  */
 export declare function patchBasaltBin(content: string): string;

package/dist/bin-template.js

@@ -197,12 +197,31 @@ if (process.argv[2]?.startsWith('make:')) {
   }
 }
 `;
+/**
+ * The DEV SERVER PRELUDE, after the generators prelude and still before
+ * anything of the app is imported: `basalt dev` must start while the app
+ * cannot boot (a variable missing, the database down, code mid-edit) — that
+ * is when a watcher is needed. `runDev` boots the app only for the route
+ * table, prints why when it does not, and starts the watcher either way.
+ */
+const DEV_SERVER_PRELUDE = `// \`dev\` starts the watcher even while the app cannot boot (database down, a
+// variable missing, code mid-edit): the route table is printed when it boots.
+if (process.argv[2] === 'dev') {
+  const { runDev } = await import('@basaltkit/cli')
+  process.env['NODE_ENV'] ??= 'development'
+  process.exit(await runDev({
+    loadApp: async () => (await import('../src/app.js')).buildApp({ logLevel: 'silent' }),
+  }))
+}
+`;
 /** Marker proving a bin/basalt.ts already delegates the project commands. */
 export const PROJECT_COMMANDS_MARKER = "['update', 'add', 'doctor', 'info'].includes(process.argv[2]";
 /** Marker proving a bin/basalt.ts already has the dev prelude (.env loading, `upgrade`, env errors). */
 export const DEV_PRELUDE_MARKER = 'process.loadEnvFile(envFile)';
 /** Marker proving a bin/basalt.ts already runs the generators without booting the app. */
 export const GENERATORS_PRELUDE_MARKER = "process.argv[2]?.startsWith('make:')";
+/** Marker proving a bin/basalt.ts already starts `dev` without booting the app. */
+export const DEV_SERVER_PRELUDE_MARKER = "if (process.argv[2] === 'dev')";
 const APP_IMPORT = "await import('../src/app.js')";
 const APP_IMPORT_EXPLAINED = `${APP_IMPORT}.catch(explainBootFailure)`;
 const RUN_CLI = 'process.exit(await runCli({ app })';
@@ -211,6 +230,7 @@ export function basaltBin() {
 ${PRELUDE}
 ${DEV_PRELUDE}
 ${GENERATORS_PRELUDE}
+${DEV_SERVER_PRELUDE}
 // The dev tools are imported dynamically, after the project commands above.
 const { runCli } = await import('@basaltkit/cli')
 const { generatorCommands } = await import('@basaltkit/generator')
@@ -259,10 +279,14 @@ export const LEGACY_BIN_HASHES = new Set([
     'sha256-bd0b6c9c40089a18c2c2f1a70953044d6a74a329d38a72903b494b1f2265a114',
     // 2026-10-08: database diagnoses in explainBootFailure — make:* still booted.
     'sha256-abea8cbfdb41a302cabad7929617f7fc2fe822345aa8db6ff777e923eb0fc96b',
+    // 2026-10-25 (create-basalt ≤ 1.15): make:* without a boot — but `dev`
+    // booted the app first, so it did not start while the app could not boot.
+    'sha256-5c2cf3f431399b961de890af457c7be5f9a0cb810cd96d6bdf080ac942e33f1b',
 ]);
 export const hasProjectCommands = (content) => content.includes(PROJECT_COMMANDS_MARKER);
 export const hasDevPrelude = (content) => content.includes(DEV_PRELUDE_MARKER);
 export const hasGeneratorsPrelude = (content) => content.includes(GENERATORS_PRELUDE_MARKER);
+export const hasDevServerPrelude = (content) => content.includes(DEV_SERVER_PRELUDE_MARKER);
 /**
  * Upgrades a template-generated bin/basalt.ts to the current template, step by
  * step: (1) without the project commands, inserts their prelude after the
@@ -270,8 +294,9 @@ export const hasGeneratorsPrelude = (content) => content.includes(GENERATORS_PRE
  * longer run before it); (2) without the dev prelude, inserts it right after
  * the project commands and routes the app import through `explainBootFailure`;
  * (3) without the generators prelude, inserts it right before the dev tools
- * are imported for the booted CLI.
- * Deterministic for the known templates — for the latest ones (1.9 to 1.14) the
+ * are imported for the booted CLI; (4) without the dev server prelude, inserts
+ * it at the same place, after the generators prelude.
+ * Deterministic for the known templates — for the latest ones (1.9 to 1.15) the
  * result is exactly {@link basaltBin}.
  */
 export function patchBasaltBin(content) {
@@ -282,6 +307,8 @@ export function patchBasaltBin(content) {
         text = addDevPrelude(text);
     if (!hasGeneratorsPrelude(text))
         text = addGeneratorsPrelude(text);
+    if (!hasDevServerPrelude(text))
+        text = addDevServerPrelude(text);
     return text;
 }
 function addProjectCommands(content) {
@@ -317,11 +344,19 @@ function addGeneratorsPrelude(content) {
         return content;
     return `${content.slice(0, anchor.index)}${GENERATORS_PRELUDE}\n${content.slice(anchor.index)}`;
 }
+/** Inserts the dev server prelude right before the dev tools are imported for the booted CLI (after the generators prelude). */
+function addDevServerPrelude(content) {
+    const anchor = /^(?:\/\/ The dev tools are imported dynamically[^\n]*\n)?const \{ runCli \} = await import\('@basaltkit\/cli'\)$/m.exec(content);
+    // Without the template's dynamic CLI import, the file is not ours to rearrange.
+    if (!anchor || !hasGeneratorsPrelude(content))
+        return content;
+    return `${content.slice(0, anchor.index)}${DEV_SERVER_PRELUDE}\n${content.slice(anchor.index)}`;
+}
 /** Where a bin/basalt.ts stands: already current, an untouched old template, or user code. */
 export function binStatus(content, manifestHash) {
     if (content === undefined)
         return 'absent';
-    if (hasProjectCommands(content) && hasDevPrelude(content) && hasGeneratorsPrelude(content))
+    if (hasProjectCommands(content) && hasDevPrelude(content) && hasGeneratorsPrelude(content) && hasDevServerPrelude(content))
         return 'current';
     const hash = hashContent(content);
     return LEGACY_BIN_HASHES.has(hash) || hash === manifestHash ? 'patchable' : 'modified';
@@ -351,6 +386,13 @@ booted CLI) — it runs the make:* generators without booting the app, so they
 work before the database is up or migrated:
 
 ${GENERATORS_PRELUDE}`);
+    }
+    if (!hasDevServerPrelude(content)) {
+        steps.push(`${steps.length > 0 ? 'Then paste' : 'Paste'} this after the generators prelude (before the dev tools are imported for
+the booted CLI) — \`basalt dev\` then starts its watcher even while the app cannot
+boot (database down, a variable missing):
+
+${DEV_SERVER_PRELUDE}`);
     }
     return steps.join('\n');
 }

package/dist/dev-entry.d.ts

@@ -16,8 +16,9 @@ export declare const patchDevEntry: () => string;
 /** What to paste by hand into a customised src/dev.ts. */
 export declare const MANUAL_DEV_SNIPPET = "Paste this at the top of src/dev.ts, BEFORE the server is imported (keep that\nimport dynamic \u2014 `await import('./server.js')` \u2014 so the variables are set first):\n\nimport { existsSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\n\n// Development loads .env (when present) like `node --env-file=.env`: a variable\n// already exported in your shell still wins, the file only fills in what is missing.\nconst envFile = fileURLToPath(new URL('../.env', import.meta.url))\nif (existsSync(envFile)) process.loadEnvFile(envFile)\n";
 /**
- * `.env.example` with the old "nothing loads this file" lead swapped for the
- * current one; undefined when the file does not start with the old lead (a
+ * `.env.example` with an earlier lead ("nothing loads this file", or "`pnpm
+ * start` does NOT") swapped for the current one; undefined when the file does
+ * not start with one of them (a
  * newer or hand-written file is left alone — it is only comments).
  */
 export declare function patchEnvExample(content: string): string | undefined;

package/dist/dev-entry.js

@@ -1,5 +1,5 @@
 import { hashContent } from './project/manifest.js';
-import { devTs, ENV_EXAMPLE_LEAD, LEGACY_ENV_EXAMPLE_LEAD } from './templates.js';
+import { devTs, ENV_EXAMPLE_LEAD, LEGACY_ENV_EXAMPLE_LEAD, PREVIOUS_ENV_EXAMPLE_LEAD } from './templates.js';
 /**
  * `src/dev.ts` (the `pnpm dev` entrypoint) and the `.env.example` header across
  * create-basalt releases. Up to 1.10, nothing loaded `.env`: `pnpm dev` booted
@@ -37,13 +37,15 @@ const envFile = fileURLToPath(new URL('../.env', import.meta.url))
 if (existsSync(envFile)) process.loadEnvFile(envFile)
 `;
 /**
- * `.env.example` with the old "nothing loads this file" lead swapped for the
- * current one; undefined when the file does not start with the old lead (a
+ * `.env.example` with an earlier lead ("nothing loads this file", or "`pnpm
+ * start` does NOT") swapped for the current one; undefined when the file does
+ * not start with one of them (a
  * newer or hand-written file is left alone — it is only comments).
  */
 export function patchEnvExample(content) {
     const normalized = content.replace(/\r\n/g, '\n');
-    if (!normalized.startsWith(`${LEGACY_ENV_EXAMPLE_LEAD}\n`))
+    const lead = [LEGACY_ENV_EXAMPLE_LEAD, PREVIOUS_ENV_EXAMPLE_LEAD].find((old) => normalized.startsWith(`${old}\n`));
+    if (lead === undefined)
         return undefined;
-    return `${ENV_EXAMPLE_LEAD}${normalized.slice(LEGACY_ENV_EXAMPLE_LEAD.length)}`;
+    return `${ENV_EXAMPLE_LEAD}${normalized.slice(lead.length)}`;
 }

package/dist/project/doctor.js

@@ -6,7 +6,7 @@ import { binStatus } from '../bin-template.js';
 import { devEntryStatus } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions } from '../latest-versions.js';
 import { PRODUCTION_ENTRY } from '../stubs.js';
-import { envPrefix } from '../templates.js';
+import { envPrefix, PREVIOUS_START_SCRIPT, START_SCRIPT } from '../templates.js';
 import { allDependencies } from './context.js';
 import { ownVersion } from './manifest.js';
 import { LEGACY_PRISMA_OUTPUT, RUNS_TSX } from './production.js';
@@ -382,7 +382,7 @@ export async function runDoctor(ctx, options = {}) {
     const bin = await readText(join(dir, 'bin', 'basalt.ts'));
     const status = binStatus(bin, ctx.manifest?.files['bin/basalt.ts']);
     if (status === 'patchable') {
-        push('warn', 'tooling', 'bin/basalt.ts is an older template (it lacks some of: .env loading, pre-boot project commands, make:* without booting the app) — `npx create-basalt@latest update` patches it.');
+        push('warn', 'tooling', 'bin/basalt.ts is an older template (it lacks some of: .env loading, pre-boot project commands, make:* and dev without booting the app) — `npx create-basalt@latest update` patches it.');
     }
     if (status === 'modified') {
         push('info', 'tooling', 'bin/basalt.ts is customised and lacks the current preludes (project commands, .env loading, pre-boot `upgrade` and make:*) — see `create-basalt update` for the snippet.');
@@ -403,6 +403,12 @@ export async function runDoctor(ctx, options = {}) {
     if (start !== undefined && RUNS_TSX.test(start) && tsxIsDevOnly) {
         push('warn', 'build', `\`start\` runs tsx ("${start}"), but tsx is only a devDependency — a production install (--prod) has no tsx. Build and run the compiled server: \`npx create-basalt@latest update\` prints the scripts.`);
     }
+    if (start === PREVIOUS_START_SCRIPT) {
+        push('info', 'build', `\`start\` loads no .env ("${start}") — fine where the platform exports the environment; \`npx create-basalt@latest update\` switches it to \`${START_SCRIPT}\`.`);
+    }
+    if (start !== undefined && /--env-file/.test(start) && /^\s*NODE_ENV\s*=\s*["']?development["']?\s*$/m.test((await readText(join(dir, '.env'))) ?? '')) {
+        push('warn', 'build', '.env sets NODE_ENV=development and `start` loads .env: a production start boots in development, with the dev secret defaults. Remove the line — `dev` and `basalt` set it themselves.');
+    }
     if (scripts['build'] === undefined) {
         push('warn', 'build', `No \`build\` script — there is no tested way to run the app on plain node. \`npx create-basalt@latest update\` adds tsconfig.build.json and \`build\`.`);
     }

package/dist/project/production.d.ts

@@ -2,9 +2,12 @@
  * The production path (BK-026) for an app scaffolded before create-basalt
  * shipped one: `create-basalt update` OFFERS what is missing — it is part of
  * the printed plan, applied only on confirmation — and never rewrites what the
- * app already has. In particular an existing `start` script is never changed:
+ * app already has. In particular a customised `start` script is never changed:
  * switching it from tsx to the compiled server changes how the app is
- * deployed, so that is printed as a manual step.
+ * deployed, so that is printed as a manual step. Only the exact `start` an
+ * earlier create-basalt wrote ({@link PREVIOUS_START_SCRIPT}) is offered the
+ * `.env` loading — under @basaltkit/deploy's pm2 runtime before 0.10 it booted
+ * without its secrets.
  */
 export interface ProductionPathPlan {
     /** New files: path → content (only files that do not exist yet). */
@@ -20,7 +23,8 @@ export interface ProductionPathPlan {
 export declare const LEGACY_PRISMA_OUTPUT: RegExp;
 /** `start` (or any script) that runs TypeScript through tsx. */
 export declare const RUNS_TSX: RegExp;
-export declare const MANUAL_START_SNIPPET = "In package.json, run the compiled server in production (build first: `pnpm build`):\n  \"start\": \"node --enable-source-maps dist/src/server.js\",\n  \"start:dev\": \"tsx src/server.ts\"";
+export declare const MANUAL_START_SNIPPET = "In package.json, run the compiled server in production (build first: `pnpm build`):\n  \"start\": \"node --env-file-if-exists=.env --enable-source-maps dist/src/server.js\",\n  \"start:dev\": \"tsx src/server.ts\"";
+export declare const MANUAL_NODE_ENV_SNIPPET = "Remove NODE_ENV=development from .env: `pnpm dev` and `pnpm basalt` already set it, and\n`pnpm start` now loads .env \u2014 with that line it would boot in development, accepting the dev secret\ndefaults instead of requiring the real ones.";
 export declare const MANUAL_PRISMA_LAYOUT_SNIPPET: string;
 /**
  * What an existing app lacks of the production path: tsconfig.build.json, a

package/dist/project/production.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { DOCKERFILE, DOCKERIGNORE, PRODUCTION_ENTRY } from '../stubs.js';
-import { BUILD_SCRIPT, PRISMA_IMPORTS, START_DEV_SCRIPT, START_SCRIPT, tsconfigBuildJson } from '../templates.js';
+import { BUILD_SCRIPT, ENGINES_NODE, PREVIOUS_START_SCRIPT, PRISMA_IMPORTS, START_DEV_SCRIPT, START_SCRIPT, tsconfigBuildJson } from '../templates.js';
 import { mergePackageJson } from './package-json.js';
 /** A Prisma generator that still writes the client under src/ — tsc does not copy its .js files to dist/. */
 export const LEGACY_PRISMA_OUTPUT = /generator\s+\w+\s*\{[^}]*output\s*=\s*"\.\.\/src\/[^"]*"/;
@@ -19,6 +19,9 @@ const exists = async (path) => (await readOptional(path)) !== undefined;
 export const MANUAL_START_SNIPPET = `In package.json, run the compiled server in production (build first: \`pnpm build\`):
   "start": "${START_SCRIPT}",
   "start:dev": "${START_DEV_SCRIPT}"`;
+export const MANUAL_NODE_ENV_SNIPPET = `Remove NODE_ENV=development from .env: \`pnpm dev\` and \`pnpm basalt\` already set it, and
+\`pnpm start\` now loads .env — with that line it would boot in development, accepting the dev secret
+defaults instead of requiring the real ones.`;
 export const MANUAL_PRISMA_LAYOUT_SNIPPET = `The Prisma client is generated under src/, where \`tsc\` does not copy its .js files — \`node ${PRODUCTION_ENTRY}\` cannot load it. Move it out of src/:
   prisma/schema.prisma   output = "../generated/prisma"
   package.json           "imports": ${JSON.stringify(PRISMA_IMPORTS)}
@@ -45,12 +48,15 @@ export async function planProductionPath(dir, packageJsonText, pm = 'pnpm') {
     const prismaClient = pkg.dependencies?.['@prisma/client'];
     const merged = mergePackageJson(packageJsonText, {
         scripts: { build: BUILD_SCRIPT },
+        replaceScripts: pkg.scripts?.['start'] === PREVIOUS_START_SCRIPT ? { start: { from: PREVIOUS_START_SCRIPT, to: START_SCRIPT } } : {},
         ...(schema !== undefined && prismaClient !== undefined
             ? { dependencies: { '@prisma/client-runtime-utils': prismaClient } }
             : {}),
     });
     for (const change of merged.changes) {
-        if (change.startsWith('scripts:'))
+        if (change.startsWith('scripts: start:'))
+            notes.push(`package.json: "start" loads .env when it exists (${START_SCRIPT}); needs Node ${ENGINES_NODE}`);
+        else if (change.startsWith('scripts:'))
             notes.push(`package.json: a "build" script (${BUILD_SCRIPT})`);
         else
             notes.push(`package.json: @prisma/client-runtime-utils ${prismaClient} — the generated client requires it by name; plain node cannot reach it as a transitive dependency`);
@@ -58,6 +64,12 @@ export async function planProductionPath(dir, packageJsonText, pm = 'pnpm') {
     const start = pkg.scripts?.['start'];
     if (start !== undefined && RUNS_TSX.test(start))
         manual.push(MANUAL_START_SNIPPET);
+    // `start` now loads .env: a NODE_ENV=development left there (create-basalt ≤ 1.14
+    // wrote one) would boot `pnpm start` in development, with the dev secret defaults.
+    const dotEnv = await readOptional(join(dir, '.env'));
+    if (dotEnv !== undefined && /^\s*NODE_ENV\s*=\s*["']?development["']?\s*$/m.test(dotEnv)) {
+        manual.push(MANUAL_NODE_ENV_SNIPPET);
+    }
     const legacyPrisma = schema !== undefined && LEGACY_PRISMA_OUTPUT.test(schema);
     if (legacyPrisma)
         manual.push(MANUAL_PRISMA_LAYOUT_SNIPPET);

package/dist/project/update.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { binStatus, hasDevPrelude, hasProjectCommands, manualBinSnippet, patchBasaltBin } from '../bin-template.js';
+import { binStatus, hasDevPrelude, hasGeneratorsPrelude, hasProjectCommands, manualBinSnippet, patchBasaltBin } from '../bin-template.js';
 import { devEntryStatus, MANUAL_DEV_SNIPPET, patchDevEntry, patchEnvExample } from '../dev-entry.js';
 import { alwaysLatest, lookupLatestVersions, minimumReleaseAgeMinutes, } from '../latest-versions.js';
 import { BASALT_PROJECT_SCRIPT } from '../templates.js';
@@ -207,7 +207,7 @@ export async function planUpdate(ctx, options = {}) {
             const after = patchBasaltBin(bin);
             files['bin/basalt.ts'] = { before: bin, after };
             patched['bin/basalt.ts'] = after;
-            toolingNotes.push(`bin/basalt.ts: unmodified template from an earlier release — ${hasProjectCommands(bin) ? '' : 'gains update/add/doctor/info; '}${hasDevPrelude(bin) ? '' : 'loads .env for development, runs \`upgrade\` without booting the app, explains env errors; '}runs make:* without booting the app (no database needed to generate code)`);
+            toolingNotes.push(`bin/basalt.ts: unmodified template from an earlier release — ${hasProjectCommands(bin) ? '' : 'gains update/add/doctor/info; '}${hasDevPrelude(bin) ? '' : 'loads .env for development, runs \`upgrade\` without booting the app, explains env errors; '}${hasGeneratorsPrelude(bin) ? '' : 'runs make:* without booting the app (no database needed to generate code); '}starts \`basalt dev\` even while the app cannot boot (the route table when it does)`);
         }
         else if (status === 'modified' && bin !== undefined) {
             manual.push(`bin/basalt.ts was customised, so it was not patched. To bring it up to date:\n${manualBinSnippet(bin)}`);
@@ -228,7 +228,7 @@ export async function planUpdate(ctx, options = {}) {
         if (example !== undefined && exampleAfter !== undefined) {
             files['.env.example'] = { before: example, after: exampleAfter };
             patched['.env.example'] = exampleAfter;
-            toolingNotes.push('.env.example: header now says dev/CLI load .env automatically and `start` does not');
+            toolingNotes.push('.env.example: header now says `dev`, `basalt` and `start` load .env (an exported variable wins)');
         }
         // The production path (BK-026): tsconfig.build.json, a `build` script, the
         // Dockerfile — offered when missing, never overwriting what the app has.

package/dist/templates.d.ts

@@ -41,7 +41,16 @@ export declare const thirdPartyVersionOf: (pkg: string) => string;
 export declare const BUILD_SCRIPT = "tsc -p tsconfig.build.json";
 /** The `db:seed` script of a `--prisma` scaffold with tenancy (prisma.config.ts loads .env, then runs `migrations.seed`). */
 export declare const DB_SEED_SCRIPT = "prisma db seed";
-export declare const START_SCRIPT = "node --enable-source-maps dist/src/server.js";
+/**
+ * `start` loads `.env` when it exists (`--env-file-if-exists`): an exported
+ * variable still wins, and the file sets no NODE_ENV, so an unset NODE_ENV
+ * stays production — secrets required (fail-closed).
+ */
+export declare const START_SCRIPT = "node --env-file-if-exists=.env --enable-source-maps dist/src/server.js";
+/** The `start` create-basalt wrote before it loaded `.env`: `update` replaces it when untouched. */
+export declare const PREVIOUS_START_SCRIPT = "node --enable-source-maps dist/src/server.js";
+/** `--env-file-if-exists` (the `start` script) needs Node 22.9. */
+export declare const ENGINES_NODE = ">=22.9.0";
 export declare const START_DEV_SCRIPT = "tsx src/server.ts";
 /** The `start` script every create-basalt release before the production path wrote. */
 export declare const LEGACY_START_SCRIPT = "tsx src/server.ts";
@@ -80,7 +89,9 @@ export declare function envPrefix(name: string): string;
  * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
  * swaps that for this one in existing apps.
  */
-export declare const ENV_EXAMPLE_LEAD = "# Development: copy this file to .env \u2014 `pnpm dev` and `pnpm basalt` load it\n# automatically (a new app already has one). `pnpm start` (production) does\n# NOT: there the variables come from the environment (or `node --env-file`).";
+export declare const ENV_EXAMPLE_LEAD = "# Copy this file to .env (a new app already has one). `pnpm dev`, `pnpm basalt`\n# and `pnpm start` load it when it exists; a variable exported in your shell\n# (or by the platform: Docker, systemd, the deploy) always wins.";
+/** The lead create-basalt 1.11–1.14 wrote (\`pnpm start\` did not load .env); \`update\` swaps it. */
+export declare const PREVIOUS_ENV_EXAMPLE_LEAD = "# Development: copy this file to .env \u2014 `pnpm dev` and `pnpm basalt` load it\n# automatically (a new app already has one). `pnpm start` (production) does\n# NOT: there the variables come from the environment (or `node --env-file`).";
 export declare const LEGACY_ENV_EXAMPLE_LEAD = "# Nothing loads this file for you: copy it to .env and start with\n# `node --env-file=.env` / `tsx --env-file=.env`, or export the variables.";
 export declare function envExample(options: ProjectOptions): string;
 /**
@@ -99,9 +110,9 @@ export declare function serverTs(): string;
  * semantics — an exported variable wins, the file only fills in what is
  * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
  * logs) unless NODE_ENV is already set, then starts the server. Kept out of
- * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
- * loads `.env` (production configuration comes from the real environment) and
- * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
+ * server.ts on purpose: `pnpm start` runs the compiled server, which loads
+ * `.env` through `--env-file-if-exists` but never opts into development — an
+ * unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export declare function devTs(): string;
 /**

package/dist/templates.js

@@ -38,7 +38,16 @@ export const thirdPartyVersionOf = (pkg) => {
 export const BUILD_SCRIPT = 'tsc -p tsconfig.build.json';
 /** The `db:seed` script of a `--prisma` scaffold with tenancy (prisma.config.ts loads .env, then runs `migrations.seed`). */
 export const DB_SEED_SCRIPT = 'prisma db seed';
-export const START_SCRIPT = `node --enable-source-maps ${PRODUCTION_ENTRY}`;
+/**
+ * `start` loads `.env` when it exists (`--env-file-if-exists`): an exported
+ * variable still wins, and the file sets no NODE_ENV, so an unset NODE_ENV
+ * stays production — secrets required (fail-closed).
+ */
+export const START_SCRIPT = `node --env-file-if-exists=.env --enable-source-maps ${PRODUCTION_ENTRY}`;
+/** The `start` create-basalt wrote before it loaded `.env`: `update` replaces it when untouched. */
+export const PREVIOUS_START_SCRIPT = `node --enable-source-maps ${PRODUCTION_ENTRY}`;
+/** `--env-file-if-exists` (the `start` script) needs Node 22.9. */
+export const ENGINES_NODE = '>=22.9.0';
 export const START_DEV_SCRIPT = 'tsx src/server.ts';
 /** The `start` script every create-basalt release before the production path wrote. */
 export const LEGACY_START_SCRIPT = 'tsx src/server.ts';
@@ -138,10 +147,12 @@ export function packageJson(options) {
         version: '0.1.0',
         private: true,
         type: 'module',
+        engines: { node: ENGINES_NODE },
         ...(options.prisma ? { imports: PRISMA_IMPORTS } : {}),
         scripts: {
-            // dev opts into NODE_ENV=development (src/dev.ts); start does not, so an
-            // unset NODE_ENV counts as production and secrets are required.
+            // dev opts into NODE_ENV=development (src/dev.ts); start loads .env but
+            // never opts in, so an unset NODE_ENV counts as production and secrets
+            // are required.
             dev: 'tsx watch src/dev.ts',
             // Production: compile once, run on plain node (no tsx at runtime).
             build: BUILD_SCRIPT,
@@ -287,7 +298,11 @@ export function envPrefix(name) {
  * {@link LEGACY_ENV_EXAMPLE_LEAD} ("nothing loads this file"); `update`
  * swaps that for this one in existing apps.
  */
-export const ENV_EXAMPLE_LEAD = `# Development: copy this file to .env — \`pnpm dev\` and \`pnpm basalt\` load it
+export const ENV_EXAMPLE_LEAD = `# Copy this file to .env (a new app already has one). \`pnpm dev\`, \`pnpm basalt\`
+# and \`pnpm start\` load it when it exists; a variable exported in your shell
+# (or by the platform: Docker, systemd, the deploy) always wins.`;
+/** The lead create-basalt 1.11–1.14 wrote (\`pnpm start\` did not load .env); \`update\` swaps it. */
+export const PREVIOUS_ENV_EXAMPLE_LEAD = `# Development: copy this file to .env — \`pnpm dev\` and \`pnpm basalt\` load it
 # automatically (a new app already has one). \`pnpm start\` (production) does
 # NOT: there the variables come from the environment (or \`node --env-file\`).`;
 export const LEGACY_ENV_EXAMPLE_LEAD = `# Nothing loads this file for you: copy it to .env and start with
@@ -303,8 +318,9 @@ export function envExample(options) {
 ${prefix}_PORT=3000
 ${prefix}_HOST=0.0.0.0
 ${prefix}_LOG_LEVEL=info
-# NODE_ENV is a Node-wide convention and is never prefixed.
-NODE_ENV=development
+# NODE_ENV is a Node-wide convention and is never prefixed. Leave it out of this
+# file: \`pnpm dev\` and \`pnpm basalt\` set development, and \`pnpm start\`, with it
+# unset, runs as production — where the secrets below are required.
 ${options.auth
         ? `# Required unless NODE_ENV is development/test — \`pnpm start\` refuses to boot
 # without it. Generate a strong one:  openssl rand -base64 48
@@ -331,8 +347,8 @@ export function devEnvFile(options, appSecret) {
     const example = envExample(options);
     const body = example.slice(example.indexOf(`${prefix}_PORT=`));
     return `# Local development settings, generated by create-basalt from .env.example.
-# Git-ignored: never commit it. \`pnpm dev\` and \`pnpm basalt\` load it (a
-# variable exported in your shell wins); \`pnpm start\` (production) does not.
+# Git-ignored: never commit it. \`pnpm dev\`, \`pnpm basalt\` and \`pnpm start\` load it
+# (a variable exported in your shell wins).
 ${body.replace(`# ${prefix}_APP_SECRET=\n`, `${prefix}_APP_SECRET=${appSecret}\n`)}`;
 }
 /** A PostgreSQL-safe database name derived from the project name. */
@@ -625,20 +641,19 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  * semantics — an exported variable wins, the file only fills in what is
  * missing — and opts into NODE_ENV=development (dev secret defaults, pretty
  * logs) unless NODE_ENV is already set, then starts the server. Kept out of
- * server.ts on purpose: `pnpm start` runs server.ts directly, where nothing
- * loads `.env` (production configuration comes from the real environment) and
- * an unset NODE_ENV counts as production, so secrets are required (fail-closed).
+ * server.ts on purpose: `pnpm start` runs the compiled server, which loads
+ * `.env` through `--env-file-if-exists` but never opts into development — an
+ * unset NODE_ENV counts as production, so secrets are required (fail-closed).
  */
 export function devTs() {
-    return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs server.ts directly,
+    return `// Development entrypoint (\`pnpm dev\`). \`pnpm start\` runs the compiled server,
 // where an unset NODE_ENV counts as production: secrets are then required.
 import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 
 // Development loads .env (when present) like \`node --env-file=.env\`: a variable
 // already exported in your shell still wins, the file only fills in what is
-// missing. \`pnpm start\` (production) never loads it — there the configuration
-// comes from the real environment.
+// missing. Only development opts into NODE_ENV=development, below.
 const envFile = fileURLToPath(new URL('../.env', import.meta.url))
 if (existsSync(envFile)) process.loadEnvFile(envFile)
 
@@ -1140,8 +1155,10 @@ scaffold with \`--cli\` — \`pnpm basalt prisma:sync\` does the merge for you.)
 \`src/env.ts\` validates \`process.env\`. For development, ${options.cli ? '`pnpm dev` and `pnpm basalt` load' : '`pnpm dev` loads'} \`.env\`
 automatically — create-basalt wrote one for you: git-ignored, with local
 values${options.auth ? ' and a generated secret' : ''}. \`.env.example\` is its committed template.
-\`pnpm start\` (production, \`${PRODUCTION_ENTRY}\`) loads **nothing**: there the
-variables come from the real environment (or \`node --env-file=.env\`).
+\`pnpm start\` (production, \`${PRODUCTION_ENTRY}\`) loads \`.env\` too when it exists
+(\`node --env-file-if-exists\`), but the file sets no \`NODE_ENV\`: unset, it counts
+as production, so the secrets are required. Variables the platform exports —
+Docker, systemd, \`@basaltkit/deploy\` — always win over the file.
 
 The variables are **app-prefixed**: \`${envPrefix(options.name)}_PORT\`,
 \`${envPrefix(options.name)}_HOST\`, \`${envPrefix(options.name)}_LOG_LEVEL\`${options.auth ? `, \`${envPrefix(options.name)}_APP_SECRET\`` : ''}${options.prisma ? `, \`${envPrefix(options.name)}_DATABASE_URL\`` : ''}. \`NODE_ENV\` is never prefixed.
@@ -1168,7 +1185,7 @@ your shell exports: \`env | grep DATABASE_URL\`.
 
 \`\`\`bash
 pnpm build          # tsc -p tsconfig.build.json → dist/ (src only)
-pnpm start          # node --enable-source-maps ${PRODUCTION_ENTRY} — no tsx at runtime
+pnpm start          # ${START_SCRIPT} — no tsx at runtime
 pnpm start:dev      # the server from source with tsx, without building
 docker build -t ${options.name} .   # the Dockerfile: build stage + plain-node runtime
 \`\`\`

package/dist/versions.js

@@ -8,10 +8,10 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/ai-mcp': '^0.4.0',
     '@basaltkit/auth': '^5.0.0',
     '@basaltkit/auth-prisma': '^3.0.0',
-    '@basaltkit/cli': '^1.4.2',
+    '@basaltkit/cli': '^1.6.0',
     '@basaltkit/config': '^1.1.2',
     '@basaltkit/core': '^1.6.0',
-    '@basaltkit/deploy': '^0.8.0',
+    '@basaltkit/deploy': '^0.10.1',
     '@basaltkit/env': '^3.1.1',
     '@basaltkit/events': '^1.3.0',
     '@basaltkit/fastify': '^3.0.0',
@@ -19,7 +19,7 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/logger': '^1.3.0',
     '@basaltkit/mailer': '^2.1.0',
     '@basaltkit/mcp': '^6.0.0',
-    '@basaltkit/prisma': '^4.0.0',
+    '@basaltkit/prisma': '^4.1.1',
     '@basaltkit/sdk': '^2.1.0',
     '@basaltkit/subscriptions': '^6.0.0',
     '@basaltkit/subscriptions-prisma': '^4.0.0',
@@ -28,5 +28,5 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/tenancy': '^4.0.0',
     '@basaltkit/tenancy-prisma': '^3.0.0',
     '@basaltkit/testing': '^3.0.0',
-    'create-basalt': '^1.14.2',
+    'create-basalt': '^1.16.0',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.14.2",
+  "version": "1.16.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -21,38 +21,38 @@
     "dist"
   ],
   "devDependencies": {
-    "@prisma/adapter-pg": "^7.10.0",
-    "@prisma/client": "^7.10.0",
-    "@prisma/client-runtime-utils": "^7.10.0",
+    "@prisma/adapter-pg": "^7.10.1",
+    "@prisma/client": "^7.10.1",
+    "@prisma/client-runtime-utils": "^7.10.1",
     "@types/node": "^26.6.5",
     "@types/pg": "^8.23.1",
     "pg": "^8.23.1",
-    "prisma": "^7.10.0",
+    "prisma": "^7.10.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.3",
-    "zod": "^4.6.6",
-    "@basaltkit/cli": "^1.4.2",
+    "vitest": "^5.0.5",
+    "zod": "^4.6.7",
+    "@basaltkit/auth-prisma": "^3.0.0",
     "@basaltkit/config": "^1.1.2",
+    "@basaltkit/auth": "^5.0.0",
     "@basaltkit/core": "^1.6.0",
-    "@basaltkit/auth-prisma": "^3.0.0",
-    "@basaltkit/deploy": "^0.8.0",
+    "@basaltkit/cli": "^1.6.0",
+    "@basaltkit/deploy": "^0.10.1",
     "@basaltkit/env": "^3.1.1",
-    "@basaltkit/events": "^1.3.0",
     "@basaltkit/fastify": "^3.0.0",
-    "@basaltkit/generator": "^1.7.0",
+    "@basaltkit/events": "^1.3.0",
     "@basaltkit/logger": "^1.3.0",
     "@basaltkit/mcp": "^6.0.0",
-    "@basaltkit/prisma": "^4.0.0",
     "@basaltkit/subscriptions": "^6.0.0",
     "@basaltkit/subscriptions-prisma": "^4.0.0",
     "@basaltkit/teams": "^4.1.1",
+    "@basaltkit/prisma": "^4.1.1",
     "@basaltkit/teams-prisma": "^1.1.0",
     "@basaltkit/tenancy": "^4.0.0",
     "@basaltkit/tenancy-prisma": "^3.0.0",
+    "@basaltkit/generator": "^1.7.0",
     "@basaltkit/testing": "^3.0.0",
-    "@basaltkit/tsconfig": "^0.24.0",
-    "@basaltkit/auth": "^5.0.0"
+    "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
     "access": "public"