Skip to content

Commit 978eddf

Browse files
fix(init): stop un-ignoring .env.example in scaffolded projects
Void refuses to start when .env.example exists, so the scaffolded .gitignore should not allow committing it. Mention env.ts in the error for anyone adding the file out of habit. Closes #757 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 7dd56a7 commit 978eddf

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)