Skip to content

Commit 655a0d9

Browse files
fix(init): stop un-ignoring .env.example in scaffolded projects (#759)
Closes #757 ## Problem `void init` writes `!.env.example` to `.gitignore`, but since #311 Void refuses to start when that file exists. New projects were being told to commit a file that stops dev and build. ## Changes - Remove `!.env.example` from `SCAFFOLD_GITIGNORE_LINES`, so `.env.*` now ignores it. - When `.env.example` is one of the reported files, the dev/build error and `void env check` now add: "env.ts lists the keys this app expects, so .env.example is not needed." Other legacy files such as `.env.local` get the same message as before. - Update the `init` unit test and the `packed-consumer` assertion that expected the file to stay un-ignored, and add coverage for the new message on both paths. Existing projects are unaffected: `void init` only appends missing `.gitignore` lines, so a line already there stays. ## Verification - `vp run check`, format and lint pass. - `vp test run`: passes. The first run had failures from a missing Playwright browser and stale playground builds, plus one port conflict; after installing Chromium and running `vp run build:all`, all 33 of those files passed when rerun. - `.github/scripts/packed-consumer.mjs` was not run locally, so CI will be the first run of that assertion. ## Note Both errors tell users to "follow the env migration guide", but no guide with that name exists in `docs/`. That wording predates this PR and is left unchanged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 7dd56a7 commit 655a0d9

8 files changed

Lines changed: 37 additions & 6 deletions

File tree

‎.github/scripts/packed-consumer.mjs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -239,8 +239,8 @@ try {
239239
)
240240
.trim()
241241
.split('\n'),
242-
['node_modules/dependency', '.env', '.env.local', '.env.production'],
243-
'Init must ignore local environment files while allowing the example',
242+
['node_modules/dependency', '.env', '.env.local', '.env.production', '.env.example'],
243+
'Init must ignore local environment files',
244244
);
245245
writeFileSync(
246246
join(fixture, '.npmrc'),

‎packages/void/src/cli/env-validation.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {
1616
findLegacyEnvFiles,
1717
findReservedEnvKeys,
1818
isClientEnvKey,
19+
legacyEnvExampleHint,
1920
loadLocalEnv,
2021
LOCAL_ENV_FILE,
2122
reservedEnvKeysMessage,
@@ -110,7 +111,7 @@ export async function validateProdEnv(
110111
const legacyFiles = findLegacyEnvFiles(root);
111112
if (legacyFiles.length > 0) {
112113
throw new Error(
113-
`env: only .env is supported for local development. Remove ${legacyFiles.join(', ')} and follow the env migration guide.`,
114+
`env: only .env is supported for local development. Remove ${legacyFiles.join(', ')} and follow the env migration guide.${legacyEnvExampleHint(legacyFiles)}`,
114115
);
115116
}
116117
// Same rule as the Vite plugin, which stops dev and build on these names.

‎packages/void/src/cli/template.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ export const SCAFFOLD_GITIGNORE_LINES = [
1313
'.void-wrangler.jsonc',
1414
'.env',
1515
'.env.*',
16-
'!.env.example',
1716
'*.tsbuildinfo',
1817
'.DS_Store',
1918
] as const;

‎packages/void/src/plugin-env-schema.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
findLegacyEnvFiles,
1414
findReservedEnvKeys,
1515
isClientEnvKey,
16+
legacyEnvExampleHint,
1617
loadLocalEnv,
1718
LOCAL_ENV_FILE,
1819
reservedEnvKeysMessage,
@@ -328,7 +329,7 @@ export function envSchemaPlugin(root: string, options: EnvSchemaPluginOptions =
328329
const legacyFiles = findLegacyEnvFiles(root);
329330
if (legacyFiles.length > 0) {
330331
throw new Error(
331-
`void/env supports one local file: .env. Remove ${legacyFiles.join(', ')} and follow the env migration guide.`,
332+
`void/env supports one local file: .env. Remove ${legacyFiles.join(', ')} and follow the env migration guide.${legacyEnvExampleHint(legacyFiles)}`,
332333
);
333334
}
334335
// Every mode (serve, build, preview), with or without env.ts. Only the

‎packages/void/src/shared/env.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,16 @@ export function findLegacyEnvFiles(root: string): Array<string> {
6161
}
6262
}
6363

64+
/**
65+
* Sentence to append to a legacy-file error when `.env.example` is among the
66+
* files, since it is usually added out of habit to document expected keys.
67+
*/
68+
export function legacyEnvExampleHint(legacyFiles: ReadonlyArray<string>): string {
69+
return legacyFiles.includes('.env.example')
70+
? ' env.ts lists the keys this app expects, so .env.example is not needed.'
71+
: '';
72+
}
73+
6474
/**
6575
* Resolve whether the plugin should run in "remote" mode (proxy real
6676
* D1/KV/R2 via the platform) based on the project config plus an optional

‎packages/void/test/integration/env-cli.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,16 @@ describe('void env check (subprocess)', () => {
9898
expect(status).toBe(1);
9999
expect(stdout).toContain('only .env is supported');
100100
expect(stdout).toContain('.env.local');
101+
expect(stdout).not.toContain('env.ts lists the keys');
102+
});
103+
104+
it('points .env.example users at env.ts', () => {
105+
const root = createProject('{ STRIPE_KEY: string() }');
106+
writeFileSync(join(root, '.env.example'), 'STRIPE_KEY=\n');
107+
const { stdout, status } = runVoid(root, ['env', 'check']);
108+
expect(status).toBe(1);
109+
expect(stdout).toContain('Remove .env.example');
110+
expect(stdout).toContain('env.ts lists the keys');
101111
});
102112
});
103113

‎packages/void/test/integration/plugin-env-schema.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,16 @@ describe('envSchemaPlugin auto-discovery', () => {
180180
writeFileSync(join(root, '.env.production'), 'API_URL=https://example.com\n');
181181

182182
await expect(runConfig(envSchemaPlugin(root))).rejects.toThrow('supports one local file: .env');
183+
await expect(runConfig(envSchemaPlugin(root))).rejects.not.toThrow('env.ts lists the keys');
184+
});
185+
186+
it('points .env.example users at env.ts', async () => {
187+
const root = createTempRoot();
188+
writeFileSync(join(root, '.env.example'), 'API_URL=\n');
189+
190+
await expect(runConfig(envSchemaPlugin(root))).rejects.toThrow(
191+
'Remove .env.example and follow the env migration guide. env.ts lists the keys',
192+
);
183193
});
184194

185195
it('removes local .env client values from production builds', async () => {

‎packages/void/test/unit/init.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2620,7 +2620,7 @@ export default config;
26202620
expect(gitignore).toContain('.wrangler');
26212621
expect(gitignore).toContain('.env');
26222622
expect(gitignore.split('\n')).toContain('.env.*');
2623-
expect(gitignore.split('\n')).toContain('!.env.example');
2623+
expect(gitignore.split('\n')).not.toContain('!.env.example');
26242624
} finally {
26252625
rmSync(root, { recursive: true, force: true });
26262626
}

0 commit comments

Comments
 (0)