@sveltejs/kit 2.62.0 → 2.63.1

package/src/core/sync/create_manifest_data/index.js

@@ -33,6 +33,7 @@ export default function create_manifest_data({
 	const matchers = create_matchers(config, cwd);
 	const { nodes, routes } = create_routes_and_nodes(cwd, config, fallback);
 
+	// validate matcher names used in parameterised routes
 	for (const route of routes) {
 		for (const param of route.params) {
 			if (param.matcher && !matchers[param.matcher]) {
@@ -51,6 +52,7 @@ export default function create_manifest_data({
 }
 
 /**
+ * Returns a list of files in the `static` directory.
  * @param {import('types').ValidatedConfig} config
  */
 export function create_assets(config) {
@@ -131,6 +133,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 	/** @type {import('types').PageNode[]} */
 	const nodes = [];
 
+	// create route data by processing files in `src/routes`
 	if (fs.existsSync(config.kit.files.routes)) {
 		/**
 		 * @param {number} depth
@@ -390,6 +393,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 
 	prevent_conflicts(routes);
 
+	// fallback root layout and root error components
 	const root = routes[0];
 
 	if (!root.layout?.component) {
@@ -398,10 +402,11 @@ function create_routes_and_nodes(cwd, config, fallback) {
 	}
 
 	if (!root.error?.component) {
-		if (!root.error) root.error = { depth: 0 };
+		if (!root.error) root.error = { depth: 0, parent: root.layout };
 		root.error.component = posixify(path.relative(cwd, `${fallback}/error.svelte`));
 	}
 
+	// populate the page nodes list
 	// we do layouts/errors first as they are more likely to be reused,
 	// and smaller indexes take fewer bytes. also, this guarantees that
 	// the default error/layout are 0/1
@@ -423,6 +428,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 
 	const node_analyser = create_node_analyser();
 
+	// add the related layout, page, and error nodes for a route
 	for (const route of routes) {
 		if (!route.leaf) continue;
 
@@ -467,6 +473,22 @@ function create_routes_and_nodes(cwd, config, fallback) {
 		}
 	}
 
+	// add parents to error nodes so that we can compute which page options apply to them
+	for (const route of routes) {
+		if (!route.error) continue;
+
+		/** @type {import('types').RouteData | null} */
+		let current_route = route;
+		while (current_route) {
+			if (current_route.layout) {
+				route.error.parent = current_route.layout;
+				break;
+			}
+			current_route = current_route.parent;
+		}
+	}
+
+	// compute the final page options for each page node
 	for (const node of nodes) {
 		node.page_options = node_analyser.get_page_options(node);
 	}
@@ -484,6 +506,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 }
 
 /**
+ * Determine if and how the file is relevant to the routing system.
  * @param {string} project_relative
  * @param {string} file
  * @param {string[]} component_extensions

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,33 @@
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
+import path from 'node:path';
+import { create_explicit_env_types } from '../env.js';
+import { posixify } from '../../utils/filesystem.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 = posixify(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 '../../utils/error.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';

package/src/exports/public.d.ts

@@ -476,6 +476,13 @@ export interface KitConfig {
 	};
 	/** Experimental features. Here be dragons. These are not subject to semantic versioning, so breaking changes or removal can happen in any release. */
 	experimental?: {
+		/**
+		 * Whether to enable explicit environment variables using `src/env.js` or `src/env.ts`.
+		 * @since 2.63.0
+		 * @default false
+		 */
+		explicitEnvironmentVariables?: boolean;
+
 		/**
 		 * Options for enabling server-side [OpenTelemetry](https://opentelemetry.io/) tracing for SvelteKit operations including the [`handle` hook](https://svelte.dev/docs/kit/hooks#Server-hooks-handle), [`load` functions](https://svelte.dev/docs/kit/load), [form actions](https://svelte.dev/docs/kit/form-actions), and [remote functions](https://svelte.dev/docs/kit/remote-functions).
 		 * @default { server: false, serverFile: false }
@@ -2314,4 +2321,37 @@ export type RemoteLiveQueryFunction<Input, Output, _Validated = Input> = (
 	arg: undefined extends Input ? Input | void : Input
 ) => RemoteLiveQuery<Output>;
 
+/**
+ * [Environment variables](https://svelte.dev/docs/kit/environment-variables) can be configured by exporting
+ * a `variables` object from `src/env.ts`, using [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-hooks#defineEnvVars).
+ */
+export interface EnvVarConfig<T> {
+	/**
+	 * Whether the environment variable can be accessed by client-side code.
+	 * - if `true`, it can be imported from `$app/env/public`
+	 * - if `false`, it can be imported from `$app/env/private`, which is a [server-only module](https://svelte.dev/docs/kit/server-only-modules)
+	 * @default false
+	 */
+	public?: boolean;
+	/**
+	 * Whether the value is determined at build time or when the app runs.
+	 * - if `true`, the build time value is inlined into the bundle. This enables optimisations like dead-code elimination
+	 * - if `false`, the value is read from the environment when the app starts
+	 * @default false
+	 */
+	static?: boolean;
+	/**
+	 * A [Standard Schema](https://standardschema.dev/) validator that is applied to the value when the app starts.
+	 * The validator can output any value — not necessarily a string — but public, non-static values must be
+	 * serializable by [devalue](https://github.com/sveltejs/devalue) so that they can be sent to the browser.
+	 *
+	 * If omitted, the value must be a non-empty string.
+	 */
+	schema?: StandardSchemaV1<string | undefined, T>;
+	/**
+	 * A description of the variable that will be used for inline documentation on hover.
+	 */
+	description?: string;
+}
+
 export * from './index.js';

package/src/exports/vite/build/build_service_worker.js

@@ -1,10 +1,11 @@
+/** @import { EnvVarConfig } from '@sveltejs/kit' */
 import fs from 'node:fs';
 import process from 'node:process';
 import * as vite from 'vite';
 import { dedent } from '../../../core/sync/utils.js';
 import { s } from '../../../utils/misc.js';
 import { get_config_aliases, strip_virtual_prefix, get_env, normalize_id } from '../utils.js';
-import { create_static_module } from '../../../core/env.js';
+import { create_static_module, create_sveltekit_env_public } from '../../../core/env.js';
 import { env_static_public, service_worker } from '../module_ids.js';
 
 // @ts-ignore `vite.rolldownVersion` only exists in `rolldown-vite`
@@ -18,6 +19,7 @@ const is_rolldown = !!vite.rolldownVersion;
  * @param {string} service_worker_entry_file
  * @param {import('types').Prerendered} prerendered
  * @param {import('vite').Manifest} client_manifest
+ * @param {Record<string, EnvVarConfig<any>> | null} env_config
  */
 export async function build_service_worker(
 	out,
@@ -26,7 +28,8 @@ export async function build_service_worker(
 	manifest_data,
 	service_worker_entry_file,
 	prerendered,
-	client_manifest
+	client_manifest,
+	env_config
 ) {
 	const build = new Set();
 	for (const key in client_manifest) {
@@ -85,7 +88,20 @@ export async function build_service_worker(
 			}
 
 			if (id === env_static_public) {
-				return create_static_module('$env/static/public', env.public);
+				return create_static_module(
+					'$env/static/public',
+					env.public,
+					kit.experimental.explicitEnvironmentVariables
+				);
+			}
+
+			if (id === '\0virtual:app/env/public') {
+				// TODO ideally we would only add the `importScripts` if there are dynamic vars that are known to be used
+				return create_sveltekit_env_public(
+					env_config,
+					env.all,
+					`importScripts('${kit.paths.base}/${kit.appDir}/env.script.js'); const env = globalThis.__sveltekit_sw.env;`
+				);
 			}
 
 			const normalized_cwd = vite.normalizePath(process.cwd());
@@ -93,7 +109,7 @@ export async function build_service_worker(
 			const relative = normalize_id(id, normalized_lib, normalized_cwd);
 			const stripped = strip_virtual_prefix(relative);
 			throw new Error(
-				`Cannot import ${stripped} into service-worker code. Only the modules $service-worker and $env/static/public are available in service workers.`
+				`Cannot import ${stripped} into service-worker code. Only the modules $service-worker, $env/static/public and $app/env/public are available in service workers.`
 			);
 		}
 	};

package/src/exports/vite/dev/index.js

@@ -322,7 +322,7 @@ export async function dev(vite, vite_config, svelte_config, get_remotes) {
 			// ssrFixStacktrace can fail on StackBlitz web containers and we don't know why
 			// by ignoring it the line numbers are wrong, but at least we can show the error
 		}
-		return error.stack;
+		return error.stack?.replaceAll('\0', ''); // remove null bytes from e.g. virtual module IDs, or the response will fail
 	}
 
 	update_manifest();
@@ -587,7 +587,7 @@ export async function dev(vite, vite_config, svelte_config, get_remotes) {
 			} catch (e) {
 				const error = coalesce_to_error(e);
 				res.statusCode = 500;
-				res.end(fix_stack_trace(error));
+				res.end(fix_stack_trace(error) || error.message); // handle `stackless` errors
 			}
 		});
 	};