@sveltejs/kit 2.62.0 → 2.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltejs/kit",
-  "version": "2.62.0",
+  "version": "2.63.0",
   "description": "SvelteKit is the fastest way to build Svelte apps",
   "keywords": [
     "framework",
@@ -76,6 +76,10 @@
     "#app/paths": {
       "browser": "./src/runtime/app/paths/client.js",
       "default": "./src/runtime/app/paths/server.js"
+    },
+    "#app/env/public": {
+      "browser": "./src/runtime/app/env/public/client.js",
+      "default": "./src/runtime/app/env/public/server.js"
     }
   },
   "exports": {
@@ -88,6 +92,13 @@
       "types": "./types/index.d.ts",
       "import": "./src/exports/internal/index.js"
     },
+    "./internal/env": {
+      "types": "./types/index.d.ts",
+      "import": "./src/exports/internal/env.js"
+    },
+    "./internal/types": {
+      "import": "./src/exports/internal/types.js"
+    },
     "./internal/server": {
       "types": "./types/index.d.ts",
       "import": "./src/exports/internal/server.js"

package/src/cli.js

@@ -4,6 +4,7 @@ import { parseArgs } from 'node:util';
 import colors from 'kleur';
 import { load_config } from './core/config/index.js';
 import { coalesce_to_error } from './utils/error.js';
+import { resolve_explicit_env_entry } from './core/env.js';
 
 /** @param {unknown} e */
 function handle_error(e) {
@@ -73,20 +74,45 @@ if (!command) {
 }
 
 if (command === 'sync') {
-	const config_files = ['js', 'ts']
-		.map((ext) => `svelte.config.${ext}`)
-		.filter((f) => fs.existsSync(f));
-	if (config_files.length === 0) {
-		console.warn(`Missing Svelte config file in ${process.cwd()} — skipping`);
-		process.exit(0);
+	// create placeholder .svelte-kit/tsconfig.json if necessary, to squelch warnings.
+	// this isn't bulletproof — if someone has some esoteric config, it will continue
+	// to harmlessly warn — but we handle the 90% case and clean up after ourselves
+	const sveltekit_dir = '.svelte-kit';
+	const base_tsconfig = `${sveltekit_dir}/tsconfig.json`;
+	const base_tsconfig_json = '{}';
+
+	const sveltekit_dir_exists = fs.existsSync(sveltekit_dir);
+	const base_tsconfig_exists = fs.existsSync(base_tsconfig);
+
+	if (!base_tsconfig_exists) {
+		try {
+			fs.mkdirSync('.svelte-kit');
+		} catch {
+			// ignore
+		}
+
+		fs.writeFileSync(base_tsconfig, base_tsconfig_json);
 	}
 
 	try {
 		const config = await load_config();
 		const sync = await import('./core/sync/sync.js');
 		sync.all_types(config, values.mode);
+
+		const explicit_env_entry = resolve_explicit_env_entry(config.kit);
+		await sync.env(config.kit, explicit_env_entry, values.mode);
 	} catch (error) {
 		handle_error(error);
+	} finally {
+		// if we errored, or accidentally created the wrong file
+		// (could happen!) then clean up after ourselves
+		if (fs.readFileSync(base_tsconfig, 'utf-8') === base_tsconfig_json) {
+			fs.unlinkSync(base_tsconfig);
+		}
+
+		if (!sveltekit_dir_exists && fs.readdirSync(sveltekit_dir).length === 0) {
+			fs.rmSync(sveltekit_dir, { recursive: true });
+		}
 	}
 } else {
 	console.error(colors.bold().red(`> Unknown command: ${command}`));

package/src/core/adapt/builder.js

@@ -1,8 +1,10 @@
+/** @import { StandardSchemaV1 } from '@standard-schema/spec' */
 /** @import { Builder } from '@sveltejs/kit' */
 /** @import { ResolvedConfig } from 'vite' */
-/** @import { RouteDefinition } from '@sveltejs/kit' */
+/** @import { RouteDefinition, EnvVarConfig } from '@sveltejs/kit' */
 /** @import { RouteData, ValidatedConfig, BuildData, ServerMetadata, ServerMetadataRoute, Prerendered, PrerenderMap, Logger, RemoteChunk } from 'types' */
 import colors from 'kleur';
+import * as devalue from 'devalue';
 import { createReadStream, createWriteStream, existsSync, statSync } from 'node:fs';
 import { extname, resolve, join, dirname, relative } from 'node:path';
 import { pipeline } from 'node:stream';
@@ -17,6 +19,7 @@ import { write } from '../sync/utils.js';
 import { list_files } from '../utils.js';
 import { find_server_assets } from '../generate_manifest/find_server_assets.js';
 import { reserved } from '../env.js';
+import { handle_issues, validate } from '../../exports/internal/env.js';
 
 const pipe = promisify(pipeline);
 const extensions = ['.html', '.js', '.mjs', '.json', '.css', '.svg', '.xml', '.wasm', '.txt'];
@@ -32,7 +35,8 @@ const extensions = ['.html', '.js', '.mjs', '.json', '.css', '.svg', '.xml', '.w
  *   prerender_map: PrerenderMap;
  *   log: Logger;
  *   vite_config: ResolvedConfig;
- *   remotes: RemoteChunk[]
+ *   remotes: RemoteChunk[];
+ *   explicit_env_config: Record<string, EnvVarConfig<any>> | null;
  * }} opts
  * @returns {Builder}
  */
@@ -45,7 +49,8 @@ export function create_builder({
 	prerender_map,
 	log,
 	vite_config,
-	remotes
+	remotes,
+	explicit_env_config
 }) {
 	/** @type {Map<RouteDefinition, RouteData>} */
 	const lookup = new Map();
@@ -168,7 +173,7 @@ export function create_builder({
 
 			const fallback = await generate_fallback({
 				manifest_path,
-				env: { ...env.private, ...env.public },
+				env: env.all,
 				out_dir: config.kit.outDir,
 				origin: config.kit.prerender.origin,
 				assets: config.kit.files.assets
@@ -193,7 +198,23 @@ export function create_builder({
 			const dest = `${config.kit.outDir}/output/prerendered/dependencies/${config.kit.appDir}/env.js`;
 			const env = get_env(config.kit.env, vite_config.mode);
 
-			write(dest, `export const env=${JSON.stringify(env.public)}`);
+			const values = config.kit.experimental.explicitEnvironmentVariables ? {} : env.public;
+
+			if (config.kit.experimental.explicitEnvironmentVariables) {
+				const variables = explicit_env_config ?? {};
+
+				/** @type {Record<string, StandardSchemaV1.Issue[]>} */
+				const issues = {};
+
+				for (const [name, config] of Object.entries(variables)) {
+					if (config.static || !config.public) continue;
+					values[name] = validate(variables, env.all[name], name, issues);
+				}
+
+				handle_issues(issues);
+			}
+
+			write(dest, `export const env=${devalue.uneval(values)}`);
 		},
 
 		generateManifest({ relativePath, routes: subset }) {

package/src/core/adapt/index.js

@@ -10,6 +10,7 @@ import { create_builder } from './builder.js';
  * @param {import('types').Logger} log
  * @param {import('types').RemoteChunk[]} remotes
  * @param {import('vite').ResolvedConfig} vite_config
+ * @param {Record<string, import('@sveltejs/kit').EnvVarConfig<any>> | null} explicit_env_config
  */
 export async function adapt(
 	config,
@@ -19,7 +20,8 @@ export async function adapt(
 	prerender_map,
 	log,
 	remotes,
-	vite_config
+	vite_config,
+	explicit_env_config
 ) {
 	// This is only called when adapter is truthy, so the cast is safe
 	const { name, adapt } = /** @type {import('@sveltejs/kit').Adapter} */ (config.kit.adapter);
@@ -35,7 +37,8 @@ export async function adapt(
 		prerender_map,
 		log,
 		remotes,
-		vite_config
+		vite_config,
+		explicit_env_config
 	});
 
 	await adapt(builder);

package/src/core/config/index.js

@@ -33,11 +33,13 @@ export function load_template(cwd, { kit }) {
 		}
 	});
 
-	for (const match of contents.matchAll(/%sveltekit\.env\.([^%]+)%/g)) {
-		if (!match[1].startsWith(env.publicPrefix)) {
-			throw new Error(
-				`Environment variables in ${relative} must start with ${env.publicPrefix} (saw %sveltekit.env.${match[1]}%)`
-			);
+	if (!kit.experimental.explicitEnvironmentVariables) {
+		for (const match of contents.matchAll(/%sveltekit\.env\.([^%]+)%/g)) {
+			if (!match[1].startsWith(env.publicPrefix)) {
+				throw new Error(
+					`Environment variables in ${relative} must start with ${env.publicPrefix} (saw %sveltekit.env.${match[1]}%)`
+				);
+			}
 		}
 	}
 

package/src/core/config/options.js

@@ -139,6 +139,7 @@ const options = object(
 				instrumentation: object({
 					server: boolean(false)
 				}),
+				explicitEnvironmentVariables: boolean(false),
 				remoteFunctions: boolean(false),
 				forkPreloads: boolean(false),
 				handleRenderingErrors: boolean(false)

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/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();
@@ -497,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);
 }