@sveltejs/kit 1.0.0-next.520 → 1.0.0-next.522

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltejs/kit",
-  "version": "1.0.0-next.520",
+  "version": "1.0.0-next.522",
   "repository": {
     "type": "git",
     "url": "https://github.com/sveltejs/kit",
@@ -80,13 +80,13 @@
     "node": ">=16.14"
   },
   "scripts": {
-    "build": "npm run types",
+    "build": "pnpm types",
     "lint": "prettier --check . --config ../../.prettierrc --ignore-path .gitignore",
     "check": "tsc",
     "check:all": "tsc && pnpm -r --filter=\"./**\" check",
-    "format": "npm run lint -- --write",
-    "test": "npm run test:unit && npm run test:integration",
-    "test:integration": "pnpm run -r --workspace-concurrency 1 --filter=\"./test/**\" test",
+    "format": "pnpm lint --write",
+    "test": "pnpm test:unit && pnpm test:integration",
+    "test:integration": "pnpm -r --workspace-concurrency 1 --filter=\"./test/**\" test",
     "test:unit": "uvu src \"(spec\\.js|test[\\\\/]index\\.js)\"",
     "types": "node scripts/extract-types.js",
     "postinstall": "node postinstall.js"

package/src/core/config/options.js

@@ -88,7 +88,7 @@ const options = object(
 			// TODO: remove this for the 1.0 release
 			amp: error(
 				(keypath) =>
-					`${keypath} has been removed. See https://kit.svelte.dev/docs/seo#amp for details on how to support AMP`
+					`${keypath} has been removed. See https://kit.svelte.dev/docs/seo#manual-setup-amp for details on how to support AMP`
 			),
 
 			appDir: validate('_app', (input, keypath) => {
@@ -321,7 +321,7 @@ const options = object(
 			// TODO remove this for 1.0
 			ssr: error(
 				(keypath) =>
-					`${keypath} has been removed — use the handle hook instead: https://kit.svelte.dev/docs/hooks#handle`
+					`${keypath} has been removed — use the handle hook instead: https://kit.svelte.dev/docs/hooks#server-hooks-handle`
 			),
 
 			// TODO remove this for 1.0

package/src/core/prerender/prerender.js

@@ -102,54 +102,15 @@ export async function prerender() {
 	});
 
 	installPolyfills();
+
+	// TODO remove this for 1.0
 	const { fetch } = globalThis;
 	globalThis.fetch = async (info, init) => {
-		/** @type {string} */
-		let url;
-
-		/** @type {RequestInit} */
-		let opts = {};
-
-		if (info instanceof Request) {
-			url = info.url;
-
-			opts = {
-				method: info.method,
-				headers: info.headers,
-				body: info.body,
-				mode: info.mode,
-				credentials: info.credentials,
-				cache: info.cache,
-				redirect: info.redirect,
-				referrer: info.referrer,
-				integrity: info.integrity
-			};
-		} else {
-			url = info.toString();
-		}
+		const url = info instanceof Request ? info.url : info.toString();
 
 		if (url.startsWith(config.prerender.origin + '/')) {
-			const request = new Request(url, opts);
-			const response = await server.respond(request, {
-				getClientAddress,
-				prerendering: {
-					dependencies: new Map()
-				}
-			});
-
-			const decoded = new URL(url).pathname;
-
-			save(
-				'dependencies',
-				response,
-				Buffer.from(await response.clone().arrayBuffer()),
-				decoded,
-				encodeURI(decoded),
-				null,
-				'fetched'
-			);
-
-			return response;
+			const sliced = url.slice(config.prerender.origin.length);
+			throw new Error(`Use \`event.fetch('${sliced}')\` instead of the global \`fetch('${url}')\``);
 		}
 
 		return fetch(info, init);
@@ -409,7 +370,7 @@ export async function prerender() {
 			for (const [id, prerender] of prerender_map) {
 				if (prerender) {
 					if (id.includes('[')) continue;
-					const path = `/${id.split('/').filter(affects_path).join('/')}`;
+					const path = `${id.split('/').filter(affects_path).join('/')}`;
 					enqueue(null, config.paths.base + path);
 				}
 			}

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

@@ -207,7 +207,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 			}
 		};
 
-		walk(0, '', '', null);
+		walk(0, '/', '', null);
 
 		if (routes.length === 1) {
 			const root = routes[0];
@@ -223,7 +223,7 @@ function create_routes_and_nodes(cwd, config, fallback) {
 		// If there's no routes directory, we'll just create a single empty route. This ensures the root layout and
 		// error components are included in the manifest, which is needed for subsequent build/dev commands to work
 		routes.push({
-			id: '',
+			id: '/',
 			segment: '',
 			pattern: /^$/,
 			names: [],

package/src/runtime/app/forms.js

@@ -21,11 +21,14 @@ export function enhance(form, submit = () => {}) {
 	 * @param {{
 	 *   action: URL;
 	 *   result: import('types').ActionResult;
+	 *   reset?: boolean
 	 * }} opts
 	 */
-	const fallback_callback = async ({ action, result }) => {
+	const fallback_callback = async ({ action, result, reset }) => {
 		if (result.type === 'success') {
-			form.reset();
+			if (reset !== false) {
+				form.reset();
+			}
 			await invalidateAll();
 		}
 
@@ -97,7 +100,7 @@ export function enhance(form, submit = () => {}) {
 			action,
 			data,
 			form,
-			update: () => fallback_callback({ action, result }),
+			update: (opts) => fallback_callback({ action, result, reset: opts?.reset }),
 			// @ts-expect-error generic constraints stuff we don't care about
 			result,
 			// TODO remove for 1.0

package/src/runtime/client/client.js

@@ -199,7 +199,7 @@ export function create_client({ target, base, trailing_slash }) {
 		const intent = get_navigation_intent(url, false);
 
 		if (!intent) {
-			throw new Error('Attempted to prefetch a URL that does not belong to this app');
+			throw new Error(`Attempted to prefetch a URL that does not belong to this app: ${url}`);
 		}
 
 		load_cache = { id: intent.id, promise: load_route(intent) };

package/src/runtime/client/fetcher.js

@@ -29,7 +29,7 @@ if (import.meta.env.DEV) {
 		const heuristic = can_inspect_stack_trace ? stack.includes('load_node') : loading;
 		if (heuristic) {
 			console.warn(
-				`Loading ${url} using \`window.fetch\`. For best results, use the \`fetch\` that is passed to your \`load\` function: https://kit.svelte.dev/docs/load#input-fetch`
+				`Loading ${url} using \`window.fetch\`. For best results, use the \`fetch\` that is passed to your \`load\` function: https://kit.svelte.dev/docs/load#making-fetch-requests`
 			);
 		}
 

package/src/runtime/server/fetch.js

@@ -16,9 +16,6 @@ export function create_fetch({ event, options, state, get_cookie_header }) {
 
 		const request_body = init?.body;
 
-		/** @type {import('types').PrerenderDependency} */
-		let dependency;
-
 		return await options.hooks.handleFetch({
 			event,
 			request,
@@ -135,11 +132,6 @@ export function create_fetch({ event, options, state, get_cookie_header }) {
 
 				response = await respond(request, options, state);
 
-				if (state.prerendering) {
-					dependency = { response, body: null };
-					state.prerendering.dependencies.set(url.pathname, dependency);
-				}
-
 				const set_cookie = response.headers.get('set-cookie');
 				if (set_cookie) {
 					for (const str of set_cookie_parser.splitCookiesString(set_cookie)) {

package/src/runtime/server/page/load_data.js

@@ -106,8 +106,13 @@ export async function load_data({
 			const url = new URL(input instanceof Request ? input.url : input, event.url);
 			const same_origin = url.origin === event.url.origin;
 
-			const request_body = init?.body;
-			const dependency = same_origin && state.prerendering?.dependencies.get(url.pathname);
+			/** @type {import('types').PrerenderDependency} */
+			let dependency;
+
+			if (same_origin && state.prerendering) {
+				dependency = { response, body: null };
+				state.prerendering.dependencies.set(url.pathname, dependency);
+			}
 
 			const proxy = new Proxy(response, {
 				get(response, key, _receiver) {
@@ -127,7 +132,7 @@ export async function load_data({
 							fetched.push({
 								url: same_origin ? url.href.slice(event.url.origin.length) : url.href,
 								method: event.request.method,
-								request_body: /** @type {string | ArrayBufferView | undefined} */ (request_body),
+								request_body: /** @type {string | ArrayBufferView | undefined} */ (init?.body),
 								response_body: body,
 								response: response
 							});
@@ -165,8 +170,6 @@ export async function load_data({
 						};
 					}
 
-					// TODO arrayBuffer?
-
 					return Reflect.get(response, key, response);
 				}
 			});
@@ -181,7 +184,7 @@ export async function load_data({
 						const included = resolve_opts.filterSerializedResponseHeaders(lower, value);
 						if (!included) {
 							throw new Error(
-								`Failed to get response header "${lower}" — it must be included by the \`filterSerializedResponseHeaders\` option: https://kit.svelte.dev/docs/hooks#handle (at ${event.routeId})`
+								`Failed to get response header "${lower}" — it must be included by the \`filterSerializedResponseHeaders\` option: https://kit.svelte.dev/docs/hooks#server-hooks-handle (at ${event.routeId})`
 							);
 						}
 					}

package/src/runtime/server/page/render.js

@@ -179,7 +179,7 @@ export async function render_response({
 		const match = /\[(\d+)\]\.data\.(.+)/.exec(error.path);
 		if (match) {
 			throw new Error(
-				`Data returned from \`load\` while rendering /${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
+				`Data returned from \`load\` while rendering ${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
 			);
 		}
 		throw error;

package/src/runtime/server/utils.js

@@ -83,7 +83,7 @@ export function data_response(data, event) {
 		const error = /** @type {any} */ (e);
 		const match = /\[(\d+)\]\.data\.(.+)/.exec(error.path);
 		const message = match
-			? `Data returned from \`load\` while rendering /${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
+			? `Data returned from \`load\` while rendering ${event.routeId} is not serializable: ${error.message} (data.${match[2]})`
 			: error.message;
 		return new Response(JSON.stringify(message), { headers, status: 500 });
 	}

package/src/utils/routing.js

@@ -13,11 +13,12 @@ export function parse_route_id(id) {
 	let add_trailing_slash = true;
 
 	const pattern =
-		id === ''
+		id === '/'
 			? /^\/$/
 			: new RegExp(
 					`^${id
 						.split(/(?:\/|$)/)
+						.slice(1)
 						.filter(affects_path)
 						.map((segment, i, segments) => {
 							const decoded_segment = decodeURIComponent(segment);

package/types/ambient.d.ts

@@ -110,7 +110,11 @@ declare module '$app/forms' {
 				form: HTMLFormElement;
 				action: URL;
 				result: ActionResult<Success, Invalid>;
-				update: () => Promise<void>;
+				/**
+				 * Call this to get the default behavior of a form submission response.
+				 * @param options Set `reset: false` if you don't want the `<form>` values to be reset after a successful submission.
+				 */
+				update: (options?: { reset: boolean }) => Promise<void>;
 		  }) => void);
 
 	/**
@@ -133,7 +137,7 @@ declare module '$app/forms' {
 		 * If this function or its return value isn't set, it
 		 * - falls back to updating the `form` prop with the returned data if the action is one same page as the form
 		 * - updates `$page.status`
-		 * - invalidates all data in case of successful submission with no redirect response
+		 * - resets the `<form>` element and invalidates all data in case of successful submission with no redirect response
 		 * - redirects in case of a redirect response
 		 * - redirects to the nearest error page in case of an unexpected error
 		 *

package/types/index.d.ts

@@ -271,18 +271,108 @@ export interface LoadEvent<
 	Data extends Record<string, unknown> | null = Record<string, any> | null,
 	ParentData extends Record<string, unknown> = Record<string, any>
 > extends NavigationEvent<Params> {
+	/**
+	 * `fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
+	 *
+	 * - it can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request
+	 * - it can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context)
+	 * - internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call
+	 * - during server-side rendering, the response will be captured and inlined into the rendered HTML. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](https://kit.svelte.dev/docs/hooks#server-hooks-handle)
+	 * - during hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request
+	 *
+	 * > Cookies will only be passed through if the target host is the same as the SvelteKit application or a more specific subdomain of it.
+	 */
 	fetch: typeof fetch;
+	/**
+	 * Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any.
+	 */
 	data: Data;
+	/**
+	 * If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
+	 *
+	 *	```js
+	 *	/// file: src/routes/blog/+page.js
+	 *	export async function load({ fetch, setHeaders }) {
+	 *		const url = `https://cms.example.com/articles.json`;
+	 *		const response = await fetch(url);
+	 *
+	 *		setHeaders({
+	 *			age: response.headers.get('age'),
+	 *			'cache-control': response.headers.get('cache-control')
+	 *		});
+	 *
+	 *		return response.json();
+	 *	}
+	 *	```
+	 *
+	 * Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
+	 *
+	 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://kit.svelte.dev/docs/types#sveltejs-kit-cookies) API in a server-only `load` function instead.
+	 *
+	 * `setHeaders` has no effect when a `load` function runs in the browser.
+	 */
 	setHeaders: (headers: Record<string, string>) => void;
+	/**
+	 * `await parent()` returns data from parent `+layout.js` `load` functions.
+	 * Implicitly, a missing `+layout.js` is treated as a `({ data }) => data` function, meaning that it will return and forward data from parent `+layout.server.js` files.
+	 *
+	 * Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
+	 */
 	parent: () => Promise<ParentData>;
+	/**
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/modules#$app-navigation-invalidate) to cause `load` to rerun.
+	 *
+	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
+	 *
+	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
+	 *
+	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
+	 *
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 *
+	 * ```js
+	 * /// file: src/routes/+page.js
+	 * let count = 0;
+	 * export async function load({ depends }) {
+	 * 	depends('increase:count');
+	 *
+	 * 	return { count: count++ };
+	 * }
+	 * ```
+	 *
+	 * ```html
+	 * /// file: src/routes/+page.svelte
+	 * <script>
+	 * 	import { invalidate } from '$app/navigation';
+	 *
+	 * 	export let data;
+	 *
+	 * 	const increase = async () => {
+	 * 		await invalidate('increase:count');
+	 * 	}
+	 * </script>
+	 *
+	 * <p>{data.count}<p>
+	 * <button on:click={increase}>Increase Count</button>
+	 * ```
+	 */
 	depends: (...deps: string[]) => void;
 }
 
 export interface NavigationEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>
 > {
+	/**
+	 * The parameters of the current page - e.g. for a route like `/blog/[slug]`, the `slug` parameter
+	 */
 	params: Params;
+	/**
+	 * The route ID of the current page - e.g. for `src/routes/blog/[slug]`, it would be `blog/[slug]`
+	 */
 	routeId: string | null;
+	/**
+	 * The URL of the current page
+	 */
 	url: URL;
 }
 
@@ -342,15 +432,70 @@ export interface ParamMatcher {
 export interface RequestEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>
 > {
+	/**
+	 * Get or set cookies related to the current request
+	 */
 	cookies: Cookies;
+	/**
+	 * `fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
+	 *
+	 * - it can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request
+	 * - it can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context)
+	 * - internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call
+	 *
+	 * > Cookies will only be passed through if the target host is the same as the SvelteKit application or a more specific subdomain of it.
+	 */
 	fetch: typeof fetch;
+	/**
+	 * The client's IP address, set by the adapter.
+	 */
 	getClientAddress: () => string;
+	/**
+	 * Contains custom data that was added to the request within the [`handle hook`](https://kit.svelte.dev/docs/hooks#server-hooks-handle).
+	 */
 	locals: App.Locals;
+	/**
+	 * The parameters of the current page or endpoint - e.g. for a route like `/blog/[slug]`, the `slug` parameter
+	 */
 	params: Params;
+	/**
+	 * Additional data made available through the adapter.
+	 */
 	platform: Readonly<App.Platform>;
+	/**
+	 * The original request object
+	 */
 	request: Request;
+	/**
+	 * The route ID of the current page - e.g. for `src/routes/blog/[slug]`, it would be `blog/[slug]`
+	 */
 	routeId: string | null;
+	/**
+	 * If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
+	 *
+	 *	```js
+	 *	/// file: src/routes/blog/+page.js
+	 *	export async function load({ fetch, setHeaders }) {
+	 *		const url = `https://cms.example.com/articles.json`;
+	 *		const response = await fetch(url);
+	 *
+	 *		setHeaders({
+	 *			age: response.headers.get('age'),
+	 *			'cache-control': response.headers.get('cache-control')
+	 *		});
+	 *
+	 *		return response.json();
+	 *	}
+	 *	```
+	 *
+	 * Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
+	 *
+	 * You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](https://kit.svelte.dev/docs/types#sveltejs-kit-cookies) API instead.
+	 */
 	setHeaders: (headers: Record<string, string>) => void;
+	/**
+	 * The URL of the current page or endpoint
+	 */
 	url: URL;
 }
 
@@ -415,7 +560,49 @@ export interface ServerLoadEvent<
 	Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
 	ParentData extends Record<string, any> = Record<string, any>
 > extends RequestEvent<Params> {
+	/**
+	 * `await parent()` returns data from parent `+layout.server.js` `load` functions.
+	 *
+	 * Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
+	 */
 	parent: () => Promise<ParentData>;
+	/**
+	 * This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/modules#$app-navigation-invalidate) to cause `load` to rerun.
+	 *
+	 * Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
+	 *
+	 * URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
+	 *
+	 * Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
+	 *
+	 * The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
+	 *
+	 * ```js
+	 * /// file: src/routes/+page.js
+	 * let count = 0;
+	 * export async function load({ depends }) {
+	 * 	depends('increase:count');
+	 *
+	 * 	return { count: count++ };
+	 * }
+	 * ```
+	 *
+	 * ```html
+	 * /// file: src/routes/+page.svelte
+	 * <script>
+	 * 	import { invalidate } from '$app/navigation';
+	 *
+	 * 	export let data;
+	 *
+	 * 	const increase = async () => {
+	 * 		await invalidate('increase:count');
+	 * 	}
+	 * </script>
+	 *
+	 * <p>{data.count}<p>
+	 * <button on:click={increase}>Increase Count</button>
+	 * ```
+	 */
 	depends: (...deps: string[]) => void;
 }