@sveltejs/kit 2.61.1 → 2.63.0

package/src/core/env.js

@@ -1,19 +1,126 @@
+/** @import { StandardSchemaV1 } from '@standard-schema/spec' */
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
+/** @import { ValidatedKitConfig } from 'types' */
+import path from 'node:path';
+import process from 'node:process';
+import * as vite from 'vite';
+import * as devalue from 'devalue';
 import { GENERATED_COMMENT } from '../constants.js';
 import { dedent } from './sync/utils.js';
-import { runtime_base } from './utils.js';
+import { runtime_base, runtime_directory } from './utils.js';
+import { resolve_entry } from '../utils/filesystem.js';
+import { handle_issues, validate } from '../exports/internal/env.js';
+import { get_config_aliases } from '../exports/vite/utils.js';
 
 /**
  * @typedef {'public' | 'private'} EnvType
  */
 
+let warned = false;
+
+/**
+ * @param {import('types').ValidatedKitConfig} config
+ * @returns {string | null}
+ */
+export function resolve_explicit_env_entry(config) {
+	const resolved = resolve_entry(path.join(config.files.src, 'env'));
+
+	if (resolved) {
+		if (config.experimental.explicitEnvironmentVariables) {
+			return resolved;
+		}
+
+		if (!warned) {
+			console.warn(
+				`${path.relative(process.cwd(), resolved)} requires the \`experimental.explicitEnvironmentVariables\` flag to be set`
+			);
+			warned = true;
+		}
+	} else if (config.experimental.explicitEnvironmentVariables) {
+		console.warn(
+			'experimental.explicitEnvironmentVariables was set, but no src/env.ts or src/env.js file could be found'
+		);
+	}
+
+	return null;
+}
+
+/**
+ * @param {ValidatedKitConfig} kit
+ * @param {string | null} file
+ * @param {string} mode
+ * @returns {Promise<Record<string, EnvVarConfig<any>> | null>}
+ */
+export async function load_explicit_env(kit, file, mode) {
+	if (!file) return null;
+
+	const server = await vite.createServer({
+		configFile: false,
+		logLevel: 'silent',
+		mode,
+		define: {
+			__SVELTEKIT_APP_VERSION__: JSON.stringify(kit.version.name) // needed by $app/env
+		},
+		resolve: {
+			alias: [
+				{ find: '$app/env', replacement: `${runtime_directory}/app/env` },
+				...get_config_aliases(kit)
+			]
+		}
+	});
+
+	/** @type {Record<string, EnvVarConfig<any>>} */
+	let variables;
+
+	try {
+		({ variables } = await server.ssrLoadModule(file));
+
+		if (!variables || typeof variables !== 'object') {
+			throw new Error(`${file} must export a variables object`);
+		}
+
+		// validate
+		for (const name of Object.keys(variables)) {
+			if (!valid_identifier.test(name) || reserved.has(name)) {
+				throw new Error(`Invalid environment variable name ${JSON.stringify(name)}`);
+			}
+		}
+	} catch (e) {
+		const error = /** @type {any} */ (e || {});
+
+		if (
+			error.code === 'ERR_MODULE_NOT_FOUND' &&
+			error.message?.includes(`Cannot find module '$app`)
+		) {
+			throw new Error(
+				`Cannot import \`$app/*\` modules other than \`$app/env\` inside \`src/env\``,
+				{ cause: e }
+			);
+		}
+
+		throw error;
+	} finally {
+		await server.close();
+	}
+
+	return variables;
+}
+
 /**
  * @param {string} id
  * @param {Record<string, string>} env
+ * @param {boolean} disabled
  * @returns {string}
  */
-export function create_static_module(id, env) {
+export function create_static_module(id, env, disabled) {
 	/** @type {string[]} */
-	const declarations = [];
+	const statements = [];
+
+	if (disabled) {
+		statements.push(
+			`throw new Error('Cannot import \`${id}\` when \`experimental.explicitEnvironmentVariables\` is enabled. Use \`${id.replace('$env/static', '$app/env')}\` instead.');`
+		);
+	}
 
 	for (const key in env) {
 		if (!valid_identifier.test(key) || reserved.has(key)) {
@@ -23,24 +130,199 @@ export function create_static_module(id, env) {
 		const comment = `/** @type {import('${id}').${key}} */`;
 		const declaration = `export const ${key} = ${JSON.stringify(env[key])};`;
 
-		declarations.push(`${comment}\n${declaration}`);
+		statements.push(`${comment}\n${declaration}`);
 	}
 
-	return GENERATED_COMMENT + declarations.join('\n\n');
+	return GENERATED_COMMENT + statements.join('\n\n');
 }
 
 /**
  * @param {EnvType} type
  * @param {Record<string, string> | undefined} dev_values If in a development mode, values to pre-populate the module with.
+ * @param {boolean} disabled
  */
-export function create_dynamic_module(type, dev_values) {
+export function create_dynamic_module(type, dev_values, disabled) {
+	const prelude = disabled
+		? `throw new Error('Cannot import \`$env/dynamic/${type}\` when \`experimental.explicitEnvironmentVariables\` is enabled. Use \`$app/env/${type}\` instead.');\n\n`
+		: '';
+
 	if (dev_values) {
 		const keys = Object.entries(dev_values).map(
 			([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
 		);
-		return `export const env = {\n${keys.join(',\n')}\n}`;
+		return `${prelude}export const env = {\n${keys.join(',\n')}\n}`;
+	}
+	return `${prelude}export { ${type}_env as env } from '${runtime_base}/shared-server.js';`;
+}
+
+/**
+ * Creates the `__sveltekit/env` module
+ * @param {Record<string, EnvVarConfig<any>> | null} variables
+ * @param {Record<string, string>} env
+ * @param {string | null} entry
+ */
+export function create_sveltekit_env(variables, env, entry) {
+	const imports = entry
+		? [
+				`import { variables } from ${JSON.stringify(entry)};`,
+				`import { validate, handle_issues } from '@sveltejs/kit/internal/env';`
+			]
+		: [`const variables = {};`, `const handle_issues = () => {};`];
+
+	const declarations = [];
+	const setters = [];
+
+	/** @type {Record<string, StandardSchemaV1.Issue[]>} */
+	const issues = {};
+
+	for (const [name, config] of Object.entries(variables ?? {})) {
+		if (config.static) {
+			if (config.public) {
+				const value = validate(variables ?? {}, env[name], name, issues);
+				declarations.push(`explicit_public_env.${name} = ${devalue.uneval(value)};`);
+			}
+		} else {
+			setters.push(
+				`const ${name} = validate(variables, env.${name}, ${JSON.stringify(name)}, issues);`
+			);
+
+			if (config.public) {
+				setters.push(`explicit_public_env.${name} = ${name};`);
+				setters.push(`rendered_env.${name} = ${name};`);
+			} else {
+				setters.push(`dynamic_private_env.${name} = ${name};`);
+			}
+		}
+	}
+
+	handle_issues(issues);
+
+	const blocks = [
+		GENERATED_COMMENT,
+		imports.join('\n'),
+		`const issues = {};`,
+		'export { variables }',
+		'export const dynamic_private_env = {};',
+		'export const explicit_public_env = {};',
+		'export const rendered_env = {};',
+		...declarations,
+		`handle_issues(issues);`,
+		dedent`
+			export function set_env(env) {
+				const issues = {};
+				${setters.join('\n')}
+				handle_issues(issues);
+			}`
+	];
+
+	const module = blocks.join('\n\n');
+
+	return module;
+}
+
+/**
+ * Creates the `__sveltekit/env/private` module
+ * @param {Record<string, EnvVarConfig<any>> | null} variables
+ * @param {Record<string, string>} env
+ */
+export function create_sveltekit_env_private(variables, env) {
+	if (!variables) {
+		return '';
+	}
+
+	/** @type {Record<string, StandardSchemaV1.Issue[]>} */
+	const issues = {};
+
+	/** @type {string[]} */
+	const exports = [];
+
+	for (const [name, config] of Object.entries(variables)) {
+		if (config.public) continue;
+
+		const value = config.static
+			? devalue.uneval(validate(variables, env[name], name, issues))
+			: `env.${name}`;
+
+		exports.push(`export const ${name} = ${value};\n`);
+	}
+
+	handle_issues(issues);
+
+	return `import { dynamic_private_env as env } from '__sveltekit/env';\n\n${exports.join('')}`;
+}
+
+/**
+ * Creates the `__sveltekit/env/public/*` modules
+ * @param {Record<string, EnvVarConfig<any>> | null} variables
+ * @param {Record<string, string>} env
+ * @param {string} prelude
+ */
+export function create_sveltekit_env_public(variables, env, prelude) {
+	if (!variables) {
+		return '';
+	}
+
+	/** @type {Record<string, StandardSchemaV1.Issue[]>} */
+	const issues = {};
+
+	/** @type {string[]} */
+	const exports = [];
+
+	for (const [name, config] of Object.entries(variables)) {
+		if (!config.public) continue;
+
+		const value = config.static
+			? devalue.uneval(validate(variables, env[name], name, issues))
+			: `env.${name}`;
+
+		exports.push(`export const ${name} = ${value};\n`);
 	}
-	return `export { ${type}_env as env } from '${runtime_base}/shared-server.js';`;
+
+	handle_issues(issues);
+
+	return `${prelude}\n\n${exports.join('')}`;
+}
+
+/**
+ * Creates the `__sveltekit/env/service-worker` module used in development
+ * (but not in prod, which goes through build_service_worker instead)
+ * @param {Record<string, EnvVarConfig<any>> | null} variables
+ * @param {Record<string, string>} env
+ * @param {string} global
+ */
+export function create_sveltekit_env_service_worker_dev(variables, env, global) {
+	/** @type {string[]} */
+	const properties = [];
+
+	/** @type {Record<string, StandardSchemaV1.Issue[]>} */
+	const issues = {};
+
+	for (const [name, config] of Object.entries(variables ?? {})) {
+		if (!config.public) continue;
+
+		const value = validate(variables ?? {}, env[name], name, issues);
+		properties.push(`${name}: ${devalue.uneval(value)}`);
+	}
+
+	handle_issues(issues);
+
+	return dedent`
+		globalThis.__SVELTEKIT_EXPERIMENTAL_EXPLICIT_ENVIRONMENT_VARIABLES__ = true;
+
+		${global} = {
+			env: {
+				${properties.join(',\n\t\t') || '// empty'}
+			}
+		};
+	`;
+}
+
+/** @param {string} description */
+function create_jsdoc(description) {
+	return `/**\n${description
+		.split('\n')
+		.map((line) => ` * ${line.replaceAll('*/', '*\\/')}`)
+		.join('\n')}\n */`;
 }
 
 /**
@@ -98,6 +380,29 @@ export function create_dynamic_types(id, env, { public_prefix, private_prefix })
 	`;
 }
 
+/**
+ * @param {Record<string, EnvVarConfig<any>>} variables
+ * @param {string} relative
+ * @param {EnvType} type
+ */
+export function create_explicit_env_types(variables, relative, type) {
+	const declarations = Object.entries(variables)
+		.filter(([_, config]) => !!config.public === (type === 'public'))
+		.map(([name, config]) => {
+			const comment = config.description ? `${create_jsdoc(config.description)}\n` : '';
+			const type = config.schema
+				? `import('@sveltejs/kit/internal/types').StandardSchemaV1.InferOutput<typeof import('${relative}').variables.${name}.schema>`
+				: 'string';
+			return `${comment}export const ${name}: ${type};`;
+		});
+
+	return dedent`
+		declare module '$app/env/${type}' {
+			${declarations.join('\n') || `// no ${type} environment variables were defined`}
+		}
+	`;
+}
+
 export const reserved = new Set([
 	'do',
 	'if',

package/src/core/postbuild/analyse.js

@@ -50,7 +50,7 @@ async function analyse({
 
 	installPolyfills();
 
-	// configure `import { building } from '$app/environment'` —
+	// configure `import { building } from '$app/environment'` and `$app/env` —
 	// essential we do this before analysing the code
 	internal.set_building();
 
@@ -60,6 +60,7 @@ async function analyse({
 	const public_env = filter_env(env, public_prefix, private_prefix);
 	internal.set_private_env(private_env);
 	internal.set_public_env(public_env);
+	internal.set_env(env);
 	internal.set_manifest(manifest);
 	internal.set_read_implementation((file) => createReadableStream(`${server_root}/server/${file}`));
 

package/src/core/postbuild/fallback.js

@@ -2,7 +2,6 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { installPolyfills } from '../../exports/node/polyfills.js';
-import { load_config } from '../config/index.js';
 import { forked } from '../../utils/fork.js';
 
 export default forked(import.meta.url, generate_fallback);
@@ -11,15 +10,15 @@ export default forked(import.meta.url, generate_fallback);
  * @param {{
  *   manifest_path: string;
  *   env: Record<string, string>
+ *   out_dir: string;
+ *   origin: string;
+ *   assets: string;
  * }} opts
  */
-async function generate_fallback({ manifest_path, env }) {
-	/** @type {import('types').ValidatedKitConfig} */
-	const config = (await load_config()).kit;
-
+async function generate_fallback({ manifest_path, env, out_dir, origin, assets }) {
 	installPolyfills();
 
-	const server_root = join(config.outDir, 'output');
+	const server_root = join(out_dir, 'output');
 
 	/** @type {import('types').ServerInternalModule} */
 	const { set_building } = await import(pathToFileURL(`${server_root}/server/internal.js`).href);
@@ -35,7 +34,7 @@ async function generate_fallback({ manifest_path, env }) {
 	const server = new Server(manifest);
 	await server.init({ env });
 
-	const response = await server.respond(new Request(config.prerender.origin + '/[fallback]'), {
+	const response = await server.respond(new Request(origin + '/[fallback]'), {
 		getClientAddress: () => {
 			throw new Error('Cannot read clientAddress during prerendering');
 		},
@@ -44,7 +43,7 @@ async function generate_fallback({ manifest_path, env }) {
 			dependencies: new Map(),
 			remote_responses: new Map()
 		},
-		read: (file) => readFileSync(join(config.files.assets, file))
+		read: (file) => readFileSync(join(assets, file))
 	});
 
 	if (response.ok) {

package/src/core/postbuild/prerender.js

@@ -46,7 +46,7 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	/** @type {import('types').ServerModule} */
 	const { Server } = await import(pathToFileURL(`${out}/server/index.js`).href);
 
-	// configure `import { building } from '$app/environment'` —
+	// configure `import { building } from '$app/environment'` and `$app/env` —
 	// essential we do this before analysing the code
 	internal.set_building();
 	internal.set_prerendering();
@@ -106,7 +106,10 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	if (hash) {
 		const fallback = await generate_fallback({
 			manifest_path,
-			env
+			env,
+			out_dir: config.outDir,
+			origin: config.prerender.origin,
+			assets: config.files.assets
 		});
 
 		const file = output_filename('/', true);
@@ -494,6 +497,7 @@ async function prerender({ hash, out, manifest_path, metadata, verbose, env }) {
 	const public_env = filter_env(env, public_prefix, private_prefix);
 	internal.set_private_env(private_env);
 	internal.set_public_env(public_env);
+	internal.set_env(env);
 	internal.set_manifest(manifest);
 	internal.set_read_implementation((file) => createReadableStream(`${out}/server/${file}`));
 

package/src/core/sync/sync.js

@@ -11,6 +11,8 @@ import {
 	create_node_analyser,
 	get_page_options
 } from '../../exports/vite/static_analysis/index.js';
+import { load_explicit_env } from '../env.js';
+import { write_env } from './write_env.js';
 
 /**
  * Initialize SvelteKit's generated files that only depend on the config and mode.
@@ -87,6 +89,20 @@ export function all_types(config, mode) {
 	write_non_ambient(config.kit, manifest_data);
 }
 
+/**
+ * Generate modules and types for explicit env vars
+ * @param {import('types').ValidatedKitConfig} kit
+ * @param {string | null} entry
+ * @param {string} mode The Vite mode
+ */
+export async function env(kit, entry, mode) {
+	const env_config = await load_explicit_env(kit, entry, mode);
+
+	write_env(kit, entry, env_config);
+
+	return env_config;
+}
+
 /**
  * Regenerate __SERVER__/internal.js in response to src/{app.html,error.html,service-worker.js} changing
  * @param {import('types').ValidatedConfig} config

package/src/core/sync/write_ambient.js

@@ -53,11 +53,17 @@ ${create_dynamic_types('public', env, prefixes)}
  * @param {string} mode The Vite mode
  */
 export function write_ambient(config, mode) {
-	const env = get_env(config.env, mode);
-	const { publicPrefix: public_prefix, privatePrefix: private_prefix } = config.env;
+	/** @type {string} */
+	let content;
 
-	write_if_changed(
-		path.join(config.outDir, 'ambient.d.ts'),
-		template(env, { public_prefix, private_prefix })
-	);
+	if (config.experimental.explicitEnvironmentVariables) {
+		content = `${GENERATED_COMMENT}\n/// <reference types="@sveltejs/kit" />`;
+	} else {
+		const env = get_env(config.env, mode);
+		const { publicPrefix: public_prefix, privatePrefix: private_prefix } = config.env;
+
+		content = template(env, { public_prefix, private_prefix });
+	}
+
+	write_if_changed(path.join(config.outDir, 'ambient.d.ts'), content);
 }

package/src/core/sync/write_env.js

@@ -0,0 +1,32 @@
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
+import path from 'node:path';
+import { create_explicit_env_types } from '../env.js';
+import { write_if_changed } from './utils.js';
+
+const DOCS = '// See https://svelte.dev/docs/kit/environment-variables for more information';
+
+/**
+ * Writes ambient declarations including types reference to @sveltejs/kit,
+ * and the existing environment variables in process.env to
+ * $env/static/private and $env/static/public
+ * @param {import('types').ValidatedKitConfig} kit
+ * @param {string | null} entry
+ * @param {Record<string, EnvVarConfig<any>> | null} env_config
+ */
+export function write_env(kit, entry, env_config) {
+	const content = [];
+	const out = path.join(kit.outDir, 'env.d.ts');
+
+	if (entry && env_config) {
+		const relative = path.relative(kit.outDir, entry);
+		content.push(
+			`// This file is generated from ${relative}.\n${DOCS}`,
+			create_explicit_env_types(env_config, relative, 'private'),
+			create_explicit_env_types(env_config, relative, 'public')
+		);
+	} else {
+		content.push(DOCS);
+	}
+
+	write_if_changed(out, content.join('\n\n'));
+}

package/src/core/sync/write_root.js

@@ -100,7 +100,7 @@ export function write_root(manifest_data, config, output) {
 			${isSvelte5Plus() ? '<svelte:options runes={true} />' : ''}
 			<script>
 				import { setContext, ${isSvelte5Plus() ? '' : 'afterUpdate, '}onMount, tick } from 'svelte';
-				import { browser } from '$app/environment';
+				import { browser } from '$app/env';
 
 				// stores
 				${

package/src/core/sync/write_server.js

@@ -30,9 +30,10 @@ const server_template = ({
 	error_page
 }) => `
 import root from '../root.${isSvelte5Plus() ? 'js' : 'svelte'}';
-import { set_building, set_prerendering } from '__sveltekit/environment';
+import { set_building, set_prerendering } from '$app/env/internal';
 import { set_assets } from '$app/paths/internal/server';
 import { set_manifest, set_read_implementation } from '__sveltekit/server';
+import { set_env } from '__sveltekit/env';
 import { set_private_env, set_public_env } from '${runtime_directory}/shared-server.js';
 
 export const options = {
@@ -92,7 +93,7 @@ export async function get_hooks() {
 	};
 }
 
-export { set_assets, set_building, set_manifest, set_prerendering, set_private_env, set_public_env, set_read_implementation };
+export { set_assets, set_building, set_env, set_manifest, set_prerendering, set_private_env, set_public_env, set_read_implementation };
 `;
 
 // TODO need to re-run this whenever src/app.html or src/error.html are

package/src/core/sync/write_tsconfig.js

@@ -57,6 +57,7 @@ export function get_tsconfig(kit) {
 
 	const include = new Set([
 		'ambient.d.ts', // careful: changing this name would be a breaking change, because it's referenced in the service-workers documentation
+		'env.d.ts',
 		'non-ambient.d.ts',
 		'./types/**/$types.d.ts',
 		config_relative('vite.config.js'),

package/src/exports/hooks/index.js

@@ -1 +1,14 @@
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
+
 export { sequence } from './sequence.js';
+
+/**
+ * Utility for defining [environment variables](https://svelte.dev/docs/kit/environment-variables),
+ * which are made available via `$app/env/public` and `$app/env/private`.
+ * @template {Record<string, EnvVarConfig<any>>} T
+ * @param {T} variables
+ * @returns {T}
+ */
+export function defineEnvVars(variables) {
+	return variables;
+}

package/src/exports/internal/env.js

@@ -0,0 +1,71 @@
+/** @import { StandardSchemaV1 } from '@standard-schema/spec' */
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
+
+import { stackless } from '../vite/utils.js';
+
+const MISSING = {
+	message: `Value is missing. If it is optional, add a Standard Schema validator declaring it as such.`
+};
+
+const BAD_VALIDATOR = {
+	message: 'Variable was configured with a validator that does not implement Standard Schema'
+};
+
+const ASYNC_VALIDATOR = {
+	message: 'Variable uses an async validator, which is not supported'
+};
+
+/**
+ * @param {Record<string, EnvVarConfig<any>>} variables
+ * @param {string | undefined} value
+ * @param {string} name
+ * @param {Record<string, StandardSchemaV1.Issue[]>} issues
+ * @returns
+ */
+export function validate(variables, value, name, issues) {
+	const config = variables[name] ?? {};
+	const validator = config.schema;
+
+	if (!validator) {
+		if (!value) issues[name] = [MISSING];
+		return value;
+	}
+
+	if (!validator['~standard']) {
+		issues[name] = [BAD_VALIDATOR];
+		return;
+	}
+
+	const result = validator['~standard'].validate(value);
+
+	if (result instanceof Promise) {
+		issues[name] = [ASYNC_VALIDATOR];
+		return;
+	}
+
+	if (result.issues) {
+		issues[name] = [...result.issues];
+		return;
+	}
+
+	return result.value;
+}
+
+/**
+ * @param {Record<string, StandardSchemaV1.Issue[]>} issues
+ */
+export function handle_issues(issues) {
+	const entries = Object.entries(issues);
+
+	if (entries.length === 0) {
+		return;
+	}
+
+	let message = 'Invalid environment variables\n';
+
+	for (const [name, issues] of entries) {
+		message += `\n${name}\n${issues.map((issue) => `  - ${issue.message}`).join('\n')}\n`;
+	}
+
+	throw stackless(message);
+}

package/src/exports/internal/types.d.ts

@@ -0,0 +1,3 @@
+// We re-export this so we can use it in the `$app/env/*` module declarations
+// without the app needing to depend on this package
+export { StandardSchemaV1 } from '@standard-schema/spec';