create-basalt 1.6.0 → 1.7.0

package/README.md

@@ -135,12 +135,12 @@ Always:
 my-app/
 ├── package.json          # scripts: dev, start, test, typecheck (+ basalt with --cli)
 ├── tsconfig.json         # strict TypeScript, ESM
-├── .env.example          # PORT, HOST, LOG_LEVEL, NODE_ENV (+ APP_SECRET with auth) + the --env-file precedence warning
+├── .env.example          # MY_APP_PORT, MY_APP_HOST, MY_APP_LOG_LEVEL, NODE_ENV (+ MY_APP_APP_SECRET with auth) + the --env-file precedence warning
 ├── .gitignore
 ├── README.md             # instructions adapted to the chosen options
 ├── pnpm-workspace.yaml   # esbuild allowBuilds, @basaltkit/* release-age exclusion (+ "web" member with --ui) + pnpm 11 notes
 ├── src/
-│   ├── env.ts            # environment variables validated with Zod (@basaltkit/env)
+│   ├── env.ts            # environment variables validated with Zod (@basaltkit/env), app-prefixed
 │   ├── app.ts            # buildApp() with the chosen plugins
 │   ├── routes.ts         # GET / (friendly index) and GET /health
 │   └── server.ts         # startup + clean shutdown on SIGINT/SIGTERM
@@ -176,7 +176,28 @@ With pnpm 11, every `pnpm <script>` and `pnpm exec` first verifies dependencies
 
 ### Environment variables and `--env-file`
 
-Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, the app boots against that value and only fails on the first request that touches it. The generated `.env.example` and README say so and suggest an app-specific prefix derived from the project name (`my-saas` → `MY_SAAS_DATABASE_URL`).
+Nothing loads `.env` for you. `node --env-file=.env` / `tsx --env-file=.env` **never override a variable already exported in the shell** — in a terminal where another project exported `DATABASE_URL` or `PORT`, an app reading the generic name boots against that value and only fails on the first request that touches it.
+
+The scaffold closes that trap instead of only warning about it: `src/env.ts` passes an **app-specific prefix** derived from the project name (`my-saas` → `MY_SAAS`) to `defineEnv`, and `.env.example` uses the prefixed names.
+
+```ts
+// src/env.ts (generated)
+export const env = defineEnv(
+  { PORT: z.coerce.number().default(3000), /* … */ },
+  { prefix: 'MY_SAAS' },
+)
+```
+
+```bash
+# .env.example (generated)
+MY_SAAS_PORT=3000
+MY_SAAS_HOST=0.0.0.0
+MY_SAAS_LOG_LEVEL=info
+NODE_ENV=development          # never prefixed — a Node-wide convention
+# MY_SAAS_APP_SECRET=         # with auth
+```
+
+Each variable is read as `MY_SAAS_<NAME>` first and **falls back** to the bare `<NAME>`, so a deployment that already exports the generic names keeps booting — while a stray `PORT` in your shell no longer wins. The rest of the app is unchanged: the keys stay bare (`env.PORT`). To require the prefixed names only, edit the generated file to `prefix: { value: 'MY_SAAS', fallback: false }`. Full rules: [`@basaltkit/env`](https://github.com/basaltkit/basalt/tree/main/packages/env#app-specific-prefix-prefix).
 
 ### Programmatic usage (Advanced)
 
@@ -267,10 +288,10 @@ 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` with at least 16 characters (there's a development default `change-me-in-production--`). Copy `.env.example` to `.env` and set your own secret before going to production.
+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`). Copy `.env.example` to `.env` and set your own secret before going to production.
 
 **My app connects to the wrong database / port.**
-A variable exported in your shell beats `--env-file`. Check `env | grep DATABASE_URL`, start with `env -u DATABASE_URL pnpm dev`, and prefer app-prefixed names (see *Environment variables and `--env-file`*).
+A variable exported in your shell beats `--env-file`. The generated `src/env.ts` already reads app-prefixed names (`MY_SAAS_PORT`), so set those rather than the generic ones — the bare names are only a fallback. Check `env | grep DATABASE_URL`, and see *Environment variables and `--env-file`*.
 
 **`pnpm basalt …` starts by running `pnpm install` (or fails offline).**
 pnpm 11's `verifyDepsBeforeRun` (default `install`). Run `node_modules/.bin/tsx bin/basalt.ts …` instead, or set `verifyDepsBeforeRun: warn` in `pnpm-workspace.yaml`.

package/dist/templates.js

@@ -105,25 +105,39 @@ export function tsconfigJson() {
     }, null, 2)}\n`;
 }
 export function envTs(options) {
+    const prefix = envPrefix(options.name);
     return `import { defineEnv${options.auth ? ', secret' : ''} } from '@basaltkit/env'
 import { LOG_LEVELS } from '@basaltkit/logger'
 import { z } from 'zod'
 
-export const env = defineEnv({
-  PORT: z.coerce.number().default(3000),
-  HOST: z.string().default('0.0.0.0'),
-  // Typed against the logger's LogLevel union — a free-form string here fails
-  // \`pnpm typecheck\` where loggerPlugin({ level }) consumes it.
-  LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
-  // Unset counts as production (fail-closed); \`pnpm dev\` sets development.
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.auth
+export const env = defineEnv(
+  {
+    PORT: z.coerce.number().default(3000),
+    HOST: z.string().default('0.0.0.0'),
+    // Typed against the logger's LogLevel union — a free-form string here fails
+    // \`pnpm typecheck\` where loggerPlugin({ level }) consumes it.
+    LOG_LEVEL: z.enum(LOG_LEVELS).default('info'),
+    // Unset counts as production (fail-closed); \`pnpm dev\` sets development.
+    // NODE_ENV is a Node-wide convention and is never prefixed.
+    NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),${options.auth
         ? `
-  // Signs JWTs and sessions. secret() is fail-closed: required unless NODE_ENV
-  // is explicitly development/test (no fallback when NODE_ENV is unset),
-  // rejected if it looks like a placeholder. \`pnpm dev\` uses devDefault.
-  APP_SECRET: secret({ minLength: 32, devDefault: 'dev-only-insecure-secret-please-change-me' }),`
+    // Signs JWTs and sessions. secret() is fail-closed: required unless NODE_ENV
+    // is explicitly development/test (no fallback when NODE_ENV is unset),
+    // rejected if it looks like a placeholder. \`pnpm dev\` uses devDefault.
+    APP_SECRET: secret({ minLength: 32, devDefault: 'dev-only-insecure-secret-please-change-me' }),`
         : ''}
-})
+  },
+  {
+    // Every variable is read as ${prefix}_<NAME> first (${prefix}_PORT before PORT),
+    // falling back to the bare name. \`--env-file\` never overrides a variable
+    // already exported in your shell, so without the prefix another project's
+    // exported PORT / DATABASE_URL would silently win. The keys above stay bare:
+    // the rest of the app still reads env.PORT.
+    // To require the prefixed names (no bare fallback at all), write:
+    //   prefix: { value: '${prefix}', fallback: false }
+    prefix: '${prefix}',
+  },
+)
 `;
 }
 /**
@@ -151,13 +165,24 @@ export function envExample(options) {
     return `# Nothing loads this file for you: copy it to .env and start with
 # \`node --env-file=.env\` / \`tsx --env-file=.env\`, or export the variables.
 # --env-file NEVER overrides a variable already exported in your shell: if
-# another project exported DATABASE_URL, the app silently uses THAT one. Give
-# generic names an app-specific prefix, e.g. ${prefix}_DATABASE_URL.
-PORT=3000
-HOST=0.0.0.0
-LOG_LEVEL=info
+# another project exported PORT or DATABASE_URL, an app reading the generic
+# name would silently use THAT one. That is why src/env.ts reads app-prefixed
+# names — ${prefix}_PORT wins over a stray PORT. The bare names still work as a
+# fallback, so an existing deployment exporting them keeps booting.
+${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
-${options.auth ? '# Required unless NODE_ENV is development/test — `pnpm start` refuses to boot\n# without it. Generate a strong one:  openssl rand -base64 48\n# APP_SECRET=\n' : ''}`;
+${options.auth
+        ? `# Required unless NODE_ENV is development/test — \`pnpm start\` refuses to boot
+# without it. Generate a strong one:  openssl rand -base64 48
+# ${prefix}_APP_SECRET=
+`
+        : ''}# When you add a database, declare DATABASE_URL in src/env.ts and set it here
+# under the prefixed name:
+# ${prefix}_DATABASE_URL=postgres://user:pass@localhost:5432/${options.name.replace(/^@[^/]+\//, '')}
+`;
 }
 export function appTs(options) {
     const imports = [
@@ -461,11 +486,21 @@ pnpm test
 \`.env.example\` to \`.env\` and launch with \`--env-file=.env\` (Node/tsx), or
 export the variables.
 
-**\`--env-file\` never overrides a variable that is already exported.** In a shell
-where another project exported \`DATABASE_URL\` (or \`PORT\`), this app boots
-against THAT value and only fails on the first request that touches it. Give
-generic names an app-specific prefix — \`${envPrefix(options.name)}_DATABASE_URL\` rather than
-\`DATABASE_URL\` — and check \`env | grep DATABASE_URL\` when in doubt.
+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\`` : ''}. \`NODE_ENV\` is never prefixed.
+
+Why: **\`--env-file\` never overrides a variable that is already exported.** In a
+shell where another project exported \`DATABASE_URL\` (or \`PORT\`), an app reading
+the generic name boots against THAT value and only fails on the first request
+that touches it. \`src/env.ts\` therefore passes \`prefix: '${envPrefix(options.name)}'\` to
+\`defineEnv\`: each variable is read as \`${envPrefix(options.name)}_<NAME>\` first and
+**falls back** to the bare \`<NAME>\`, so a deployment that already exports the
+generic names keeps booting while a stray one in your shell loses. Add a
+database and \`DATABASE_URL\` is read as \`${envPrefix(options.name)}_DATABASE_URL\`.
+
+To drop the fallback entirely (prefixed names only), write
+\`prefix: { value: '${envPrefix(options.name)}', fallback: false }\`. When in doubt about what
+your shell exports: \`env | grep DATABASE_URL\`.
 ${options.cli
         ? `
 ## The \`basalt\` CLI

package/dist/versions.js

@@ -8,15 +8,15 @@ export const SCAFFOLD_VERSIONS = {
     '@basaltkit/auth': '^3.1.0',
     '@basaltkit/cli': '^1.2.0',
     '@basaltkit/config': '^1.1.0',
-    '@basaltkit/core': '^1.3.0',
-    '@basaltkit/env': '^3.0.0',
+    '@basaltkit/core': '^1.4.0',
+    '@basaltkit/env': '^3.1.0',
     '@basaltkit/events': '^1.3.0',
     '@basaltkit/fastify': '^2.2.0',
-    '@basaltkit/generator': '^1.4.0',
+    '@basaltkit/generator': '^1.5.0',
     '@basaltkit/logger': '^1.3.0',
     '@basaltkit/mcp': '^3.0.0',
     '@basaltkit/prisma': '^2.1.0',
-    '@basaltkit/sdk': '^2.0.0',
+    '@basaltkit/sdk': '^2.1.0',
     '@basaltkit/subscriptions': '^4.0.0',
     '@basaltkit/teams': '^3.0.0',
     '@basaltkit/tenancy': '^2.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-basalt",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -25,22 +25,22 @@
     "typescript": "^7.0.2",
     "vitest": "^5.0.1",
     "zod": "^4.6.5",
-    "@basaltkit/auth": "^3.1.0",
     "@basaltkit/config": "^1.1.2",
-    "@basaltkit/core": "^1.3.2",
-    "@basaltkit/env": "^3.0.0",
+    "@basaltkit/auth": "^3.1.0",
     "@basaltkit/cli": "^1.2.5",
+    "@basaltkit/env": "^3.1.0",
+    "@basaltkit/core": "^1.4.0",
     "@basaltkit/events": "^1.3.0",
-    "@basaltkit/generator": "^1.4.0",
+    "@basaltkit/fastify": "^2.2.0",
+    "@basaltkit/generator": "^1.5.0",
     "@basaltkit/logger": "^1.3.0",
     "@basaltkit/mcp": "^3.0.0",
-    "@basaltkit/prisma": "^2.1.0",
+    "@basaltkit/subscriptions": "^4.0.0",
     "@basaltkit/teams": "^3.0.1",
-    "@basaltkit/fastify": "^2.2.0",
     "@basaltkit/tenancy": "^2.0.0",
+    "@basaltkit/tsconfig": "^0.24.0",
     "@basaltkit/testing": "^2.0.2",
-    "@basaltkit/subscriptions": "^4.0.0",
-    "@basaltkit/tsconfig": "^0.24.0"
+    "@basaltkit/prisma": "^2.1.0"
   },
   "publishConfig": {
     "access": "public"