feat: Consistent handling of environment variables

.changeset/beige-gorillas-tell.md

@@ -0,0 +1,9 @@
+---
+'@sveltejs/adapter-cloudflare': patch
+'@sveltejs/adapter-cloudflare-workers': patch
+'@sveltejs/adapter-netlify': patch
+'@sveltejs/adapter-node': patch
+'@sveltejs/adapter-vercel': patch
+---
+
+Initialise `env`

.changeset/pretty-kings-care.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': patch
+---
+
+Add `$env/static/private`, `$env/static/public`, `$env/dynamic/private` and `$env/dynamic/public` modules

documentation/docs/06-hooks.md

@@ -38,9 +38,6 @@ declare namespace App {
 	interface Locals {
 		user: User;
 	}
-	interface Platform {}
-	interface Session {}
-	interface Stuff {}
 }
 
 const getUserInformation: (cookie: string | null) => Promise<User>;

documentation/docs/15-configuration.md

@@ -29,7 +29,9 @@ const config = {
 				// ...
 			}
 		},
-		moduleExtensions: ['.js', '.ts'],
+		env: {
+			publicPrefix: 'PUBLIC_'
+		},
 		files: {
 			assets: 'static',
 			hooks: 'src/hooks',
@@ -44,6 +46,7 @@ const config = {
 			parameter: '_method',
 			allowed: []
 		},
+		moduleExtensions: ['.js', '.ts'],
 		outDir: '.svelte-kit',
 		package: {
 			dir: 'package',
@@ -157,9 +160,11 @@ When pages are prerendered, the CSP header is added via a `<meta http-equiv>` ta
 
 > Note that most [Svelte transitions](https://svelte.dev/tutorial/transition) work by creating an inline `<style>` element. If you use these in your app, you must either leave the `style-src` directive unspecified or add `unsafe-inline`.
 
-### moduleExtensions
+### env
 
-An array of file extensions that SvelteKit will treat as modules. Files with extensions that match neither `config.extensions` nor `config.kit.moduleExtensions` will be ignored by the router.
+Environment variable configuration:
+
+- `publicPrefix` — a prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](/docs/modules#$env-static-public) and [`$env/dynamic/public`](/docs/modules#$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary.
 
 ### files
 
@@ -186,6 +191,10 @@ See [HTTP Method Overrides](/docs/routing#endpoints-http-method-overrides). An o
 - `parameter` — query parameter name to use for passing the intended method value
 - `allowed` - array of HTTP methods that can be used when overriding the original request method
 
+### moduleExtensions
+
+An array of file extensions that SvelteKit will treat as modules. Files with extensions that match neither `config.extensions` nor `config.kit.moduleExtensions` will be ignored by the router.
+
 ### outDir
 
 The directory that SvelteKit writes files to during `dev` and `build`. You should exclude this directory from version control.

packages/adapter-cloudflare-workers/files/entry.js

@@ -15,6 +15,8 @@ export default {
 	 * @param {any} context
 	 */
 	async fetch(req, env, context) {
+		server.init({ env });
+
 		const url = new URL(req.url);
 
 		// static assets

packages/adapter-cloudflare/src/worker.js

@@ -9,6 +9,7 @@ const prefix = `/${manifest.appDir}/`;
 /** @type {import('worktop/cfw').Module.Worker<{ ASSETS: import('worktop/cfw.durable').Durable.Object }>} */
 const worker = {
 	async fetch(req, env, context) {
+		server.init({ env });
 		// skip cache if "cache-control: no-cache" in request
 		let pragma = req.headers.get('cache-control') || '';
 		let res = !pragma.includes('no-cache') && (await Cache.lookup(req));

packages/adapter-netlify/src/serverless.js

@@ -9,6 +9,10 @@ import { split_headers } from './headers';
 export function init(manifest) {
 	const server = new Server(manifest);
 
+	server.init({
+		env: process.env
+	});
+
 	return async (event, context) => {
 		const response = await server.respond(to_request(event), {
 			platform: { context },

packages/adapter-node/src/handler.js

@@ -11,6 +11,7 @@ import { env } from './env.js';
 /* global ENV_PREFIX */
 
 const server = new Server(manifest);
+server.init({ env: process.env });
 const origin = env('ORIGIN', undefined);
 const xff_depth = parseInt(env('XFF_DEPTH', '1'));
 

packages/adapter-vercel/files/serverless.js

@@ -7,6 +7,10 @@ installPolyfills();
 
 const server = new Server(manifest);
 
+server.init({
+	env: process.env
+});
+
 /**
  * @param {import('http').IncomingMessage} req
  * @param {import('http').ServerResponse} res

packages/create-svelte/templates/default/src/app.d.ts

@@ -10,6 +10,10 @@ declare namespace App {
 
 	// interface Platform {}
 
+	// interface PrivateEnv {}
+
+	// interface PublicEnv {}
+
 	// interface Session {}
 
 	// interface Stuff {}

packages/create-svelte/templates/skeleton/src/app.d.ts

@@ -6,6 +6,8 @@
 declare namespace App {
 	// interface Locals {}
 	// interface Platform {}
+	// interface PrivateEnv {}
+	// interface PublicEnv {}
 	// interface Session {}
 	// interface Stuff {}
 }

packages/kit/rollup.config.js

@@ -23,6 +23,10 @@ export default [
 			'app/stores': 'src/runtime/app/stores.js',
 			'app/paths': 'src/runtime/app/paths.js',
 			'app/env': 'src/runtime/app/env.js',
+			'env/dynamic/private': 'src/runtime/env/dynamic/private.js',
+			'env/dynamic/public': 'src/runtime/env/dynamic/public.js',
+			'env-private': 'src/runtime/env-private.js',
+			'env-public': 'src/runtime/env-public.js',
 			paths: 'src/runtime/paths.js',
 			env: 'src/runtime/env.js'
 		},

packages/kit/scripts/extract-types.js

@@ -2,10 +2,11 @@ import fs from 'fs';
 import ts from 'typescript';
 import prettier from 'prettier';
 import { mkdirp } from '../src/utils/filesystem.js';
+import { fileURLToPath } from 'url';
 
 /** @typedef {{ name: string, comment: string, snippet: string }} Extracted */
 
-/** @type {Array<{ name: string, comment: string, exports: Extracted[], types: Extracted[] }>} */
+/** @type {Array<{ name: string, comment: string, exports: Extracted[], types: Extracted[], exempt?: boolean }>} */
 const modules = [];
 
 /**
@@ -19,59 +20,72 @@ function get_types(code, statements) {
 	/** @type {Extracted[]} */
 	const types = [];
 
-	for (const statement of statements) {
-		if (
-			ts.isClassDeclaration(statement) ||
-			ts.isInterfaceDeclaration(statement) ||
-			ts.isTypeAliasDeclaration(statement) ||
-			ts.isModuleDeclaration(statement) ||
-			ts.isVariableStatement(statement) ||
-			ts.isFunctionDeclaration(statement)
-		) {
-			const name_node = ts.isVariableStatement(statement)
-				? statement.declarationList.declarations[0]
-				: statement;
-
-			// @ts-ignore no idea why it's complaining here
-			const name = name_node.name?.escapedText;
-
-			let start = statement.pos;
-			let comment = '';
-
-			// @ts-ignore i think typescript is bad at typescript
-			if (statement.jsDoc) {
-				// @ts-ignore
-				comment = statement.jsDoc[0].comment;
-				// @ts-ignore
-				start = statement.jsDoc[0].end;
+	if (statements) {
+		for (const statement of statements) {
+			if (
+				ts.isClassDeclaration(statement) ||
+				ts.isInterfaceDeclaration(statement) ||
+				ts.isTypeAliasDeclaration(statement) ||
+				ts.isModuleDeclaration(statement) ||
+				ts.isVariableStatement(statement) ||
+				ts.isFunctionDeclaration(statement)
+			) {
+				const name_node = ts.isVariableStatement(statement)
+					? statement.declarationList.declarations[0]
+					: statement;
+
+				// @ts-ignore no idea why it's complaining here
+				const name = name_node.name?.escapedText;
+
+				let start = statement.pos;
+				let comment = '';
+
+				// @ts-ignore i think typescript is bad at typescript
+				if (statement.jsDoc) {
+					// @ts-ignore
+					comment = statement.jsDoc[0].comment;
+					// @ts-ignore
+					start = statement.jsDoc[0].end;
+				}
+
+				const i = code.indexOf('export', start);
+				start = i + 6;
+
+				const snippet = prettier.format(code.slice(start, statement.end).trim(), {
+					parser: 'typescript',
+					printWidth: 80,
+					useTabs: true,
+					singleQuote: true,
+					trailingComma: 'none'
+				});
+
+				const collection =
+					ts.isVariableStatement(statement) || ts.isFunctionDeclaration(statement)
+						? exports
+						: types;
+
+				collection.push({ name, comment, snippet });
 			}
-
-			const i = code.indexOf('export', start);
-			start = i + 6;
-
-			const snippet = prettier.format(code.slice(start, statement.end).trim(), {
-				parser: 'typescript',
-				printWidth: 80,
-				useTabs: true,
-				singleQuote: true,
-				trailingComma: 'none'
-			});
-
-			const collection =
-				ts.isVariableStatement(statement) || ts.isFunctionDeclaration(statement) ? exports : types;
-
-			collection.push({ name, comment, snippet });
-		} else {
-			// console.log(statement.kind);
 		}
-	}
 
-	types.sort((a, b) => (a.name < b.name ? -1 : 1));
-	exports.sort((a, b) => (a.name < b.name ? -1 : 1));
+		types.sort((a, b) => (a.name < b.name ? -1 : 1));
+		exports.sort((a, b) => (a.name < b.name ? -1 : 1));
+	}
 
 	return { types, exports };
 }
 
+/**
+ * Type declarations include fully qualified URLs so that they become links when
+ * you hover over names in an editor with TypeScript enabled. We need to remove
+ * the origin so that they become root-relative, so that they work in preview
+ * deployments and when developing locally
+ * @param {string} str
+ */
+function strip_origin(str) {
+	return str.replace(/https:\/\/kit\.svelte\.dev/g, '');
+}
+
 {
 	const code = fs.readFileSync('types/index.d.ts', 'utf-8');
 	const node = ts.createSourceFile('index.d.ts', code, ts.ScriptTarget.Latest);
@@ -95,13 +109,20 @@ function get_types(code, statements) {
 	});
 }
 
-modules.push({
-	name: '$lib',
-	comment:
-		'This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](/docs/configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense.',
-	exports: [],
-	types: []
-});
+const dir = fileURLToPath(new URL('./special-types', import.meta.url).href);
+for (const file of fs.readdirSync(dir)) {
+	if (!file.endsWith('.md')) continue;
+
+	const comment = strip_origin(fs.readFileSync(`${dir}/${file}`, 'utf-8'));
+
+	modules.push({
+		name: file.replace(/\+/g, '/').slice(0, -3),
+		comment,
+		exports: [],
+		types: [],
+		exempt: true
+	});
+}
 
 {
 	const code = fs.readFileSync('types/ambient.d.ts', 'utf-8');
@@ -113,13 +134,13 @@ modules.push({
 			const name = statement.name.text || statement.name.escapedText;
 
 			// @ts-ignore
-			const comment = statement.jsDoc?.[0].comment ?? '';
+			const comment = strip_origin(statement.jsDoc?.[0].comment ?? '');
 
 			modules.push({
 				name,
 				comment,
 				// @ts-ignore
-				...get_types(code, statement.body.statements)
+				...get_types(code, statement.body?.statements)
 			});
 		}
 	}

packages/kit/scripts/special-types/$env+static+private.md

@@ -0,0 +1,7 @@
+Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-platform), this module cannot be imported into client-side code.
+
+_Unlike_ [`$env/dynamic/private`](https://kit.svelte.dev/docs/modules#$env-dynamic-platform), the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination.
+
+```ts
+import { API_KEY } from '$env/static/private';
+```

packages/kit/scripts/special-types/$env+static+public.md

@@ -0,0 +1,7 @@
+Similar to [`$env/static/private`](https://kit.svelte.dev/docs/modules#$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](https://kit.svelte.dev/docs/configuration#kit-env-publicprefix) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code.
+
+Values are replaced statically at build time.
+
+```ts
+import { PUBLIC_BASE_URL } from '$env/static/public';
+```

packages/kit/scripts/special-types/$lib.md

@@ -0,0 +1 @@
+This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](https://kit.svelte.dev/docs/configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense.

packages/kit/src/cli.js

@@ -38,7 +38,8 @@ prog
 prog
 	.command('sync')
 	.describe('Synchronise generated files')
-	.action(async () => {
+	.option('--mode', 'Specify a mode for loading environment variables', 'development')
+	.action(async ({ mode }) => {
 		if (!fs.existsSync('svelte.config.js')) {
 			console.warn('Missing svelte.config.js — skipping');
 			return;
@@ -47,7 +48,7 @@ prog
 		try {
 			const config = await load_config();
 			const sync = await import('./core/sync/sync.js');
-			sync.all(config);
+			sync.all(config, mode);
 		} catch (error) {
 			handle_error(error);
 		}

packages/kit/src/core/config/index.spec.js

@@ -73,6 +73,9 @@ const get_defaults = (prefix = '') => ({
 			reportOnly: directive_defaults
 		},
 		endpointExtensions: undefined,
+		env: {
+			publicPrefix: 'PUBLIC_'
+		},
 		files: {
 			assets: join(prefix, 'static'),
 			hooks: join(prefix, 'src/hooks'),

packages/kit/src/core/config/options.js

@@ -123,6 +123,10 @@ const options = object(
 				(keypath) => `${keypath} has been renamed to config.kit.moduleExtensions`
 			),
 
+			env: object({
+				publicPrefix: string('PUBLIC_')
+			}),
+
 			files: object({
 				assets: string('static'),
 				hooks: string(join('src', 'hooks')),