From 6042fdaadbcdcc505012a2f8cc63180eb0f053dd Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Sat, 28 Sep 2024 10:55:27 -0400 Subject: [PATCH 1/8] use runtime includes --- .../docs/kit/98-reference/10-@sveltejs-kit.md | 3431 +---------------- .../15-@sveltejs-kit-node-polyfills.md | 24 +- .../includes/kit/$app/environment/index.md | 59 + .../includes/kit/$app/forms/index.md | 102 + .../includes/kit/$app/navigation/index.md | 246 ++ .../includes/kit/$app/paths/index.md | 68 + .../includes/kit/$app/server/index.md | 29 + .../includes/kit/$app/stores/index.md | 79 + .../kit/$env/dynamic/private/index.md | 14 + .../includes/kit/$env/dynamic/public/index.md | 12 + .../includes/kit/$env/static/private/index.md | 21 + .../includes/kit/$env/static/public/index.md | 9 + apps/svelte.dev/includes/kit/$lib/index.md | 7 + .../includes/kit/$service-worker/index.md | 77 + .../includes/kit/@sveltejs/kit/hooks/index.md | 85 + .../includes/kit/@sveltejs/kit/index.md | 2605 +++++++++++++ .../includes/kit/@sveltejs/kit/node/index.md | 61 + .../kit/@sveltejs/kit/node/polyfills/index.md | 22 + .../includes/kit/@sveltejs/kit/vite/index.md | 20 + apps/svelte.dev/includes/kit/App/index.md | 74 + .../includes/kit/Private types/index.md | 818 ++++ .../includes/kit/__configuration/index.md | 1105 ++++++ .../includes/svelte/$derived/index.md | 162 + .../includes/svelte/$effect/index.md | 228 ++ .../includes/svelte/$state/index.md | 248 ++ .../includes/svelte/svelte/action/index.md | 105 + .../includes/svelte/svelte/animate/index.md | 123 + .../includes/svelte/svelte/compiler/index.md | 1305 +++++++ .../includes/svelte/svelte/easing/index.md | 442 +++ .../includes/svelte/svelte/events/index.md | 125 + .../includes/svelte/svelte/index.md | 845 ++++ .../includes/svelte/svelte/legacy/index.md | 240 ++ .../includes/svelte/svelte/motion/index.md | 124 + .../svelte/svelte/reactivity/index.md | 153 + .../includes/svelte/svelte/server/index.md | 44 + .../includes/svelte/svelte/store/index.md | 320 ++ .../svelte/svelte/transition/index.md | 589 +++ apps/svelte.dev/scripts/sync-docs/index.ts | 18 +- apps/svelte.dev/scripts/sync-docs/utils.ts | 11 + apps/svelte.dev/src/lib/server/content.ts | 47 +- .../site-kit/src/lib/markdown/renderer.ts | 2 +- .../site-kit/src/lib/server/content/index.ts | 22 +- 42 files changed, 10642 insertions(+), 3479 deletions(-) create mode 100644 apps/svelte.dev/includes/kit/$app/environment/index.md create mode 100644 apps/svelte.dev/includes/kit/$app/forms/index.md create mode 100644 apps/svelte.dev/includes/kit/$app/navigation/index.md create mode 100644 apps/svelte.dev/includes/kit/$app/paths/index.md create mode 100644 apps/svelte.dev/includes/kit/$app/server/index.md create mode 100644 apps/svelte.dev/includes/kit/$app/stores/index.md create mode 100644 apps/svelte.dev/includes/kit/$env/dynamic/private/index.md create mode 100644 apps/svelte.dev/includes/kit/$env/dynamic/public/index.md create mode 100644 apps/svelte.dev/includes/kit/$env/static/private/index.md create mode 100644 apps/svelte.dev/includes/kit/$env/static/public/index.md create mode 100644 apps/svelte.dev/includes/kit/$lib/index.md create mode 100644 apps/svelte.dev/includes/kit/$service-worker/index.md create mode 100644 apps/svelte.dev/includes/kit/@sveltejs/kit/hooks/index.md create mode 100644 apps/svelte.dev/includes/kit/@sveltejs/kit/index.md create mode 100644 apps/svelte.dev/includes/kit/@sveltejs/kit/node/index.md create mode 100644 apps/svelte.dev/includes/kit/@sveltejs/kit/node/polyfills/index.md create mode 100644 apps/svelte.dev/includes/kit/@sveltejs/kit/vite/index.md create mode 100644 apps/svelte.dev/includes/kit/App/index.md create mode 100644 apps/svelte.dev/includes/kit/Private types/index.md create mode 100644 apps/svelte.dev/includes/kit/__configuration/index.md create mode 100644 apps/svelte.dev/includes/svelte/$derived/index.md create mode 100644 apps/svelte.dev/includes/svelte/$effect/index.md create mode 100644 apps/svelte.dev/includes/svelte/$state/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/action/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/animate/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/compiler/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/easing/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/events/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/legacy/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/motion/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/reactivity/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/server/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/store/index.md create mode 100644 apps/svelte.dev/includes/svelte/svelte/transition/index.md diff --git a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md index 3c7d7bb230..e89510f253 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md @@ -2,3433 +2,4 @@ title: @sveltejs/kit --- - - -```js -// @noErrors -import { - VERSION, - error, - fail, - isHttpError, - isRedirect, - json, - redirect, - text -} from '@sveltejs/kit'; -``` - -## VERSION - - - -
- -```ts -// @noErrors -const VERSION: string; -``` - -
- -## error - -Throws an error with a HTTP status code and an optional message. -When called during request handling, this will cause SvelteKit to -return an error response without invoking `handleError`. -Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it. - -
- -```ts -// @noErrors -function error(status: number, body: App.Error): never; -``` - -
- -## error - -Throws an error with a HTTP status code and an optional message. -When called during request handling, this will cause SvelteKit to -return an error response without invoking `handleError`. -Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it. - -
- -```ts -// @noErrors -function error( - status: number, - body?: { - message: string; - } extends App.Error - ? App.Error | string | undefined - : never -): never; -``` - -
- -## fail - -Create an `ActionFailure` object. - -
- -```ts -// @noErrors -function fail(status: number): ActionFailure; -``` - -
- -## fail - -Create an `ActionFailure` object. - -
- -```ts -// @noErrors -function fail< - T extends Record | undefined = undefined ->(status: number, data: T): ActionFailure; -``` - -
- -## isHttpError - -Checks whether this is an error thrown by `error`. - -
- -```ts -// @noErrors -function isHttpError( - e: unknown, - status?: T | undefined -): e is HttpError_1 & { - status: T extends undefined ? never : T; -}; -``` - -
- -## isRedirect - -Checks whether this is a redirect thrown by `redirect`. - -
- -```ts -// @noErrors -function isRedirect(e: unknown): e is Redirect_1; -``` - -
- -## json - -Create a JSON `Response` object from the supplied data. - -
- -```ts -// @noErrors -function json( - data: any, - init?: ResponseInit | undefined -): Response; -``` - -
- -## redirect - -Redirect a request. When called during request handling, SvelteKit will return a redirect response. -Make sure you're not catching the thrown redirect, which would prevent SvelteKit from handling it. - -
- -```ts -// @noErrors -function redirect( - status: - | 300 - | 301 - | 302 - | 303 - | 304 - | 305 - | 306 - | 307 - | 308 - | ({} & number), - location: string | URL -): never; -``` - -
- -## text - -Create a `Response` object from the supplied body. - -
- -```ts -// @noErrors -function text( - body: string, - init?: ResponseInit | undefined -): Response; -``` - -
- -## Action - -Shape of a form action method that is part of `export const actions = {..}` in `+page.server.js`. -See [form actions](https://kit.svelte.dev/docs/form-actions) for more information. - -
- -```dts -type Action< - Params extends Partial> = Partial< - Record - >, - OutputData extends Record | void = Record< - string, - any - > | void, - RouteId extends string | null = string | null -> = ( - event: RequestEvent -) => MaybePromise; -``` - - -
- -## ActionFailure - -
- -```dts -interface ActionFailure< - T extends Record | undefined = undefined -> {/*…*/} -``` - -
- -```dts -status: number; -``` - -
-
- -
- -```dts -data: T; -``` - -
-
- -
- -```dts -[uniqueSymbol]: true; -``` - -
-
-
- -## ActionResult - -When calling a form action via fetch, the response will be one of these shapes. -```svelte -
{ - return ({ result }) => { - // result is of type ActionResult - }; -}} -``` - -
- -```dts -type ActionResult< - Success extends - | Record - | undefined = Record, - Failure extends - | Record - | undefined = Record -> = - | { type: 'success'; status: number; data?: Success } - | { type: 'failure'; status: number; data?: Failure } - | { type: 'redirect'; status: number; location: string } - | { type: 'error'; status?: number; error: any }; -``` - - -
- -## Actions - -Shape of the `export const actions = {..}` object in `+page.server.js`. -See [form actions](https://kit.svelte.dev/docs/form-actions) for more information. - -
- -```dts -type Actions< - Params extends Partial> = Partial< - Record - >, - OutputData extends Record | void = Record< - string, - any - > | void, - RouteId extends string | null = string | null -> = Record>; -``` - - -
- -## Adapter - -[Adapters](https://kit.svelte.dev/docs/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. - -
- -```dts -interface Adapter {/*…*/} -``` - -
- -```dts -name: string; -``` - -
- -The name of the adapter, using for logging. Will typically correspond to the package name. - -
-
- -
- -```dts -adapt(builder: Builder): MaybePromise; -``` - -
- -
- -- `builder` An object provided by SvelteKit that contains methods for adapting the app - -
- -This function is called after SvelteKit has built your app. - -
-
- -
- -```dts -supports?: {/*…*/} -``` - -
- -Checks called during dev and build to determine whether specific features will work in production with this adapter - -
- -```dts -read?: (details: { config: any; route: { id: string } }) => boolean; -``` - -
- -
- -- `config` The merged route config - -
- -Test support for `read` from `$app/server` - -
-
- -
-
- -
- -```dts -emulate?(): MaybePromise; -``` - -
- -Creates an `Emulator`, which allows the adapter to influence the environment -during dev, build and prerendering - -
-
-
- -## AfterNavigate - -The argument passed to [`afterNavigate`](/docs/kit/reference/$app-navigation#afternavigate) callbacks. - -
- -```dts -interface AfterNavigate extends Omit {/*…*/} -``` - -
- -```dts -type: Exclude; -``` - -
- -The type of navigation: -- `enter`: The app has hydrated -- `form`: The user submitted a `` -- `link`: Navigation was triggered by a link click -- `goto`: Navigation was triggered by a `goto(...)` call or a redirect -- `popstate`: Navigation was triggered by back/forward navigation - -
-
- -
- -```dts -willUnload: false; -``` - -
- -Since `afterNavigate` callbacks are called after a navigation completes, they will never be called with a navigation that unloads the page. - -
-
-
- -## AwaitedActions - -
- -```dts -type AwaitedActions< - T extends Record any> -> = OptionalUnion< - { - [Key in keyof T]: UnpackValidationError< - Awaited> - >; - }[keyof T] ->; -``` - - -
- -## BeforeNavigate - -The argument passed to [`beforeNavigate`](/docs/kit/reference/$app-navigation#beforenavigate) callbacks. - -
- -```dts -interface BeforeNavigate extends Navigation {/*…*/} -``` - -
- -```dts -cancel(): void; -``` - -
- -Call this to prevent the navigation from starting. - -
-
-
- -## Builder - -This object is passed to the `adapt` function of adapters. -It contains various methods and properties that are useful for adapting the app. - -
- -```dts -interface Builder {/*…*/} -``` - -
- -```dts -log: Logger; -``` - -
- -Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`. - -
-
- -
- -```dts -rimraf(dir: string): void; -``` - -
- -Remove `dir` and all its contents. - -
-
- -
- -```dts -mkdirp(dir: string): void; -``` - -
- -Create `dir` and any required parent directories. - -
-
- -
- -```dts -config: ValidatedConfig; -``` - -
- -The fully resolved `svelte.config.js`. - -
-
- -
- -```dts -prerendered: Prerendered; -``` - -
- -Information about prerendered pages and assets, if any. - -
-
- -
- -```dts -routes: RouteDefinition[]; -``` - -
- -An array of all routes (including prerendered) - -
-
- -
- -```dts -createEntries(fn: (route: RouteDefinition) => AdapterEntry): Promise; -``` - -
- -
- -- `fn` A function that groups a set of routes into an entry point -- deprecated Use `builder.routes` instead - -
- -Create separate functions that map to one or more routes of your app. - -
-
- -
- -```dts -findServerAssets(routes: RouteDefinition[]): string[]; -``` - -
- -Find all the assets imported by server files belonging to `routes` - -
-
- -
- -```dts -generateFallback(dest: string): Promise; -``` - -
- -Generate a fallback page for a static webserver to use when no route is matched. Useful for single-page apps. - -
-
- -
- -```dts -generateEnvModule(): void; -``` - -
- -Generate a module exposing build-time environment variables as `$env/dynamic/public`. - -
-
- -
- -```dts -generateManifest(opts: { relativePath: string; routes?: RouteDefinition[] }): string; -``` - -
- -
- -- `opts` a relative path to the base directory of the app and optionally in which format (esm or cjs) the manifest should be generated - -
- -Generate a server-side manifest to initialise the SvelteKit [server](/docs/kit/reference/types#public-types-server) with. - -
-
- -
- -```dts -getBuildDirectory(name: string): string; -``` - -
- -
- -- `name` path to the file, relative to the build directory - -
- -Resolve a path to the `name` directory inside `outDir`, e.g. `/path/to/.svelte-kit/my-adapter`. - -
-
- -
- -```dts -getClientDirectory(): string; -``` - -
- -Get the fully resolved path to the directory containing client-side assets, including the contents of your `static` directory. - -
-
- -
- -```dts -getServerDirectory(): string; -``` - -
- -Get the fully resolved path to the directory containing server-side code. - -
-
- -
- -```dts -getAppPath(): string; -``` - -
- -Get the application path including any configured `base` path, e.g. `my-base-path/_app`. - -
-
- -
- -```dts -writeClient(dest: string): string[]; -``` - -
- -
- -- `dest` the destination folder -- returns an array of files written to `dest` - -
- -Write client assets to `dest`. - -
-
- -
- -```dts -writePrerendered(dest: string): string[]; -``` - -
- -
- -- `dest` the destination folder -- returns an array of files written to `dest` - -
- -Write prerendered files to `dest`. - -
-
- -
- -```dts -writeServer(dest: string): string[]; -``` - -
- -
- -- `dest` the destination folder -- returns an array of files written to `dest` - -
- -Write server-side code to `dest`. - -
-
- -
- -```dts -copy( - from: string, - to: string, - opts?: { - filter?(basename: string): boolean; - replace?: Record; - } -): string[]; -``` - -
- -
- -- `from` the source file or directory -- `to` the destination file or directory -- `opts.filter` a function to determine whether a file or directory should be copied -- `opts.replace` a map of strings to replace -- returns an array of files that were copied - -
- -Copy a file or directory. - -
-
- -
- -```dts -compress(directory: string): Promise; -``` - -
- -
- -- `directory` The directory containing the files to be compressed - -
- -Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals. - -
-
-
- -## Config - -See the [configuration reference](/docs/kit/configuration) for details. - -## Cookies - -
- -```dts -interface Cookies {/*…*/} -``` - -
- -```dts -get(name: string, opts?: import('cookie').CookieParseOptions): string | undefined; -``` - -
- -
- -- `name` the name of the cookie -- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options) - -
- -Gets a cookie that was previously set with `cookies.set`, or from the request headers. - -
-
- -
- -```dts -getAll(opts?: import('cookie').CookieParseOptions): Array<{ name: string; value: string }>; -``` - -
- -
- -- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options) - -
- -Gets all cookies that were previously set with `cookies.set`, or from the request headers. - -
-
- -
- -```dts -set( - name: string, - value: string, - opts: import('cookie').CookieSerializeOptions & { path: string } -): void; -``` - -
- -
- -- `name` the name of the cookie -- `value` the cookie value -- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) - -
- -Sets a cookie. This will add a `set-cookie` header to the response, but also make the cookie available via `cookies.get` or `cookies.getAll` during the current request. - -The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`. - -You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children - -
-
- -
- -```dts -delete(name: string, opts: import('cookie').CookieSerializeOptions & { path: string }): void; -``` - -
- -
- -- `name` the name of the cookie -- `opts` the options, passed directly to `cookie.serialize`. The `path` must match the path of the cookie you want to delete. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) - -
- -Deletes a cookie by setting its value to an empty string and setting the expiry date in the past. - -You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children - -
-
- -
- -```dts -serialize( - name: string, - value: string, - opts: import('cookie').CookieSerializeOptions & { path: string } -): string; -``` - -
- -
- -- `name` the name of the cookie -- `value` the cookie value -- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) - -
- -Serialize a cookie name-value pair into a `Set-Cookie` header string, but don't apply it to the response. - -The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`. - -You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children - -
-
-
- -## Emulator - -A collection of functions that influence the environment during dev, build and prerendering - -
- -```dts -interface Emulator {/*…*/} -``` - -
- -```dts -platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise; -``` - -
- -A function that is called with the current route `config` and `prerender` option -and returns an `App.Platform` object - -
-
-
- -## Handle - -The [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) hook runs every time the SvelteKit server receives a [request](https://kit.svelte.dev/docs/web-standards#fetch-apis-request) and -determines the [response](https://kit.svelte.dev/docs/web-standards#fetch-apis-response). -It receives an `event` object representing the request and a function called `resolve`, which renders the route and generates a `Response`. -This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example). - -
- -```dts -type Handle = (input: { - event: RequestEvent; - resolve( - event: RequestEvent, - opts?: ResolveOptions - ): MaybePromise; -}) => MaybePromise; -``` - - -
- -## HandleClientError - -The client-side [`handleError`](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror) hook runs when an unexpected error is thrown while navigating. - -If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event. -Make sure that this function _never_ throws an error. - -
- -```dts -type HandleClientError = (input: { - error: unknown; - event: NavigationEvent; - status: number; - message: string; -}) => MaybePromise; -``` - - -
- -## HandleFetch - -The [`handleFetch`](https://kit.svelte.dev/docs/hooks#server-hooks-handlefetch) hook allows you to modify (or replace) a `fetch` request that happens inside a `load` function that runs on the server (or during pre-rendering) - -
- -```dts -type HandleFetch = (input: { - event: RequestEvent; - request: Request; - fetch: typeof fetch; -}) => MaybePromise; -``` - - -
- -## HandleServerError - -The server-side [`handleError`](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror) hook runs when an unexpected error is thrown while responding to a request. - -If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event. -Make sure that this function _never_ throws an error. - -
- -```dts -type HandleServerError = (input: { - error: unknown; - event: RequestEvent; - status: number; - message: string; -}) => MaybePromise; -``` - - -
- -## HttpError - -The object returned by the [`error`](/docs/kit/reference/@sveltejs-kit#error) function. - -
- -```dts -interface HttpError {/*…*/} -``` - -
- -```dts -status: number; -``` - -
- -The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), in the range 400-599. - -
-
- -
- -```dts -body: App.Error; -``` - -
- -The content of the error. - -
-
-
- -## KitConfig - -See the [configuration reference](/docs/kit/configuration) for details. - -## LessThan - -
- -```dts -type LessThan< - TNumber extends number, - TArray extends any[] = [] -> = TNumber extends TArray['length'] - ? TArray[number] - : LessThan; -``` - - -
- -## Load - -The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) -rather than using `Load` directly. - -
- -```dts -type Load< - Params extends Partial> = Partial< - Record - >, - InputData extends Record | null = Record< - string, - any - > | null, - ParentData extends Record = Record< - string, - any - >, - OutputData extends Record< - string, - unknown - > | void = Record | void, - RouteId extends string | null = string | null -> = ( - event: LoadEvent -) => MaybePromise; -``` - - -
- -## LoadEvent - -The generic form of `PageLoadEvent` and `LayoutLoadEvent`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) -rather than using `LoadEvent` directly. - -
- -```dts -interface LoadEvent< - Params extends Partial> = Partial< - Record - >, - Data extends Record | null = Record< - string, - any - > | null, - ParentData extends Record = Record< - string, - any - >, - RouteId extends string | null = string | null -> extends NavigationEvent {/*…*/} -``` - -
- -```dts -fetch: typeof fetch; -``` - -
- -`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 by hooking into the `text` and `json` methods of the `Response` object. 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. - -You can learn more about making credentialed requests with cookies [here](https://kit.svelte.dev/docs/load#cookies) - -
-
- -
- -```dts -data: Data; -``` - -
- -Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any. - -
-
- -
- -```dts -setHeaders(headers: Record): void; -``` - -
- -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 -// @errors: 7031 -/// 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`](/docs/kit/reference/types#public-types-cookies) API in a server-only `load` function instead. - -`setHeaders` has no effect when a `load` function runs in the browser. - -
-
- -
- -```dts -parent(): Promise; -``` - -
- -`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. - -
-
- -
- -```dts -depends(...deps: Array<`${string}:${string}`>): void; -``` - -
- -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/kit/reference/$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 -// @errors: 7031 -/// 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 - - -

{data.count}

- -``` - -

-
- -
- -```dts -untrack(fn: () => T): T; -``` - -
- -Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example: - -```js -// @errors: 7031 -/// file: src/routes/+page.server.js -export async function load({ untrack, url }) { - // Untrack url.pathname so that path changes don't trigger a rerun - if (untrack(() => url.pathname === '/')) { - return { message: 'Welcome!' }; - } -} -``` - -
-
-
- -## LoadProperties - -
- -```dts -type LoadProperties< - input extends Record | void -> = input extends void - ? undefined // needs to be undefined, because void will break intellisense - : input extends Record - ? input - : unknown; -``` - - -
- -## Navigation - -
- -```dts -interface Navigation {/*…*/} -``` - -
- -```dts -from: NavigationTarget | null; -``` - -
- -Where navigation was triggered from - -
-
- -
- -```dts -to: NavigationTarget | null; -``` - -
- -Where navigation is going to/has gone to - -
-
- -
- -```dts -type: Exclude; -``` - -
- -The type of navigation: -- `form`: The user submitted a `` -- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring -- `link`: Navigation was triggered by a link click -- `goto`: Navigation was triggered by a `goto(...)` call or a redirect -- `popstate`: Navigation was triggered by back/forward navigation - -
-
- -
- -```dts -willUnload: boolean; -``` - -
- -Whether or not the navigation will result in the page being unloaded (i.e. not a client-side navigation) - -
-
- -
- -```dts -delta?: number; -``` - -
- -In case of a history back/forward navigation, the number of steps to go back/forward - -
-
- -
- -```dts -complete: Promise; -``` - -
- -A promise that resolves once the navigation is complete, and rejects if the navigation -fails or is aborted. In the case of a `willUnload` navigation, the promise will never resolve - -
-
-
- -## NavigationEvent - -
- -```dts -interface NavigationEvent< - Params extends Partial> = Partial< - Record - >, - RouteId extends string | null = string | null -> {/*…*/} -``` - -
- -```dts -params: Params; -``` - -
- -The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object - -
-
- -
- -```dts -route: {/*…*/} -``` - -
- -Info about the current route - -
- -```dts -id: RouteId; -``` - -
- -The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` - -
-
- -
-
- -
- -```dts -url: URL; -``` - -
- -The URL of the current page - -
-
-
- -## NavigationTarget - -Information about the target of a specific navigation. - -
- -```dts -interface NavigationTarget {/*…*/} -``` - -
- -```dts -params: Record | null; -``` - -
- -Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object. -Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route). - -
-
- -
- -```dts -route: { id: string | null }; -``` - -
- -Info about the target route - -
-
- -
- -```dts -url: URL; -``` - -
- -The URL that is navigated to - -
-
-
- -## NavigationType - -- `enter`: The app has hydrated -- `form`: The user submitted a `` with a GET method -- `leave`: The user is leaving the app by closing the tab or using the back/forward buttons to go to a different document -- `link`: Navigation was triggered by a link click -- `goto`: Navigation was triggered by a `goto(...)` call or a redirect -- `popstate`: Navigation was triggered by back/forward navigation - -
- -```dts -type NavigationType = - | 'enter' - | 'form' - | 'leave' - | 'link' - | 'goto' - | 'popstate'; -``` - - -
- -## NumericRange - -
- -```dts -type NumericRange< - TStart extends number, - TEnd extends number -> = Exclude, LessThan>; -``` - - -
- -## OnNavigate - -The argument passed to [`onNavigate`](/docs/kit/reference/$app-navigation#onnavigate) callbacks. - -
- -```dts -interface OnNavigate extends Navigation {/*…*/} -``` - -
- -```dts -type: Exclude; -``` - -
- -The type of navigation: -- `form`: The user submitted a `` -- `link`: Navigation was triggered by a link click -- `goto`: Navigation was triggered by a `goto(...)` call or a redirect -- `popstate`: Navigation was triggered by back/forward navigation - -
-
- -
- -```dts -willUnload: false; -``` - -
- -Since `onNavigate` callbacks are called immediately before a client-side navigation, they will never be called with a navigation that unloads the page. - -
-
-
- -## Page - -The shape of the `$page` store - -
- -```dts -interface Page< - Params extends Record = Record< - string, - string - >, - RouteId extends string | null = string | null -> {/*…*/} -``` - -
- -```dts -url: URL; -``` - -
- -The URL of the current page - -
-
- -
- -```dts -params: Params; -``` - -
- -The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object - -
-
- -
- -```dts -route: {/*…*/} -``` - -
- -Info about the current route - -
- -```dts -id: RouteId; -``` - -
- -The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` - -
-
- -
-
- -
- -```dts -status: number; -``` - -
- -Http status code of the current page - -
-
- -
- -```dts -error: App.Error | null; -``` - -
- -The error object of the current page, if any. Filled from the `handleError` hooks. - -
-
- -
- -```dts -data: App.PageData & Record; -``` - -
- -The merged result of all data from all `load` functions on the current page. You can type a common denominator through `App.PageData`. - -
-
- -
- -```dts -state: App.PageState; -``` - -
- -The page state, which can be manipulated using the [`pushState`](/docs/kit/reference/$app-navigation#pushstate) and [`replaceState`](/docs/kit/reference/$app-navigation#replacestate) functions from `$app/navigation`. - -
-
- -
- -```dts -form: any; -``` - -
- -Filled only after a form submission. See [form actions](https://kit.svelte.dev/docs/form-actions) for more info. - -
-
-
- -## ParamMatcher - -The shape of a param matcher. See [matching](https://kit.svelte.dev/docs/advanced-routing#matching) for more info. - -
- -```dts -type ParamMatcher = (param: string) => boolean; -``` - - -
- -## PrerenderOption - -
- -```dts -type PrerenderOption = boolean | 'auto'; -``` - - -
- -## Redirect - -The object returned by the [`redirect`](/docs/kit/reference/@sveltejs-kit#redirect) function - -
- -```dts -interface Redirect {/*…*/} -``` - -
- -```dts -status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308; -``` - -
- -The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages), in the range 300-308. - -
-
- -
- -```dts -location: string; -``` - -
- -The location to redirect to. - -
-
-
- -## RequestEvent - -
- -```dts -interface RequestEvent< - Params extends Partial> = Partial< - Record - >, - RouteId extends string | null = string | null -> {/*…*/} -``` - -
- -```dts -cookies: Cookies; -``` - -
- -Get or set cookies related to the current request - -
-
- -
- -```dts -fetch: typeof fetch; -``` - -
- -`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 by hooking into the `text` and `json` methods of the `Response` object. 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. - -You can learn more about making credentialed requests with cookies [here](https://kit.svelte.dev/docs/load#cookies) - -
-
- -
- -```dts -getClientAddress(): string; -``` - -
- -The client's IP address, set by the adapter. - -
-
- -
- -```dts -locals: App.Locals; -``` - -
- -Contains custom data that was added to the request within the [`handle hook`](https://kit.svelte.dev/docs/hooks#server-hooks-handle). - -
-
- -
- -```dts -params: Params; -``` - -
- -The parameters of the current route - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object - -
-
- -
- -```dts -platform: Readonly | undefined; -``` - -
- -Additional data made available through the adapter. - -
-
- -
- -```dts -request: Request; -``` - -
- -The original request object - -
-
- -
- -```dts -route: {/*…*/} -``` - -
- -Info about the current route - -
- -```dts -id: RouteId; -``` - -
- -The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` - -
-
- -
-
- -
- -```dts -setHeaders(headers: Record): void; -``` - -
- -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 -// @errors: 7031 -/// 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`](/docs/kit/reference/types#public-types-cookies) API instead. - -
-
- -
- -```dts -url: URL; -``` - -
- -The requested URL. - -
-
- -
- -```dts -isDataRequest: boolean; -``` - -
- -`true` if the request comes from the client asking for `+page/layout.server.js` data. The `url` property will be stripped of the internal information -related to the data request in this case. Use this property instead if the distinction is important to you. - -
-
- -
- -```dts -isSubRequest: boolean; -``` - -
- -`true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server. - -
-
-
- -## RequestHandler - -A `(event: RequestEvent) => Response` function exported from a `+server.js` file that corresponds to an HTTP verb (`GET`, `PUT`, `PATCH`, etc) and handles requests with that method. - -It receives `Params` as the first generic argument, which you can skip by using [generated types](/docs/kit/reference/types#generated-types) instead. - -
- -```dts -type RequestHandler< - Params extends Partial> = Partial< - Record - >, - RouteId extends string | null = string | null -> = ( - event: RequestEvent -) => MaybePromise; -``` - - -
- -## Reroute - -The [`reroute`](https://kit.svelte.dev/docs/hooks#universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render. - -
- -```dts -type Reroute = (event: { url: URL }) => void | string; -``` - - -
- -## ResolveOptions - -
- -```dts -interface ResolveOptions {/*…*/} -``` - -
- -```dts -transformPageChunk?(input: { html: string; done: boolean }): MaybePromise; -``` - -
- -
- -- `input` the html chunk and the info if this is the last chunk - -
- -Applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML -(they could include an element's opening tag but not its closing tag, for example) -but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components. - -
-
- -
- -```dts -filterSerializedResponseHeaders?(name: string, value: string): boolean; -``` - -
- -
- -- `name` header name -- `value` header value - -
- -Determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`. -By default, none will be included. - -
-
- -
- -```dts -preload?(input: { type: 'font' | 'css' | 'js' | 'asset'; path: string }): boolean; -``` - -
- -
- -- `input` the type of the file and its path - -
- -Determines what should be added to the `` tag to preload it. -By default, `js` and `css` files will be preloaded. - -
-
-
- -## RouteDefinition - -
- -```dts -interface RouteDefinition {/*…*/} -``` - -
- -```dts -id: string; -``` - -
-
- -
- -```dts -api: { - methods: Array; -}; -``` - -
-
- -
- -```dts -page: { - methods: Array>; -}; -``` - -
-
- -
- -```dts -pattern: RegExp; -``` - -
-
- -
- -```dts -prerender: PrerenderOption; -``` - -
-
- -
- -```dts -segments: RouteSegment[]; -``` - -
-
- -
- -```dts -methods: Array; -``` - -
-
- -
- -```dts -config: Config; -``` - -
-
-
- -## SSRManifest - -
- -```dts -interface SSRManifest {/*…*/} -``` - -
- -```dts -appDir: string; -``` - -
-
- -
- -```dts -appPath: string; -``` - -
-
- -
- -```dts -assets: Set; -``` - -
-
- -
- -```dts -mimeTypes: Record; -``` - -
-
- -
- -```dts -_: {/*…*/} -``` - -
- -private fields - -
- -```dts -client: NonNullable; -``` - -
-
-
- -```dts -nodes: SSRNodeLoader[]; -``` - -
-
-
- -```dts -routes: SSRRoute[]; -``` - -
-
-
- -```dts -matchers(): Promise>; -``` - -
-
-
- -```dts -server_assets: Record; -``` - -
- -A `[file]: size` map of all assets imported by server code - -
-
- -
-
-
- -## Server - -
- -```dts -class Server {/*…*/} -``` - -
- -```dts -constructor(manifest: SSRManifest); -``` - -
-
- -
- -```dts -init(options: ServerInitOptions): Promise; -``` - -
-
- -
- -```dts -respond(request: Request, options: RequestOptions): Promise; -``` - -
-
-
- -## ServerInitOptions - -
- -```dts -interface ServerInitOptions {/*…*/} -``` - -
- -```dts -env: Record; -``` - -
- -A map of environment variables - -
-
- -
- -```dts -read?: (file: string) => ReadableStream; -``` - -
- -A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work - -
-
-
- -## ServerLoad - -The generic form of `PageServerLoad` and `LayoutServerLoad`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) -rather than using `ServerLoad` directly. - -
- -```dts -type ServerLoad< - Params extends Partial> = Partial< - Record - >, - ParentData extends Record = Record< - string, - any - >, - OutputData extends Record | void = Record< - string, - any - > | void, - RouteId extends string | null = string | null -> = ( - event: ServerLoadEvent -) => MaybePromise; -``` - - -
- -## ServerLoadEvent - -
- -```dts -interface ServerLoadEvent< - Params extends Partial> = Partial< - Record - >, - ParentData extends Record = Record< - string, - any - >, - RouteId extends string | null = string | null -> extends RequestEvent {/*…*/} -``` - -
- -```dts -parent(): Promise; -``` - -
- -`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. - -
-
- -
- -```dts -depends(...deps: string[]): void; -``` - -
- -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/kit/reference/$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 -// @errors: 7031 -/// 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 - - -

{data.count}

- -``` - -

-
- -
- -```dts -untrack(fn: () => T): T; -``` - -
- -Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example: - -```js -// @errors: 7031 -/// file: src/routes/+page.js -export async function load({ untrack, url }) { - // Untrack url.pathname so that path changes don't trigger a rerun - if (untrack(() => url.pathname === '/')) { - return { message: 'Welcome!' }; - } -} -``` - -
-
-
- -## Snapshot - -The type of `export const snapshot` exported from a page or layout component. - -
- -```dts -interface Snapshot {/*…*/} -``` - -
- -```dts -capture: () => T; -``` - -
-
- -
- -```dts -restore: (snapshot: T) => void; -``` - -
-
-
- -## SubmitFunction - -
- -```dts -type SubmitFunction< - Success extends - | Record - | undefined = Record, - Failure extends - | Record - | undefined = Record -> = (input: { - action: URL; - formData: FormData; - formElement: HTMLFormElement; - controller: AbortController; - submitter: HTMLElement | null; - cancel(): void; -}) => MaybePromise< - | void - | ((opts: { - formData: FormData; - formElement: HTMLFormElement; - action: URL; - result: ActionResult; - /** - * Call this to get the default behavior of a form submission response. - * @param options Set `reset: false` if you don't want the `` values to be reset after a successful submission. - * @param invalidateAll Set `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission. - */ - update(options?: { - reset?: boolean; - invalidateAll?: boolean; - }): Promise; - }) => void) ->; -``` - - -
- - - -## Private types - -The following are referenced by the public types documented above, but cannot be imported directly: - -## AdapterEntry - -
- -```dts -interface AdapterEntry {/*…*/} -``` - -
- -```dts -id: string; -``` - -
- -A string that uniquely identifies an HTTP service (e.g. serverless function) and is used for deduplication. -For example, `/foo/a-[b]` and `/foo/[c]` are different routes, but would both -be represented in a Netlify _redirects file as `/foo/:param`, so they share an ID - -
-
- -
- -```dts -filter(route: RouteDefinition): boolean; -``` - -
- -A function that compares the candidate route with the current route to determine -if it should be grouped with the current route. - -Use cases: -- Fallback pages: `/foo/[c]` is a fallback for `/foo/a-[b]`, and `/[...catchall]` is a fallback for all routes -- Grouping routes that share a common `config`: `/foo` should be deployed to the edge, `/bar` and `/baz` should be deployed to a serverless function - -
-
- -
- -```dts -complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise; -``` - -
- -A function that is invoked once the entry has been created. This is where you -should write the function to the filesystem and generate redirect manifests. - -
-
-
- -## Csp - -
- -```dts -namespace Csp { - type ActionSource = 'strict-dynamic' | 'report-sample'; - type BaseSource = - | 'self' - | 'unsafe-eval' - | 'unsafe-hashes' - | 'unsafe-inline' - | 'wasm-unsafe-eval' - | 'none'; - type CryptoSource = - `${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`; - type FrameSource = - | HostSource - | SchemeSource - | 'self' - | 'none'; - type HostNameScheme = `${string}.${string}` | 'localhost'; - type HostSource = - `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`; - type HostProtocolSchemes = `${string}://` | ''; - type HttpDelineator = '/' | '?' | '#' | '\\'; - type PortScheme = `:${number}` | '' | ':*'; - type SchemeSource = - | 'http:' - | 'https:' - | 'data:' - | 'mediastream:' - | 'blob:' - | 'filesystem:'; - type Source = - | HostSource - | SchemeSource - | CryptoSource - | BaseSource; - type Sources = Source[]; -} -``` - - -
- -## CspDirectives - -
- -```dts -interface CspDirectives {/*…*/} -``` - -
- -```dts -'child-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'default-src'?: Array; -``` - -
-
- -
- -```dts -'frame-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'worker-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'connect-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'font-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'img-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'manifest-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'media-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'object-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'prefetch-src'?: Csp.Sources; -``` - -
-
- -
- -```dts -'script-src'?: Array; -``` - -
-
- -
- -```dts -'script-src-elem'?: Csp.Sources; -``` - -
-
- -
- -```dts -'script-src-attr'?: Csp.Sources; -``` - -
-
- -
- -```dts -'style-src'?: Array; -``` - -
-
- -
- -```dts -'style-src-elem'?: Csp.Sources; -``` - -
-
- -
- -```dts -'style-src-attr'?: Csp.Sources; -``` - -
-
- -
- -```dts -'base-uri'?: Array; -``` - -
-
- -
- -```dts -sandbox?: Array< -| 'allow-downloads-without-user-activation' -| 'allow-forms' -| 'allow-modals' -| 'allow-orientation-lock' -| 'allow-pointer-lock' -| 'allow-popups' -| 'allow-popups-to-escape-sandbox' -| 'allow-presentation' -| 'allow-same-origin' -| 'allow-scripts' -| 'allow-storage-access-by-user-activation' -| 'allow-top-navigation' -| 'allow-top-navigation-by-user-activation' ->; -``` - -
-
- -
- -```dts -'form-action'?: Array; -``` - -
-
- -
- -```dts -'frame-ancestors'?: Array; -``` - -
-
- -
- -```dts -'navigate-to'?: Array; -``` - -
-
- -
- -```dts -'report-uri'?: string[]; -``` - -
-
- -
- -```dts -'report-to'?: string[]; -``` - -
-
- -
- -```dts -'require-trusted-types-for'?: Array<'script'>; -``` - -
-
- -
- -```dts -'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>; -``` - -
-
- -
- -```dts -'upgrade-insecure-requests'?: boolean; -``` - -
-
- -
- -```dts -'require-sri-for'?: Array<'script' | 'style' | 'script style'>; -``` - -
- -
- -- deprecated - -
- -
-
- -
- -```dts -'block-all-mixed-content'?: boolean; -``` - -
- -
- -- deprecated - -
- -
-
- -
- -```dts -'plugin-types'?: Array<`${string}/${string}` | 'none'>; -``` - -
- -
- -- deprecated - -
- -
-
- -
- -```dts -referrer?: Array< -| 'no-referrer' -| 'no-referrer-when-downgrade' -| 'origin' -| 'origin-when-cross-origin' -| 'same-origin' -| 'strict-origin' -| 'strict-origin-when-cross-origin' -| 'unsafe-url' -| 'none' ->; -``` - -
- -
- -- deprecated - -
- -
-
-
- -## HttpMethod - -
- -```dts -type HttpMethod = - | 'GET' - | 'HEAD' - | 'POST' - | 'PUT' - | 'DELETE' - | 'PATCH' - | 'OPTIONS'; -``` - - -
- -## Logger - -
- -```dts -interface Logger {/*…*/} -``` - -
- -```dts -(msg: string): void; -``` - -
-
- -
- -```dts -success(msg: string): void; -``` - -
-
- -
- -```dts -error(msg: string): void; -``` - -
-
- -
- -```dts -warn(msg: string): void; -``` - -
-
- -
- -```dts -minor(msg: string): void; -``` - -
-
- -
- -```dts -info(msg: string): void; -``` - -
-
-
- -## MaybePromise - -
- -```dts -type MaybePromise = T | Promise; -``` - - -
- -## PrerenderEntryGeneratorMismatchHandler - -
- -```dts -interface PrerenderEntryGeneratorMismatchHandler {/*…*/} -``` - -
- -```dts -(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void; -``` - -
-
-
- -## PrerenderEntryGeneratorMismatchHandlerValue - -
- -```dts -type PrerenderEntryGeneratorMismatchHandlerValue = - | 'fail' - | 'warn' - | 'ignore' - | PrerenderEntryGeneratorMismatchHandler; -``` - - -
- -## PrerenderHttpErrorHandler - -
- -```dts -interface PrerenderHttpErrorHandler {/*…*/} -``` - -
- -```dts -(details: { -status: number; -path: string; -referrer: string | null; -referenceType: 'linked' | 'fetched'; -message: string; -}): void; -``` - -
-
-
- -## PrerenderHttpErrorHandlerValue - -
- -```dts -type PrerenderHttpErrorHandlerValue = - | 'fail' - | 'warn' - | 'ignore' - | PrerenderHttpErrorHandler; -``` - - -
- -## PrerenderMap - -
- -```dts -type PrerenderMap = Map; -``` - - -
- -## PrerenderMissingIdHandler - -
- -```dts -interface PrerenderMissingIdHandler {/*…*/} -``` - -
- -```dts -(details: { path: string; id: string; referrers: string[]; message: string }): void; -``` - -
-
-
- -## PrerenderMissingIdHandlerValue - -
- -```dts -type PrerenderMissingIdHandlerValue = - | 'fail' - | 'warn' - | 'ignore' - | PrerenderMissingIdHandler; -``` - - -
- -## PrerenderOption - -
- -```dts -type PrerenderOption = boolean | 'auto'; -``` - - -
- -## Prerendered - -
- -```dts -interface Prerendered {/*…*/} -``` - -
- -```dts -pages: Map< -string, -{ - /** The location of the .html file relative to the output directory */ - file: string; -} ->; -``` - -
- -A map of `path` to `{ file }` objects, where a path like `/foo` corresponds to `foo.html` and a path like `/bar/` corresponds to `bar/index.html`. - -
-
- -
- -```dts -assets: Map< -string, -{ - /** The MIME type of the asset */ - type: string; -} ->; -``` - -
- -A map of `path` to `{ type }` objects. - -
-
- -
- -```dts -redirects: Map< -string, -{ - status: number; - location: string; -} ->; -``` - -
- -A map of redirects encountered during prerendering. - -
-
- -
- -```dts -paths: string[]; -``` - -
- -An array of prerendered paths (without trailing slashes, regardless of the trailingSlash config) - -
-
-
- -## RequestOptions - -
- -```dts -interface RequestOptions {/*…*/} -``` - -
- -```dts -getClientAddress(): string; -``` - -
-
- -
- -```dts -platform?: App.Platform; -``` - -
-
-
- -## RouteSegment - -
- -```dts -interface RouteSegment {/*…*/} -``` - -
- -```dts -content: string; -``` - -
-
- -
- -```dts -dynamic: boolean; -``` - -
-
- -
- -```dts -rest: boolean; -``` - -
-
-
- -## TrailingSlash - -
- -```dts -type TrailingSlash = 'never' | 'always' | 'ignore'; -``` - - -
- - +@include kit/@sveltejs/kit/index.md diff --git a/apps/svelte.dev/content/docs/kit/98-reference/15-@sveltejs-kit-node-polyfills.md b/apps/svelte.dev/content/docs/kit/98-reference/15-@sveltejs-kit-node-polyfills.md index 37f8d7c715..03b5c648a9 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/15-@sveltejs-kit-node-polyfills.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/15-@sveltejs-kit-node-polyfills.md @@ -2,26 +2,4 @@ title: @sveltejs/kit/node/polyfills --- - - -```js -// @noErrors -import { installPolyfills } from '@sveltejs/kit/node/polyfills'; -``` - -## installPolyfills - -Make various web APIs available as globals: -- `crypto` -- `File` - -
- -```ts -// @noErrors -function installPolyfills(): void; -``` - -
- - +@include kit/@sveltejs/kit/node/polyfills/index.md diff --git a/apps/svelte.dev/includes/kit/$app/environment/index.md b/apps/svelte.dev/includes/kit/$app/environment/index.md new file mode 100644 index 0000000000..52c86666e8 --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/environment/index.md @@ -0,0 +1,59 @@ + + +```js +// @noErrors +import { browser, building, dev, version } from '$app/environment'; +``` + +## browser + +`true` if the app is running in the browser. + +
+ +```ts +// @noErrors +const browser: boolean; +``` + +
+ +## building + +SvelteKit analyses your app during the `build` step by running it. During this process, `building` is `true`. This also applies during prerendering. + +
+ +```ts +// @noErrors +const building: boolean; +``` + +
+ +## dev + +Whether the dev server is running. This is not guaranteed to correspond to `NODE_ENV` or `MODE`. + +
+ +```ts +// @noErrors +const dev: boolean; +``` + +
+ +## version + +The value of `config.kit.version.name`. + +
+ +```ts +// @noErrors +const version: string; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$app/forms/index.md b/apps/svelte.dev/includes/kit/$app/forms/index.md new file mode 100644 index 0000000000..01d571a98a --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/forms/index.md @@ -0,0 +1,102 @@ + + +```js +// @noErrors +import { applyAction, deserialize, enhance } from '$app/forms'; +``` + +## applyAction + +This action updates the `form` property of the current page with the given data and updates `$page.status`. +In case of an error, it redirects to the nearest error page. + +
+ +```ts +// @noErrors +function applyAction< + Success extends Record | undefined, + Failure extends Record | undefined +>( + result: import('@sveltejs/kit').ActionResult< + Success, + Failure + > +): Promise; +``` + +
+ +## deserialize + +Use this function to deserialize the response from a form submission. +Usage: + +```js +// @errors: 7031 +import { deserialize } from '$app/forms'; + +async function handleSubmit(event) { + const response = await fetch('/form?/action', { + method: 'POST', + body: new FormData(event.target) + }); + + const result = deserialize(await response.text()); + // ... +} +``` + +
+ +```ts +// @noErrors +function deserialize< + Success extends Record | undefined, + Failure extends Record | undefined +>( + result: string +): import('@sveltejs/kit').ActionResult; +``` + +
+ +## enhance + +This action enhances a `` element that otherwise would work without JavaScript. + +The `submit` function is called upon submission with the given FormData and the `action` that should be triggered. +If `cancel` is called, the form will not be submitted. +You can use the abort `controller` to cancel the submission in case another one starts. +If a function is returned, that function is called with the response from the server. +If nothing is returned, the fallback will be used. + +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 on the same page as the form +- updates `$page.status` +- resets the `` 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 + +If you provide a custom function with a callback and want to use the default behavior, invoke `update` in your callback. + +
+ +```ts +// @noErrors +function enhance< + Success extends Record | undefined, + Failure extends Record | undefined +>( + form_element: HTMLFormElement, + submit?: import('@sveltejs/kit').SubmitFunction< + Success, + Failure + > +): { + destroy(): void; +}; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$app/navigation/index.md b/apps/svelte.dev/includes/kit/$app/navigation/index.md new file mode 100644 index 0000000000..0b9f1123cd --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/navigation/index.md @@ -0,0 +1,246 @@ + + +```js +// @noErrors +import { + afterNavigate, + beforeNavigate, + disableScrollHandling, + goto, + invalidate, + invalidateAll, + onNavigate, + preloadCode, + preloadData, + pushState, + replaceState +} from '$app/navigation'; +``` + +## afterNavigate + +A lifecycle function that runs the supplied `callback` when the current component mounts, and also whenever we navigate to a new URL. + +`afterNavigate` must be called during a component initialization. It remains active as long as the component is mounted. + +
+ +```ts +// @noErrors +function afterNavigate( + callback: ( + navigation: import('@sveltejs/kit').AfterNavigate + ) => void +): void; +``` + +
+ +## beforeNavigate + +A navigation interceptor that triggers before we navigate to a new URL, whether by clicking a link, calling `goto(...)`, or using the browser back/forward controls. + +Calling `cancel()` will prevent the navigation from completing. If `navigation.type === 'leave'` — meaning the user is navigating away from the app (or closing the tab) — calling `cancel` will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response. + +When a navigation isn't to a SvelteKit-owned route (and therefore controlled by SvelteKit's client-side router), `navigation.to.route.id` will be `null`. + +If the navigation will (if not cancelled) cause the document to unload — in other words `'leave'` navigations and `'link'` navigations where `navigation.to.route === null` — `navigation.willUnload` is `true`. + +`beforeNavigate` must be called during a component initialization. It remains active as long as the component is mounted. + +
+ +```ts +// @noErrors +function beforeNavigate( + callback: ( + navigation: import('@sveltejs/kit').BeforeNavigate + ) => void +): void; +``` + +
+ +## disableScrollHandling + +If called when the page is being updated following a navigation (in `onMount` or `afterNavigate` or an action, for example), this disables SvelteKit's built-in scroll handling. +This is generally discouraged, since it breaks user expectations. + +
+ +```ts +// @noErrors +function disableScrollHandling(): void; +``` + +
+ +## goto + +Returns a Promise that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) to the specified `url`. +For external URLs, use `window.location = url` instead of calling `goto(url)`. + +
+ +```ts +// @noErrors +function goto( + url: string | URL, + opts?: + | { + replaceState?: boolean | undefined; + noScroll?: boolean | undefined; + keepFocus?: boolean | undefined; + invalidateAll?: boolean | undefined; + state?: App.PageState | undefined; + } + | undefined +): Promise; +``` + +
+ +## invalidate + +Causes any `load` functions belonging to the currently active page to re-run if they depend on the `url` in question, via `fetch` or `depends`. Returns a `Promise` that resolves when the page is subsequently updated. + +If the argument is given as a `string` or `URL`, it must resolve to the same URL that was passed to `fetch` or `depends` (including query parameters). +To create a custom identifier, use a string beginning with `[a-z]+:` (e.g. `custom:state`) — this is a valid URL. + +The `function` argument can be used define a custom predicate. It receives the full `URL` and causes `load` to rerun if `true` is returned. +This can be useful if you want to invalidate based on a pattern instead of a exact match. + +```ts +// Example: Match '/path' regardless of the query parameters +import { invalidate } from '$app/navigation'; + +invalidate((url) => url.pathname === '/path'); +``` + +
+ +```ts +// @noErrors +function invalidate( + resource: string | URL | ((url: URL) => boolean) +): Promise; +``` + +
+ +## invalidateAll + +Causes all `load` functions belonging to the currently active page to re-run. Returns a `Promise` that resolves when the page is subsequently updated. + +
+ +```ts +// @noErrors +function invalidateAll(): Promise; +``` + +
+ +## onNavigate + +A lifecycle function that runs the supplied `callback` immediately before we navigate to a new URL except during full-page navigations. + +If you return a `Promise`, SvelteKit will wait for it to resolve before completing the navigation. This allows you to — for example — use `document.startViewTransition`. Avoid promises that are slow to resolve, since navigation will appear stalled to the user. + +If a function (or a `Promise` that resolves to a function) is returned from the callback, it will be called once the DOM has updated. + +`onNavigate` must be called during a component initialization. It remains active as long as the component is mounted. + +
+ +```ts +// @noErrors +function onNavigate( + callback: ( + navigation: import('@sveltejs/kit').OnNavigate + ) => MaybePromise<(() => void) | void> +): void; +``` + +
+ +## preloadCode + +Programmatically imports the code for routes that haven't yet been fetched. +Typically, you might call this to speed up subsequent navigation. + +You can specify routes by any matching pathname such as `/about` (to match `src/routes/about/+page.svelte`) or `/blog/*` (to match `src/routes/blog/[slug]/+page.svelte`). + +Unlike `preloadData`, this won't call `load` functions. +Returns a Promise that resolves when the modules have been imported. + +
+ +```ts +// @noErrors +function preloadCode(pathname: string): Promise; +``` + +
+ +## preloadData + +Programmatically preloads the given page, which means + 1. ensuring that the code for the page is loaded, and + 2. calling the page's load function with the appropriate options. + +This is the same behaviour that SvelteKit triggers when the user taps or mouses over an `` element with `data-sveltekit-preload-data`. +If the next navigation is to `href`, the values returned from load will be used, making navigation instantaneous. +Returns a Promise that resolves with the result of running the new route's `load` functions once the preload is complete. + +
+ +```ts +// @noErrors +function preloadData(href: string): Promise< + | { + type: 'loaded'; + status: number; + data: Record; + } + | { + type: 'redirect'; + location: string; + } +>; +``` + +
+ +## pushState + +Programmatically create a new history entry with the given `$page.state`. To use the current URL, you can pass `''` as the first argument. Used for [shallow routing](https://kit.svelte.dev/docs/shallow-routing). + +
+ +```ts +// @noErrors +function pushState( + url: string | URL, + state: App.PageState +): void; +``` + +
+ +## replaceState + +Programmatically replace the current history entry with the given `$page.state`. To use the current URL, you can pass `''` as the first argument. Used for [shallow routing](https://kit.svelte.dev/docs/shallow-routing). + +
+ +```ts +// @noErrors +function replaceState( + url: string | URL, + state: App.PageState +): void; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$app/paths/index.md b/apps/svelte.dev/includes/kit/$app/paths/index.md new file mode 100644 index 0000000000..e11d213b19 --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/paths/index.md @@ -0,0 +1,68 @@ + + +```js +// @noErrors +import { assets, base, resolveRoute } from '$app/paths'; +``` + +## assets + +An absolute path that matches [`config.kit.paths.assets`](/docs/kit/reference/configuration#paths). + +> If a value for `config.kit.paths.assets` is specified, it will be replaced with `'/_svelte_kit_assets'` during `vite dev` or `vite preview`, since the assets don't yet live at their eventual URL. + +
+ +```ts +// @noErrors +let assets: + | '' + | `https://${string}` + | `http://${string}` + | '/_svelte_kit_assets'; +``` + +
+ +## base + +A string that matches [`config.kit.paths.base`](/docs/kit/reference/configuration#paths). + +Example usage: `Link` + +
+ +```ts +// @noErrors +let base: '' | `/${string}`; +``` + +
+ +## resolveRoute + +Populate a route ID with params to resolve a pathname. + +```js +// @errors: 7031 +resolveRoute( + `/blog/[slug]/[...somethingElse]`, + { + slug: 'hello-world', + somethingElse: 'something/else' + } +); // `/blog/hello-world/something/else` +``` + +
+ +```ts +// @noErrors +function resolveRoute( + id: string, + params: Record +): string; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$app/server/index.md b/apps/svelte.dev/includes/kit/$app/server/index.md new file mode 100644 index 0000000000..431a62352c --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/server/index.md @@ -0,0 +1,29 @@ + + +```js +// @noErrors +import { read } from '$app/server'; +``` + +## read + +Read the contents of an imported asset from the filesystem + +```js +// @errors: 7031 +import { read } from '$app/server'; +import somefile from './somefile.txt'; + +const asset = read(somefile); +const text = await asset.text(); +``` + +
+ +```ts +// @noErrors +function read(asset: string): Response; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$app/stores/index.md b/apps/svelte.dev/includes/kit/$app/stores/index.md new file mode 100644 index 0000000000..9803fa7972 --- /dev/null +++ b/apps/svelte.dev/includes/kit/$app/stores/index.md @@ -0,0 +1,79 @@ + + +```js +// @noErrors +import { getStores, navigating, page, updated } from '$app/stores'; +``` + +## getStores + + + +
+ +```ts +// @noErrors +function getStores(): { + page: typeof page; + + navigating: typeof navigating; + + updated: typeof updated; +}; +``` + +
+ +## navigating + +A readable store. +When navigating starts, its value is a `Navigation` object with `from`, `to`, `type` and (if `type === 'popstate'`) `delta` properties. +When navigating finishes, its value reverts to `null`. + +On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. + +
+ +```ts +// @noErrors +const navigating: import('svelte/store').Readable< + import('@sveltejs/kit').Navigation | null +>; +``` + +
+ +## page + +A readable store whose value contains page data. + +On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. + +
+ +```ts +// @noErrors +const page: import('svelte/store').Readable< + import('@sveltejs/kit').Page +>; +``` + +
+ +## updated + +A readable store whose initial value is `false`. If [`version.pollInterval`](/docs/kit/reference/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update the store value to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling. + +On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time. + +
+ +```ts +// @noErrors +const updated: import('svelte/store').Readable & { + check(): Promise; +}; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/$env/dynamic/private/index.md b/apps/svelte.dev/includes/kit/$env/dynamic/private/index.md new file mode 100644 index 0000000000..b09b2cd57b --- /dev/null +++ b/apps/svelte.dev/includes/kit/$env/dynamic/private/index.md @@ -0,0 +1,14 @@ +This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using [`adapter-node`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](/docs/kit/reference/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/reference/configuration#env) (if configured). + +This module cannot be imported into client-side code. + +Dynamic environment variables cannot be used during prerendering. + +```ts +import { env } from '$env/dynamic/private'; +console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE); +``` + +> In `dev`, `$env/dynamic` always includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter. + + diff --git a/apps/svelte.dev/includes/kit/$env/dynamic/public/index.md b/apps/svelte.dev/includes/kit/$env/dynamic/public/index.md new file mode 100644 index 0000000000..01534a6266 --- /dev/null +++ b/apps/svelte.dev/includes/kit/$env/dynamic/public/index.md @@ -0,0 +1,12 @@ +Similar to [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) (which defaults to `PUBLIC_`), and can therefore safely be exposed to client-side code. + +Note that public dynamic environment variables must all be sent from the server to the client, causing larger network requests — when possible, use `$env/static/public` instead. + +Dynamic environment variables cannot be used during prerendering. + +```ts +import { env } from '$env/dynamic/public'; +console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE); +``` + + diff --git a/apps/svelte.dev/includes/kit/$env/static/private/index.md b/apps/svelte.dev/includes/kit/$env/static/private/index.md new file mode 100644 index 0000000000..fc9aa1b94b --- /dev/null +++ b/apps/svelte.dev/includes/kit/$env/static/private/index.md @@ -0,0 +1,21 @@ +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`](/docs/kit/reference/$env-all#$env-dynamic-private), this module cannot be imported into client-side code. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/reference/configuration#env) (if configured). + +_Unlike_ [`$env/dynamic/private`](/docs/kit/reference/$env-all#$env-dynamic-private), 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'; +``` + +Note that all environment variables referenced in your code should be declared (for example in an `.env` file), even if they don't have a value until the app is deployed: + +``` +MY_FEATURE_FLAG="" +``` + +You can override `.env` values from the command line like so: + +```bash +MY_FEATURE_FLAG="enabled" npm run dev +``` + + diff --git a/apps/svelte.dev/includes/kit/$env/static/public/index.md b/apps/svelte.dev/includes/kit/$env/static/public/index.md new file mode 100644 index 0000000000..477f82f3df --- /dev/null +++ b/apps/svelte.dev/includes/kit/$env/static/public/index.md @@ -0,0 +1,9 @@ +Similar to [`$env/static/private`](/docs/kit/reference/$env-all#$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/reference/configuration#env) (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'; +``` + + diff --git a/apps/svelte.dev/includes/kit/$lib/index.md b/apps/svelte.dev/includes/kit/$lib/index.md new file mode 100644 index 0000000000..696616d26a --- /dev/null +++ b/apps/svelte.dev/includes/kit/$lib/index.md @@ -0,0 +1,7 @@ +This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](/docs/kit/reference/configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense. + +### `$lib/server` + +A subdirectory of `$lib`. SvelteKit will prevent you from importing any modules in `$lib/server` into client-side code. See [server-only modules](/docs/server-only-modules). + + diff --git a/apps/svelte.dev/includes/kit/$service-worker/index.md b/apps/svelte.dev/includes/kit/$service-worker/index.md new file mode 100644 index 0000000000..50fa405d59 --- /dev/null +++ b/apps/svelte.dev/includes/kit/$service-worker/index.md @@ -0,0 +1,77 @@ + + +```js +// @noErrors +import { base, build, files, prerendered, version } from '$service-worker'; +``` + +This module is only available to [service workers](/docs/service-workers). + +## base + +The `base` path of the deployment. Typically this is equivalent to `config.kit.paths.base`, but it is calculated from `location.pathname` meaning that it will continue to work correctly if the site is deployed to a subdirectory. +Note that there is a `base` but no `assets`, since service workers cannot be used if `config.kit.paths.assets` is specified. + +
+ +```ts +// @noErrors +const base: string; +``` + +
+ +## build + +An array of URL strings representing the files generated by Vite, suitable for caching with `cache.addAll(build)`. +During development, this is an empty array. + +
+ +```ts +// @noErrors +const build: string[]; +``` + +
+ +## files + +An array of URL strings representing the files in your static directory, or whatever directory is specified by `config.kit.files.assets`. You can customize which files are included from `static` directory using [`config.kit.serviceWorker.files`](/docs/kit/reference/configuration) + +
+ +```ts +// @noErrors +const files: string[]; +``` + +
+ +## prerendered + +An array of pathnames corresponding to prerendered pages and endpoints. +During development, this is an empty array. + +
+ +```ts +// @noErrors +const prerendered: string[]; +``` + +
+ +## version + +See [`config.kit.version`](/docs/kit/reference/configuration#version). It's useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches. + +
+ +```ts +// @noErrors +const version: string; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/@sveltejs/kit/hooks/index.md b/apps/svelte.dev/includes/kit/@sveltejs/kit/hooks/index.md new file mode 100644 index 0000000000..a7b1ef641f --- /dev/null +++ b/apps/svelte.dev/includes/kit/@sveltejs/kit/hooks/index.md @@ -0,0 +1,85 @@ + + +```js +// @noErrors +import { sequence } from '@sveltejs/kit/hooks'; +``` + +## sequence + +A helper function for sequencing multiple `handle` calls in a middleware-like manner. +The behavior for the `handle` options is as follows: +- `transformPageChunk` is applied in reverse order and merged +- `preload` is applied in forward order, the first option "wins" and no `preload` options after it are called +- `filterSerializedResponseHeaders` behaves the same as `preload` + +```js +// @errors: 7031 +/// file: src/hooks.server.js +import { sequence } from '@sveltejs/kit/hooks'; + +/** @type {import('@sveltejs/kit').Handle} */ +async function first({ event, resolve }) { + console.log('first pre-processing'); + const result = await resolve(event, { + transformPageChunk: ({ html }) => { + // transforms are applied in reverse order + console.log('first transform'); + return html; + }, + preload: () => { + // this one wins as it's the first defined in the chain + console.log('first preload'); + } + }); + console.log('first post-processing'); + return result; +} + +/** @type {import('@sveltejs/kit').Handle} */ +async function second({ event, resolve }) { + console.log('second pre-processing'); + const result = await resolve(event, { + transformPageChunk: ({ html }) => { + console.log('second transform'); + return html; + }, + preload: () => { + console.log('second preload'); + }, + filterSerializedResponseHeaders: () => { + // this one wins as it's the first defined in the chain + console.log('second filterSerializedResponseHeaders'); + } + }); + console.log('second post-processing'); + return result; +} + +export const handle = sequence(first, second); +``` + +The example above would print: + +``` +first pre-processing +first preload +second pre-processing +second filterSerializedResponseHeaders +second transform +first transform +second post-processing +first post-processing +``` + +
+ +```ts +// @noErrors +function sequence( + ...handlers: import('@sveltejs/kit').Handle[] +): import('@sveltejs/kit').Handle; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/@sveltejs/kit/index.md b/apps/svelte.dev/includes/kit/@sveltejs/kit/index.md new file mode 100644 index 0000000000..d651765661 --- /dev/null +++ b/apps/svelte.dev/includes/kit/@sveltejs/kit/index.md @@ -0,0 +1,2605 @@ + + +```js +// @noErrors +import { + VERSION, + error, + fail, + isHttpError, + isRedirect, + json, + redirect, + text +} from '@sveltejs/kit'; +``` + +## VERSION + + + +
+ +```ts +// @noErrors +const VERSION: string; +``` + +
+ +## error + +Throws an error with a HTTP status code and an optional message. +When called during request handling, this will cause SvelteKit to +return an error response without invoking `handleError`. +Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it. + +
+ +```ts +// @noErrors +function error(status: number, body: App.Error): never; +``` + +
+ +## error + +Throws an error with a HTTP status code and an optional message. +When called during request handling, this will cause SvelteKit to +return an error response without invoking `handleError`. +Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it. + +
+ +```ts +// @noErrors +function error( + status: number, + body?: { + message: string; + } extends App.Error + ? App.Error | string | undefined + : never +): never; +``` + +
+ +## fail + +Create an `ActionFailure` object. + +
+ +```ts +// @noErrors +function fail(status: number): ActionFailure; +``` + +
+ +## fail + +Create an `ActionFailure` object. + +
+ +```ts +// @noErrors +function fail< + T extends Record | undefined = undefined +>(status: number, data: T): ActionFailure; +``` + +
+ +## isHttpError + +Checks whether this is an error thrown by `error`. + +
+ +```ts +// @noErrors +function isHttpError( + e: unknown, + status?: T | undefined +): e is HttpError_1 & { + status: T extends undefined ? never : T; +}; +``` + +
+ +## isRedirect + +Checks whether this is a redirect thrown by `redirect`. + +
+ +```ts +// @noErrors +function isRedirect(e: unknown): e is Redirect_1; +``` + +
+ +## json + +Create a JSON `Response` object from the supplied data. + +
+ +```ts +// @noErrors +function json( + data: any, + init?: ResponseInit | undefined +): Response; +``` + +
+ +## redirect + +Redirect a request. When called during request handling, SvelteKit will return a redirect response. +Make sure you're not catching the thrown redirect, which would prevent SvelteKit from handling it. + +
+ +```ts +// @noErrors +function redirect( + status: + | 300 + | 301 + | 302 + | 303 + | 304 + | 305 + | 306 + | 307 + | 308 + | ({} & number), + location: string | URL +): never; +``` + +
+ +## text + +Create a `Response` object from the supplied body. + +
+ +```ts +// @noErrors +function text( + body: string, + init?: ResponseInit | undefined +): Response; +``` + +
+ +## Action + +Shape of a form action method that is part of `export const actions = {..}` in `+page.server.js`. +See [form actions](https://kit.svelte.dev/docs/form-actions) for more information. + +
+ +```dts +type Action< + Params extends Partial> = Partial< + Record + >, + OutputData extends Record | void = Record< + string, + any + > | void, + RouteId extends string | null = string | null +> = ( + event: RequestEvent +) => MaybePromise; +``` + + +
+ +## ActionFailure + +
+ +```dts +interface ActionFailure< + T extends Record | undefined = undefined +> {/*…*/} +``` + +
+ +```dts +status: number; +``` + +
+
+ +
+ +```dts +data: T; +``` + +
+
+ +
+ +```dts +[uniqueSymbol]: true; +``` + +
+
+
+ +## ActionResult + +When calling a form action via fetch, the response will be one of these shapes. +```svelte + { + return ({ result }) => { + // result is of type ActionResult + }; +}} +``` + +
+ +```dts +type ActionResult< + Success extends + | Record + | undefined = Record, + Failure extends + | Record + | undefined = Record +> = + | { type: 'success'; status: number; data?: Success } + | { type: 'failure'; status: number; data?: Failure } + | { type: 'redirect'; status: number; location: string } + | { type: 'error'; status?: number; error: any }; +``` + + +
+ +## Actions + +Shape of the `export const actions = {..}` object in `+page.server.js`. +See [form actions](https://kit.svelte.dev/docs/form-actions) for more information. + +
+ +```dts +type Actions< + Params extends Partial> = Partial< + Record + >, + OutputData extends Record | void = Record< + string, + any + > | void, + RouteId extends string | null = string | null +> = Record>; +``` + + +
+ +## Adapter + +[Adapters](https://kit.svelte.dev/docs/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing. + +
+ +```dts +interface Adapter {/*…*/} +``` + +
+ +```dts +name: string; +``` + +
+ +The name of the adapter, using for logging. Will typically correspond to the package name. + +
+
+ +
+ +```dts +adapt(builder: Builder): MaybePromise; +``` + +
+ +
+ +- `builder` An object provided by SvelteKit that contains methods for adapting the app + +
+ +This function is called after SvelteKit has built your app. + +
+
+ +
+ +```dts +supports?: {/*…*/} +``` + +
+ +Checks called during dev and build to determine whether specific features will work in production with this adapter + +
+ +```dts +read?: (details: { config: any; route: { id: string } }) => boolean; +``` + +
+ +
+ +- `config` The merged route config + +
+ +Test support for `read` from `$app/server` + +
+
+ +
+
+ +
+ +```dts +emulate?(): MaybePromise; +``` + +
+ +Creates an `Emulator`, which allows the adapter to influence the environment +during dev, build and prerendering + +
+
+
+ +## AfterNavigate + +The argument passed to [`afterNavigate`](/docs/kit/reference/$app-navigation#afternavigate) callbacks. + +
+ +```dts +interface AfterNavigate extends Omit {/*…*/} +``` + +
+ +```dts +type: Exclude; +``` + +
+ +The type of navigation: +- `enter`: The app has hydrated +- `form`: The user submitted a `` +- `link`: Navigation was triggered by a link click +- `goto`: Navigation was triggered by a `goto(...)` call or a redirect +- `popstate`: Navigation was triggered by back/forward navigation + +
+
+ +
+ +```dts +willUnload: false; +``` + +
+ +Since `afterNavigate` callbacks are called after a navigation completes, they will never be called with a navigation that unloads the page. + +
+
+
+ +## AwaitedActions + +
+ +```dts +type AwaitedActions< + T extends Record any> +> = OptionalUnion< + { + [Key in keyof T]: UnpackValidationError< + Awaited> + >; + }[keyof T] +>; +``` + + +
+ +## BeforeNavigate + +The argument passed to [`beforeNavigate`](/docs/kit/reference/$app-navigation#beforenavigate) callbacks. + +
+ +```dts +interface BeforeNavigate extends Navigation {/*…*/} +``` + +
+ +```dts +cancel(): void; +``` + +
+ +Call this to prevent the navigation from starting. + +
+
+
+ +## Builder + +This object is passed to the `adapt` function of adapters. +It contains various methods and properties that are useful for adapting the app. + +
+ +```dts +interface Builder {/*…*/} +``` + +
+ +```dts +log: Logger; +``` + +
+ +Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`. + +
+
+ +
+ +```dts +rimraf(dir: string): void; +``` + +
+ +Remove `dir` and all its contents. + +
+
+ +
+ +```dts +mkdirp(dir: string): void; +``` + +
+ +Create `dir` and any required parent directories. + +
+
+ +
+ +```dts +config: ValidatedConfig; +``` + +
+ +The fully resolved `svelte.config.js`. + +
+
+ +
+ +```dts +prerendered: Prerendered; +``` + +
+ +Information about prerendered pages and assets, if any. + +
+
+ +
+ +```dts +routes: RouteDefinition[]; +``` + +
+ +An array of all routes (including prerendered) + +
+
+ +
+ +```dts +createEntries(fn: (route: RouteDefinition) => AdapterEntry): Promise; +``` + +
+ +
+ +- `fn` A function that groups a set of routes into an entry point +- deprecated Use `builder.routes` instead + +
+ +Create separate functions that map to one or more routes of your app. + +
+
+ +
+ +```dts +findServerAssets(routes: RouteDefinition[]): string[]; +``` + +
+ +Find all the assets imported by server files belonging to `routes` + +
+
+ +
+ +```dts +generateFallback(dest: string): Promise; +``` + +
+ +Generate a fallback page for a static webserver to use when no route is matched. Useful for single-page apps. + +
+
+ +
+ +```dts +generateEnvModule(): void; +``` + +
+ +Generate a module exposing build-time environment variables as `$env/dynamic/public`. + +
+
+ +
+ +```dts +generateManifest(opts: { relativePath: string; routes?: RouteDefinition[] }): string; +``` + +
+ +
+ +- `opts` a relative path to the base directory of the app and optionally in which format (esm or cjs) the manifest should be generated + +
+ +Generate a server-side manifest to initialise the SvelteKit [server](/docs/kit/reference/types#public-types-server) with. + +
+
+ +
+ +```dts +getBuildDirectory(name: string): string; +``` + +
+ +
+ +- `name` path to the file, relative to the build directory + +
+ +Resolve a path to the `name` directory inside `outDir`, e.g. `/path/to/.svelte-kit/my-adapter`. + +
+
+ +
+ +```dts +getClientDirectory(): string; +``` + +
+ +Get the fully resolved path to the directory containing client-side assets, including the contents of your `static` directory. + +
+
+ +
+ +```dts +getServerDirectory(): string; +``` + +
+ +Get the fully resolved path to the directory containing server-side code. + +
+
+ +
+ +```dts +getAppPath(): string; +``` + +
+ +Get the application path including any configured `base` path, e.g. `my-base-path/_app`. + +
+
+ +
+ +```dts +writeClient(dest: string): string[]; +``` + +
+ +
+ +- `dest` the destination folder +- returns an array of files written to `dest` + +
+ +Write client assets to `dest`. + +
+
+ +
+ +```dts +writePrerendered(dest: string): string[]; +``` + +
+ +
+ +- `dest` the destination folder +- returns an array of files written to `dest` + +
+ +Write prerendered files to `dest`. + +
+
+ +
+ +```dts +writeServer(dest: string): string[]; +``` + +
+ +
+ +- `dest` the destination folder +- returns an array of files written to `dest` + +
+ +Write server-side code to `dest`. + +
+
+ +
+ +```dts +copy( + from: string, + to: string, + opts?: { + filter?(basename: string): boolean; + replace?: Record; + } +): string[]; +``` + +
+ +
+ +- `from` the source file or directory +- `to` the destination file or directory +- `opts.filter` a function to determine whether a file or directory should be copied +- `opts.replace` a map of strings to replace +- returns an array of files that were copied + +
+ +Copy a file or directory. + +
+
+ +
+ +```dts +compress(directory: string): Promise; +``` + +
+ +
+ +- `directory` The directory containing the files to be compressed + +
+ +Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals. + +
+
+
+ +## Config + +See the [configuration reference](/docs/kit/configuration) for details. + +## Cookies + +
+ +```dts +interface Cookies {/*…*/} +``` + +
+ +```dts +get(name: string, opts?: import('cookie').CookieParseOptions): string | undefined; +``` + +
+ +
+ +- `name` the name of the cookie +- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options) + +
+ +Gets a cookie that was previously set with `cookies.set`, or from the request headers. + +
+
+ +
+ +```dts +getAll(opts?: import('cookie').CookieParseOptions): Array<{ name: string; value: string }>; +``` + +
+ +
+ +- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options) + +
+ +Gets all cookies that were previously set with `cookies.set`, or from the request headers. + +
+
+ +
+ +```dts +set( + name: string, + value: string, + opts: import('cookie').CookieSerializeOptions & { path: string } +): void; +``` + +
+ +
+ +- `name` the name of the cookie +- `value` the cookie value +- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) + +
+ +Sets a cookie. This will add a `set-cookie` header to the response, but also make the cookie available via `cookies.get` or `cookies.getAll` during the current request. + +The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`. + +You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children + +
+
+ +
+ +```dts +delete(name: string, opts: import('cookie').CookieSerializeOptions & { path: string }): void; +``` + +
+ +
+ +- `name` the name of the cookie +- `opts` the options, passed directly to `cookie.serialize`. The `path` must match the path of the cookie you want to delete. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) + +
+ +Deletes a cookie by setting its value to an empty string and setting the expiry date in the past. + +You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children + +
+
+ +
+ +```dts +serialize( + name: string, + value: string, + opts: import('cookie').CookieSerializeOptions & { path: string } +): string; +``` + +
+ +
+ +- `name` the name of the cookie +- `value` the cookie value +- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options) + +
+ +Serialize a cookie name-value pair into a `Set-Cookie` header string, but don't apply it to the response. + +The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`. + +You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children + +
+
+
+ +## Emulator + +A collection of functions that influence the environment during dev, build and prerendering + +
+ +```dts +interface Emulator {/*…*/} +``` + +
+ +```dts +platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise; +``` + +
+ +A function that is called with the current route `config` and `prerender` option +and returns an `App.Platform` object + +
+
+
+ +## Handle + +The [`handle`](https://kit.svelte.dev/docs/hooks#server-hooks-handle) hook runs every time the SvelteKit server receives a [request](https://kit.svelte.dev/docs/web-standards#fetch-apis-request) and +determines the [response](https://kit.svelte.dev/docs/web-standards#fetch-apis-response). +It receives an `event` object representing the request and a function called `resolve`, which renders the route and generates a `Response`. +This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example). + +
+ +```dts +type Handle = (input: { + event: RequestEvent; + resolve( + event: RequestEvent, + opts?: ResolveOptions + ): MaybePromise; +}) => MaybePromise; +``` + + +
+ +## HandleClientError + +The client-side [`handleError`](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror) hook runs when an unexpected error is thrown while navigating. + +If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event. +Make sure that this function _never_ throws an error. + +
+ +```dts +type HandleClientError = (input: { + error: unknown; + event: NavigationEvent; + status: number; + message: string; +}) => MaybePromise; +``` + + +
+ +## HandleFetch + +The [`handleFetch`](https://kit.svelte.dev/docs/hooks#server-hooks-handlefetch) hook allows you to modify (or replace) a `fetch` request that happens inside a `load` function that runs on the server (or during pre-rendering) + +
+ +```dts +type HandleFetch = (input: { + event: RequestEvent; + request: Request; + fetch: typeof fetch; +}) => MaybePromise; +``` + + +
+ +## HandleServerError + +The server-side [`handleError`](https://kit.svelte.dev/docs/hooks#shared-hooks-handleerror) hook runs when an unexpected error is thrown while responding to a request. + +If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event. +Make sure that this function _never_ throws an error. + +
+ +```dts +type HandleServerError = (input: { + error: unknown; + event: RequestEvent; + status: number; + message: string; +}) => MaybePromise; +``` + + +
+ +## HttpError + +The object returned by the [`error`](/docs/kit/reference/@sveltejs-kit#error) function. + +
+ +```dts +interface HttpError {/*…*/} +``` + +
+ +```dts +status: number; +``` + +
+ +The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), in the range 400-599. + +
+
+ +
+ +```dts +body: App.Error; +``` + +
+ +The content of the error. + +
+
+
+ +## KitConfig + +See the [configuration reference](/docs/kit/configuration) for details. + +## LessThan + +
+ +```dts +type LessThan< + TNumber extends number, + TArray extends any[] = [] +> = TNumber extends TArray['length'] + ? TArray[number] + : LessThan; +``` + + +
+ +## Load + +The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) +rather than using `Load` directly. + +
+ +```dts +type Load< + Params extends Partial> = Partial< + Record + >, + InputData extends Record | null = Record< + string, + any + > | null, + ParentData extends Record = Record< + string, + any + >, + OutputData extends Record< + string, + unknown + > | void = Record | void, + RouteId extends string | null = string | null +> = ( + event: LoadEvent +) => MaybePromise; +``` + + +
+ +## LoadEvent + +The generic form of `PageLoadEvent` and `LayoutLoadEvent`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) +rather than using `LoadEvent` directly. + +
+ +```dts +interface LoadEvent< + Params extends Partial> = Partial< + Record + >, + Data extends Record | null = Record< + string, + any + > | null, + ParentData extends Record = Record< + string, + any + >, + RouteId extends string | null = string | null +> extends NavigationEvent {/*…*/} +``` + +
+ +```dts +fetch: typeof fetch; +``` + +
+ +`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 by hooking into the `text` and `json` methods of the `Response` object. 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. + +You can learn more about making credentialed requests with cookies [here](https://kit.svelte.dev/docs/load#cookies) + +
+
+ +
+ +```dts +data: Data; +``` + +
+ +Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any. + +
+
+ +
+ +```dts +setHeaders(headers: Record): void; +``` + +
+ +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 +// @errors: 7031 +/// 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`](/docs/kit/reference/types#public-types-cookies) API in a server-only `load` function instead. + +`setHeaders` has no effect when a `load` function runs in the browser. + +
+
+ +
+ +```dts +parent(): Promise; +``` + +
+ +`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. + +
+
+ +
+ +```dts +depends(...deps: Array<`${string}:${string}`>): void; +``` + +
+ +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/kit/reference/$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 +// @errors: 7031 +/// 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 + + +

{data.count}

+ +``` + +

+
+ +
+ +```dts +untrack(fn: () => T): T; +``` + +
+ +Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example: + +```js +// @errors: 7031 +/// file: src/routes/+page.server.js +export async function load({ untrack, url }) { + // Untrack url.pathname so that path changes don't trigger a rerun + if (untrack(() => url.pathname === '/')) { + return { message: 'Welcome!' }; + } +} +``` + +
+
+
+ +## LoadProperties + +
+ +```dts +type LoadProperties< + input extends Record | void +> = input extends void + ? undefined // needs to be undefined, because void will break intellisense + : input extends Record + ? input + : unknown; +``` + + +
+ +## Navigation + +
+ +```dts +interface Navigation {/*…*/} +``` + +
+ +```dts +from: NavigationTarget | null; +``` + +
+ +Where navigation was triggered from + +
+
+ +
+ +```dts +to: NavigationTarget | null; +``` + +
+ +Where navigation is going to/has gone to + +
+
+ +
+ +```dts +type: Exclude; +``` + +
+ +The type of navigation: +- `form`: The user submitted a `` +- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring +- `link`: Navigation was triggered by a link click +- `goto`: Navigation was triggered by a `goto(...)` call or a redirect +- `popstate`: Navigation was triggered by back/forward navigation + +
+
+ +
+ +```dts +willUnload: boolean; +``` + +
+ +Whether or not the navigation will result in the page being unloaded (i.e. not a client-side navigation) + +
+
+ +
+ +```dts +delta?: number; +``` + +
+ +In case of a history back/forward navigation, the number of steps to go back/forward + +
+
+ +
+ +```dts +complete: Promise; +``` + +
+ +A promise that resolves once the navigation is complete, and rejects if the navigation +fails or is aborted. In the case of a `willUnload` navigation, the promise will never resolve + +
+
+
+ +## NavigationEvent + +
+ +```dts +interface NavigationEvent< + Params extends Partial> = Partial< + Record + >, + RouteId extends string | null = string | null +> {/*…*/} +``` + +
+ +```dts +params: Params; +``` + +
+ +The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object + +
+
+ +
+ +```dts +route: {/*…*/} +``` + +
+ +Info about the current route + +
+ +```dts +id: RouteId; +``` + +
+ +The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` + +
+
+ +
+
+ +
+ +```dts +url: URL; +``` + +
+ +The URL of the current page + +
+
+
+ +## NavigationTarget + +Information about the target of a specific navigation. + +
+ +```dts +interface NavigationTarget {/*…*/} +``` + +
+ +```dts +params: Record | null; +``` + +
+ +Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object. +Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route). + +
+
+ +
+ +```dts +route: { id: string | null }; +``` + +
+ +Info about the target route + +
+
+ +
+ +```dts +url: URL; +``` + +
+ +The URL that is navigated to + +
+
+
+ +## NavigationType + +- `enter`: The app has hydrated +- `form`: The user submitted a `` with a GET method +- `leave`: The user is leaving the app by closing the tab or using the back/forward buttons to go to a different document +- `link`: Navigation was triggered by a link click +- `goto`: Navigation was triggered by a `goto(...)` call or a redirect +- `popstate`: Navigation was triggered by back/forward navigation + +
+ +```dts +type NavigationType = + | 'enter' + | 'form' + | 'leave' + | 'link' + | 'goto' + | 'popstate'; +``` + + +
+ +## NumericRange + +
+ +```dts +type NumericRange< + TStart extends number, + TEnd extends number +> = Exclude, LessThan>; +``` + + +
+ +## OnNavigate + +The argument passed to [`onNavigate`](/docs/kit/reference/$app-navigation#onnavigate) callbacks. + +
+ +```dts +interface OnNavigate extends Navigation {/*…*/} +``` + +
+ +```dts +type: Exclude; +``` + +
+ +The type of navigation: +- `form`: The user submitted a `` +- `link`: Navigation was triggered by a link click +- `goto`: Navigation was triggered by a `goto(...)` call or a redirect +- `popstate`: Navigation was triggered by back/forward navigation + +
+
+ +
+ +```dts +willUnload: false; +``` + +
+ +Since `onNavigate` callbacks are called immediately before a client-side navigation, they will never be called with a navigation that unloads the page. + +
+
+
+ +## Page + +The shape of the `$page` store + +
+ +```dts +interface Page< + Params extends Record = Record< + string, + string + >, + RouteId extends string | null = string | null +> {/*…*/} +``` + +
+ +```dts +url: URL; +``` + +
+ +The URL of the current page + +
+
+ +
+ +```dts +params: Params; +``` + +
+ +The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object + +
+
+ +
+ +```dts +route: {/*…*/} +``` + +
+ +Info about the current route + +
+ +```dts +id: RouteId; +``` + +
+ +The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` + +
+
+ +
+
+ +
+ +```dts +status: number; +``` + +
+ +Http status code of the current page + +
+
+ +
+ +```dts +error: App.Error | null; +``` + +
+ +The error object of the current page, if any. Filled from the `handleError` hooks. + +
+
+ +
+ +```dts +data: App.PageData & Record; +``` + +
+ +The merged result of all data from all `load` functions on the current page. You can type a common denominator through `App.PageData`. + +
+
+ +
+ +```dts +state: App.PageState; +``` + +
+ +The page state, which can be manipulated using the [`pushState`](/docs/kit/reference/$app-navigation#pushstate) and [`replaceState`](/docs/kit/reference/$app-navigation#replacestate) functions from `$app/navigation`. + +
+
+ +
+ +```dts +form: any; +``` + +
+ +Filled only after a form submission. See [form actions](https://kit.svelte.dev/docs/form-actions) for more info. + +
+
+
+ +## ParamMatcher + +The shape of a param matcher. See [matching](https://kit.svelte.dev/docs/advanced-routing#matching) for more info. + +
+ +```dts +type ParamMatcher = (param: string) => boolean; +``` + + +
+ +## PrerenderOption + +
+ +```dts +type PrerenderOption = boolean | 'auto'; +``` + + +
+ +## Redirect + +The object returned by the [`redirect`](/docs/kit/reference/@sveltejs-kit#redirect) function + +
+ +```dts +interface Redirect {/*…*/} +``` + +
+ +```dts +status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308; +``` + +
+ +The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages), in the range 300-308. + +
+
+ +
+ +```dts +location: string; +``` + +
+ +The location to redirect to. + +
+
+
+ +## RequestEvent + +
+ +```dts +interface RequestEvent< + Params extends Partial> = Partial< + Record + >, + RouteId extends string | null = string | null +> {/*…*/} +``` + +
+ +```dts +cookies: Cookies; +``` + +
+ +Get or set cookies related to the current request + +
+
+ +
+ +```dts +fetch: typeof fetch; +``` + +
+ +`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 by hooking into the `text` and `json` methods of the `Response` object. 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. + +You can learn more about making credentialed requests with cookies [here](https://kit.svelte.dev/docs/load#cookies) + +
+
+ +
+ +```dts +getClientAddress(): string; +``` + +
+ +The client's IP address, set by the adapter. + +
+
+ +
+ +```dts +locals: App.Locals; +``` + +
+ +Contains custom data that was added to the request within the [`handle hook`](https://kit.svelte.dev/docs/hooks#server-hooks-handle). + +
+
+ +
+ +```dts +params: Params; +``` + +
+ +The parameters of the current route - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object + +
+
+ +
+ +```dts +platform: Readonly | undefined; +``` + +
+ +Additional data made available through the adapter. + +
+
+ +
+ +```dts +request: Request; +``` + +
+ +The original request object + +
+
+ +
+ +```dts +route: {/*…*/} +``` + +
+ +Info about the current route + +
+ +```dts +id: RouteId; +``` + +
+ +The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]` + +
+
+ +
+
+ +
+ +```dts +setHeaders(headers: Record): void; +``` + +
+ +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 +// @errors: 7031 +/// 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`](/docs/kit/reference/types#public-types-cookies) API instead. + +
+
+ +
+ +```dts +url: URL; +``` + +
+ +The requested URL. + +
+
+ +
+ +```dts +isDataRequest: boolean; +``` + +
+ +`true` if the request comes from the client asking for `+page/layout.server.js` data. The `url` property will be stripped of the internal information +related to the data request in this case. Use this property instead if the distinction is important to you. + +
+
+ +
+ +```dts +isSubRequest: boolean; +``` + +
+ +`true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server. + +
+
+
+ +## RequestHandler + +A `(event: RequestEvent) => Response` function exported from a `+server.js` file that corresponds to an HTTP verb (`GET`, `PUT`, `PATCH`, etc) and handles requests with that method. + +It receives `Params` as the first generic argument, which you can skip by using [generated types](/docs/kit/reference/types#generated-types) instead. + +
+ +```dts +type RequestHandler< + Params extends Partial> = Partial< + Record + >, + RouteId extends string | null = string | null +> = ( + event: RequestEvent +) => MaybePromise; +``` + + +
+ +## Reroute + +The [`reroute`](https://kit.svelte.dev/docs/hooks#universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render. + +
+ +```dts +type Reroute = (event: { url: URL }) => void | string; +``` + + +
+ +## ResolveOptions + +
+ +```dts +interface ResolveOptions {/*…*/} +``` + +
+ +```dts +transformPageChunk?(input: { html: string; done: boolean }): MaybePromise; +``` + +
+ +
+ +- `input` the html chunk and the info if this is the last chunk + +
+ +Applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML +(they could include an element's opening tag but not its closing tag, for example) +but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components. + +
+
+ +
+ +```dts +filterSerializedResponseHeaders?(name: string, value: string): boolean; +``` + +
+ +
+ +- `name` header name +- `value` header value + +
+ +Determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`. +By default, none will be included. + +
+
+ +
+ +```dts +preload?(input: { type: 'font' | 'css' | 'js' | 'asset'; path: string }): boolean; +``` + +
+ +
+ +- `input` the type of the file and its path + +
+ +Determines what should be added to the `` tag to preload it. +By default, `js` and `css` files will be preloaded. + +
+
+
+ +## RouteDefinition + +
+ +```dts +interface RouteDefinition {/*…*/} +``` + +
+ +```dts +id: string; +``` + +
+
+ +
+ +```dts +api: { + methods: Array; +}; +``` + +
+
+ +
+ +```dts +page: { + methods: Array>; +}; +``` + +
+
+ +
+ +```dts +pattern: RegExp; +``` + +
+
+ +
+ +```dts +prerender: PrerenderOption; +``` + +
+
+ +
+ +```dts +segments: RouteSegment[]; +``` + +
+
+ +
+ +```dts +methods: Array; +``` + +
+
+ +
+ +```dts +config: Config; +``` + +
+
+
+ +## SSRManifest + +
+ +```dts +interface SSRManifest {/*…*/} +``` + +
+ +```dts +appDir: string; +``` + +
+
+ +
+ +```dts +appPath: string; +``` + +
+
+ +
+ +```dts +assets: Set; +``` + +
+
+ +
+ +```dts +mimeTypes: Record; +``` + +
+
+ +
+ +```dts +_: {/*…*/} +``` + +
+ +private fields + +
+ +```dts +client: NonNullable; +``` + +
+
+
+ +```dts +nodes: SSRNodeLoader[]; +``` + +
+
+
+ +```dts +routes: SSRRoute[]; +``` + +
+
+
+ +```dts +matchers(): Promise>; +``` + +
+
+
+ +```dts +server_assets: Record; +``` + +
+ +A `[file]: size` map of all assets imported by server code + +
+
+ +
+
+
+ +## Server + +
+ +```dts +class Server {/*…*/} +``` + +
+ +```dts +constructor(manifest: SSRManifest); +``` + +
+
+ +
+ +```dts +init(options: ServerInitOptions): Promise; +``` + +
+
+ +
+ +```dts +respond(request: Request, options: RequestOptions): Promise; +``` + +
+
+
+ +## ServerInitOptions + +
+ +```dts +interface ServerInitOptions {/*…*/} +``` + +
+ +```dts +env: Record; +``` + +
+ +A map of environment variables + +
+
+ +
+ +```dts +read?: (file: string) => ReadableStream; +``` + +
+ +A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work + +
+
+
+ +## ServerLoad + +The generic form of `PageServerLoad` and `LayoutServerLoad`. You should import those from `./$types` (see [generated types](/docs/kit/reference/types#generated-types)) +rather than using `ServerLoad` directly. + +
+ +```dts +type ServerLoad< + Params extends Partial> = Partial< + Record + >, + ParentData extends Record = Record< + string, + any + >, + OutputData extends Record | void = Record< + string, + any + > | void, + RouteId extends string | null = string | null +> = ( + event: ServerLoadEvent +) => MaybePromise; +``` + + +
+ +## ServerLoadEvent + +
+ +```dts +interface ServerLoadEvent< + Params extends Partial> = Partial< + Record + >, + ParentData extends Record = Record< + string, + any + >, + RouteId extends string | null = string | null +> extends RequestEvent {/*…*/} +``` + +
+ +```dts +parent(): Promise; +``` + +
+ +`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. + +
+
+ +
+ +```dts +depends(...deps: string[]): void; +``` + +
+ +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/kit/reference/$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 +// @errors: 7031 +/// 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 + + +

{data.count}

+ +``` + +

+
+ +
+ +```dts +untrack(fn: () => T): T; +``` + +
+ +Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example: + +```js +// @errors: 7031 +/// file: src/routes/+page.js +export async function load({ untrack, url }) { + // Untrack url.pathname so that path changes don't trigger a rerun + if (untrack(() => url.pathname === '/')) { + return { message: 'Welcome!' }; + } +} +``` + +
+
+
+ +## Snapshot + +The type of `export const snapshot` exported from a page or layout component. + +
+ +```dts +interface Snapshot {/*…*/} +``` + +
+ +```dts +capture: () => T; +``` + +
+
+ +
+ +```dts +restore: (snapshot: T) => void; +``` + +
+
+
+ +## SubmitFunction + +
+ +```dts +type SubmitFunction< + Success extends + | Record + | undefined = Record, + Failure extends + | Record + | undefined = Record +> = (input: { + action: URL; + formData: FormData; + formElement: HTMLFormElement; + controller: AbortController; + submitter: HTMLElement | null; + cancel(): void; +}) => MaybePromise< + | void + | ((opts: { + formData: FormData; + formElement: HTMLFormElement; + action: URL; + result: ActionResult; + /** + * Call this to get the default behavior of a form submission response. + * @param options Set `reset: false` if you don't want the `` values to be reset after a successful submission. + * @param invalidateAll Set `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission. + */ + update(options?: { + reset?: boolean; + invalidateAll?: boolean; + }): Promise; + }) => void) +>; +``` + + +
+ diff --git a/apps/svelte.dev/includes/kit/@sveltejs/kit/node/index.md b/apps/svelte.dev/includes/kit/@sveltejs/kit/node/index.md new file mode 100644 index 0000000000..acab4f518d --- /dev/null +++ b/apps/svelte.dev/includes/kit/@sveltejs/kit/node/index.md @@ -0,0 +1,61 @@ + + +```js +// @noErrors +import { + createReadableStream, + getRequest, + setResponse +} from '@sveltejs/kit/node'; +``` + +## createReadableStream + +Converts a file on disk to a readable stream + +
+ +```ts +// @noErrors +function createReadableStream(file: string): ReadableStream; +``` + +
+ +## getRequest + + + +
+ +```ts +// @noErrors +function getRequest({ + request, + base, + bodySizeLimit +}: { + request: import('http').IncomingMessage; + base: string; + bodySizeLimit?: number; +}): Promise; +``` + +
+ +## setResponse + + + +
+ +```ts +// @noErrors +function setResponse( + res: import('http').ServerResponse, + response: Response +): Promise; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/@sveltejs/kit/node/polyfills/index.md b/apps/svelte.dev/includes/kit/@sveltejs/kit/node/polyfills/index.md new file mode 100644 index 0000000000..ba5ddba680 --- /dev/null +++ b/apps/svelte.dev/includes/kit/@sveltejs/kit/node/polyfills/index.md @@ -0,0 +1,22 @@ + + +```js +// @noErrors +import { installPolyfills } from '@sveltejs/kit/node/polyfills'; +``` + +## installPolyfills + +Make various web APIs available as globals: +- `crypto` +- `File` + +
+ +```ts +// @noErrors +function installPolyfills(): void; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/@sveltejs/kit/vite/index.md b/apps/svelte.dev/includes/kit/@sveltejs/kit/vite/index.md new file mode 100644 index 0000000000..6d5440175b --- /dev/null +++ b/apps/svelte.dev/includes/kit/@sveltejs/kit/vite/index.md @@ -0,0 +1,20 @@ + + +```js +// @noErrors +import { sveltekit } from '@sveltejs/kit/vite'; +``` + +## sveltekit + +Returns the SvelteKit Vite plugins. + +
+ +```ts +// @noErrors +function sveltekit(): Promise; +``` + +
+ diff --git a/apps/svelte.dev/includes/kit/App/index.md b/apps/svelte.dev/includes/kit/App/index.md new file mode 100644 index 0000000000..6fb5c65f81 --- /dev/null +++ b/apps/svelte.dev/includes/kit/App/index.md @@ -0,0 +1,74 @@ +## Error + +Defines the common shape of expected and unexpected errors. Expected errors are thrown using the `error` function. Unexpected errors are handled by the `handleError` hooks which should return this shape. + +
+ +```dts +interface Error {/*…*/} +``` + +
+ +```dts +message: string; +``` + +
+
+
+ +## Locals + +The interface that defines `event.locals`, which can be accessed in [hooks](https://kit.svelte.dev/docs/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files. + +
+ +```dts +interface Locals {} +``` + + +
+ +## PageData + +Defines the common shape of the [$page.data store](/docs/kit/reference/$app-stores#page) - that is, the data that is shared between all pages. +The `Load` and `ServerLoad` functions in `./$types` will be narrowed accordingly. +Use optional properties for data that is only present on specific pages. Do not add an index signature (`[key: string]: any`). + +
+ +```dts +interface PageData {} +``` + + +
+ +## PageState + +The shape of the `$page.state` object, which can be manipulated using the [`pushState`](/docs/kit/reference/$app-navigation#pushstate) and [`replaceState`](/docs/kit/reference/$app-navigation#replacestate) functions from `$app/navigation`. + +
+ +```dts +interface PageState {} +``` + + +
+ +## Platform + +If your adapter provides [platform-specific context](https://kit.svelte.dev/docs/adapters#platform-specific-context) via `event.platform`, you can specify it here. + +
+ +```dts +interface Platform {} +``` + + +
+ diff --git a/apps/svelte.dev/includes/kit/Private types/index.md b/apps/svelte.dev/includes/kit/Private types/index.md new file mode 100644 index 0000000000..c9c1bc835d --- /dev/null +++ b/apps/svelte.dev/includes/kit/Private types/index.md @@ -0,0 +1,818 @@ +## AdapterEntry + +
+ +```dts +interface AdapterEntry {/*…*/} +``` + +
+ +```dts +id: string; +``` + +
+ +A string that uniquely identifies an HTTP service (e.g. serverless function) and is used for deduplication. +For example, `/foo/a-[b]` and `/foo/[c]` are different routes, but would both +be represented in a Netlify _redirects file as `/foo/:param`, so they share an ID + +
+
+ +
+ +```dts +filter(route: RouteDefinition): boolean; +``` + +
+ +A function that compares the candidate route with the current route to determine +if it should be grouped with the current route. + +Use cases: +- Fallback pages: `/foo/[c]` is a fallback for `/foo/a-[b]`, and `/[...catchall]` is a fallback for all routes +- Grouping routes that share a common `config`: `/foo` should be deployed to the edge, `/bar` and `/baz` should be deployed to a serverless function + +
+
+ +
+ +```dts +complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise; +``` + +
+ +A function that is invoked once the entry has been created. This is where you +should write the function to the filesystem and generate redirect manifests. + +
+
+
+ +## Csp + +
+ +```dts +namespace Csp { + type ActionSource = 'strict-dynamic' | 'report-sample'; + type BaseSource = + | 'self' + | 'unsafe-eval' + | 'unsafe-hashes' + | 'unsafe-inline' + | 'wasm-unsafe-eval' + | 'none'; + type CryptoSource = + `${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`; + type FrameSource = + | HostSource + | SchemeSource + | 'self' + | 'none'; + type HostNameScheme = `${string}.${string}` | 'localhost'; + type HostSource = + `${HostProtocolSchemes}${HostNameScheme}${PortScheme}`; + type HostProtocolSchemes = `${string}://` | ''; + type HttpDelineator = '/' | '?' | '#' | '\\'; + type PortScheme = `:${number}` | '' | ':*'; + type SchemeSource = + | 'http:' + | 'https:' + | 'data:' + | 'mediastream:' + | 'blob:' + | 'filesystem:'; + type Source = + | HostSource + | SchemeSource + | CryptoSource + | BaseSource; + type Sources = Source[]; +} +``` + + +
+ +## CspDirectives + +
+ +```dts +interface CspDirectives {/*…*/} +``` + +
+ +```dts +'child-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'default-src'?: Array; +``` + +
+
+ +
+ +```dts +'frame-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'worker-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'connect-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'font-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'img-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'manifest-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'media-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'object-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'prefetch-src'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'script-src'?: Array; +``` + +
+
+ +
+ +```dts +'script-src-elem'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'script-src-attr'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'style-src'?: Array; +``` + +
+
+ +
+ +```dts +'style-src-elem'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'style-src-attr'?: Csp.Sources; +``` + +
+
+ +
+ +```dts +'base-uri'?: Array; +``` + +
+
+ +
+ +```dts +sandbox?: Array< +| 'allow-downloads-without-user-activation' +| 'allow-forms' +| 'allow-modals' +| 'allow-orientation-lock' +| 'allow-pointer-lock' +| 'allow-popups' +| 'allow-popups-to-escape-sandbox' +| 'allow-presentation' +| 'allow-same-origin' +| 'allow-scripts' +| 'allow-storage-access-by-user-activation' +| 'allow-top-navigation' +| 'allow-top-navigation-by-user-activation' +>; +``` + +
+
+ +
+ +```dts +'form-action'?: Array; +``` + +
+
+ +
+ +```dts +'frame-ancestors'?: Array; +``` + +
+
+ +
+ +```dts +'navigate-to'?: Array; +``` + +
+
+ +
+ +```dts +'report-uri'?: string[]; +``` + +
+
+ +
+ +```dts +'report-to'?: string[]; +``` + +
+
+ +
+ +```dts +'require-trusted-types-for'?: Array<'script'>; +``` + +
+
+ +
+ +```dts +'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>; +``` + +
+
+ +
+ +```dts +'upgrade-insecure-requests'?: boolean; +``` + +
+
+ +
+ +```dts +'require-sri-for'?: Array<'script' | 'style' | 'script style'>; +``` + +
+ +
+ +- deprecated + +
+ +
+
+ +
+ +```dts +'block-all-mixed-content'?: boolean; +``` + +
+ +
+ +- deprecated + +
+ +
+
+ +
+ +```dts +'plugin-types'?: Array<`${string}/${string}` | 'none'>; +``` + +
+ +
+ +- deprecated + +
+ +
+
+ +
+ +```dts +referrer?: Array< +| 'no-referrer' +| 'no-referrer-when-downgrade' +| 'origin' +| 'origin-when-cross-origin' +| 'same-origin' +| 'strict-origin' +| 'strict-origin-when-cross-origin' +| 'unsafe-url' +| 'none' +>; +``` + +
+ +
+ +- deprecated + +
+ +
+
+
+ +## HttpMethod + +
+ +```dts +type HttpMethod = + | 'GET' + | 'HEAD' + | 'POST' + | 'PUT' + | 'DELETE' + | 'PATCH' + | 'OPTIONS'; +``` + + +
+ +## Logger + +
+ +```dts +interface Logger {/*…*/} +``` + +
+ +```dts +(msg: string): void; +``` + +
+
+ +
+ +```dts +success(msg: string): void; +``` + +
+
+ +
+ +```dts +error(msg: string): void; +``` + +
+
+ +
+ +```dts +warn(msg: string): void; +``` + +
+
+ +
+ +```dts +minor(msg: string): void; +``` + +
+
+ +
+ +```dts +info(msg: string): void; +``` + +
+
+
+ +## MaybePromise + +
+ +```dts +type MaybePromise = T | Promise; +``` + + +
+ +## PrerenderEntryGeneratorMismatchHandler + +
+ +```dts +interface PrerenderEntryGeneratorMismatchHandler {/*…*/} +``` + +
+ +```dts +(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void; +``` + +
+
+
+ +## PrerenderEntryGeneratorMismatchHandlerValue + +
+ +```dts +type PrerenderEntryGeneratorMismatchHandlerValue = + | 'fail' + | 'warn' + | 'ignore' + | PrerenderEntryGeneratorMismatchHandler; +``` + + +
+ +## PrerenderHttpErrorHandler + +
+ +```dts +interface PrerenderHttpErrorHandler {/*…*/} +``` + +
+ +```dts +(details: { +status: number; +path: string; +referrer: string | null; +referenceType: 'linked' | 'fetched'; +message: string; +}): void; +``` + +
+
+
+ +## PrerenderHttpErrorHandlerValue + +
+ +```dts +type PrerenderHttpErrorHandlerValue = + | 'fail' + | 'warn' + | 'ignore' + | PrerenderHttpErrorHandler; +``` + + +
+ +## PrerenderMap + +
+ +```dts +type PrerenderMap = Map; +``` + + +
+ +## PrerenderMissingIdHandler + +
+ +```dts +interface PrerenderMissingIdHandler {/*…*/} +``` + +
+ +```dts +(details: { path: string; id: string; referrers: string[]; message: string }): void; +``` + +
+
+
+ +## PrerenderMissingIdHandlerValue + +
+ +```dts +type PrerenderMissingIdHandlerValue = + | 'fail' + | 'warn' + | 'ignore' + | PrerenderMissingIdHandler; +``` + + +
+ +## PrerenderOption + +
+ +```dts +type PrerenderOption = boolean | 'auto'; +``` + + +
+ +## Prerendered + +
+ +```dts +interface Prerendered {/*…*/} +``` + +
+ +```dts +pages: Map< +string, +{ + /** The location of the .html file relative to the output directory */ + file: string; +} +>; +``` + +
+ +A map of `path` to `{ file }` objects, where a path like `/foo` corresponds to `foo.html` and a path like `/bar/` corresponds to `bar/index.html`. + +
+
+ +
+ +```dts +assets: Map< +string, +{ + /** The MIME type of the asset */ + type: string; +} +>; +``` + +
+ +A map of `path` to `{ type }` objects. + +
+
+ +
+ +```dts +redirects: Map< +string, +{ + status: number; + location: string; +} +>; +``` + +
+ +A map of redirects encountered during prerendering. + +
+
+ +
+ +```dts +paths: string[]; +``` + +
+ +An array of prerendered paths (without trailing slashes, regardless of the trailingSlash config) + +
+
+
+ +## RequestOptions + +
+ +```dts +interface RequestOptions {/*…*/} +``` + +
+ +```dts +getClientAddress(): string; +``` + +
+
+ +
+ +```dts +platform?: App.Platform; +``` + +
+
+
+ +## RouteSegment + +
+ +```dts +interface RouteSegment {/*…*/} +``` + +
+ +```dts +content: string; +``` + +
+
+ +
+ +```dts +dynamic: boolean; +``` + +
+
+ +
+ +```dts +rest: boolean; +``` + +
+
+
+ +## TrailingSlash + +
+ +```dts +type TrailingSlash = 'never' | 'always' | 'ignore'; +``` + + +
+ diff --git a/apps/svelte.dev/includes/kit/__configuration/index.md b/apps/svelte.dev/includes/kit/__configuration/index.md new file mode 100644 index 0000000000..786c5e1027 --- /dev/null +++ b/apps/svelte.dev/includes/kit/__configuration/index.md @@ -0,0 +1,1105 @@ +## Config + +
+ +```dts +interface Config {/*…*/} +``` + +
+ +```dts +compilerOptions?: CompileOptions; +``` + +
+ +
+ +- default `{}` + +
+ +Options passed to [`svelte.compile`](https://svelte.dev/docs#compile-time-svelte-compile). + +
+
+ +
+ +```dts +extensions?: string[]; +``` + +
+ +
+ +- default `[".svelte"]` + +
+ +List of file extensions that should be treated as Svelte files. + +
+
+ +
+ +```dts +kit?: KitConfig; +``` + +
+ +SvelteKit options + +
+
+ +
+ +```dts +preprocess?: any; +``` + +
+ +Preprocessor options, if any. Preprocessing can alternatively also be done through Vite's preprocessor capabilities. + +
+
+ +
+ +```dts +vitePlugin?: PluginOptions; +``` + +
+ +`vite-plugin-svelte` plugin options. + +
+
+ +
+ +```dts +[key: string]: any; +``` + +
+ +Any additional options required by tooling that integrates with Svelte. + +
+
+
+ +## KitConfig + +
+ +```dts +interface KitConfig {/*…*/} +``` + +
+ +```dts +adapter?: Adapter; +``` + +
+ +
+ +- default `undefined` + +
+ +Your [adapter](https://kit.svelte.dev/docs/adapters) is run when executing `vite build`. It determines how the output is converted for different platforms. + +
+
+ +
+ +```dts +alias?: Record; +``` + +
+ +
+ +- default `{}` + +
+ +An object containing zero or more aliases used to replace values in `import` statements. These aliases are automatically passed to Vite and TypeScript. + +```js +// @errors: 7031 +/// file: svelte.config.js +/** @type {import('@sveltejs/kit').Config} */ +const config = { + kit: { + alias: { + // this will match a file + 'my-file': 'path/to/my-file.js', + + // this will match a directory and its contents + // (`my-directory/x` resolves to `path/to/my-directory/x`) + 'my-directory': 'path/to/my-directory', + + // an alias ending /* will only match + // the contents of a directory, not the directory itself + 'my-directory/*': 'path/to/my-directory/*' + } + } +}; +``` + +> The built-in `$lib` alias is controlled by `config.kit.files.lib` as it is used for packaging. + +> You will need to run `npm run dev` to have SvelteKit automatically generate the required alias configuration in `jsconfig.json` or `tsconfig.json`. + +
+
+ +
+ +```dts +appDir?: string; +``` + +
+ +
+ +- default `"_app"` + +
+ +The directory where SvelteKit keeps its stuff, including static assets (such as JS and CSS) and internally-used routes. + +If `paths.assets` is specified, there will be two app directories — `${paths.assets}/${appDir}` and `${paths.base}/${appDir}`. + +
+
+ +
+ +```dts +csp?: {/*…*/} +``` + +
+ +[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) configuration. CSP helps to protect your users against cross-site scripting (XSS) attacks, by limiting the places resources can be loaded from. For example, a configuration like this... + +```js +// @errors: 7031 +/// file: svelte.config.js +/** @type {import('@sveltejs/kit').Config} */ +const config = { + kit: { + csp: { + directives: { + 'script-src': ['self'] + }, + reportOnly: { + 'script-src': ['self'] + } + } + } +}; + +export default config; +``` + +...would prevent scripts loading from external sites. SvelteKit will augment the specified directives with nonces or hashes (depending on `mode`) for any inline styles and scripts it generates. + +To add a nonce for scripts and links manually included in `src/app.html`, you may use the placeholder `%sveltekit.nonce%` (for example ` +``` + +If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of the [`updated`](/docs/kit/reference/$app-stores#updated) store to `true` when it detects one. + +
+ +```dts +name?: string; +``` + +
+ +The current app version string. If specified, this must be deterministic (e.g. a commit ref rather than `Math.random()` or `Date.now().toString()`), otherwise defaults to a timestamp of the build. + +For example, to use the current commit hash, you could do use `git rev-parse HEAD`: + +```js +// @errors: 7031 +/// file: svelte.config.js +import * as child_process from 'node:child_process'; + +export default { + kit: { + version: { + name: child_process.execSync('git rev-parse HEAD').toString().trim() + } + } +}; +``` + +
+
+
+ +```dts +pollInterval?: number; +``` + +
+ +
+ +- default `0` + +
+ +The interval in milliseconds to poll for version changes. If this is `0`, no polling occurs. + +
+
+ +
+
+
+ diff --git a/apps/svelte.dev/includes/svelte/$derived/index.md b/apps/svelte.dev/includes/svelte/$derived/index.md new file mode 100644 index 0000000000..17c1e3cdad --- /dev/null +++ b/apps/svelte.dev/includes/svelte/$derived/index.md @@ -0,0 +1,162 @@ + + +```js +// @noErrors +import { + apply, + arguments, + bind, + by, + call, + caller, + length, + name, + prototype, + toString +} from '$derived'; +``` + +## apply + + + +
+ +```ts +// @noErrors +const apply: never; +``` + +
+ +## arguments + + + +
+ +```ts +// @noErrors +const arguments: never; +``` + +
+ +## bind + + + +
+ +```ts +// @noErrors +const bind: never; +``` + +
+ +## by + +Sometimes you need to create complex derivations that don't fit inside a short expression. +In these cases, you can use `$derived.by` which accepts a function as its argument. + +Example: +```ts +let total = $derived.by(() => { + let result = 0; + for (const n of numbers) { + result += n; + } + return result; +}); +``` + +https://svelte-5-preview.vercel.app/docs/runes#$derived-by + +
+ +```ts +// @noErrors +function by(fn: () => T): T; +``` + +
+ +## call + + + +
+ +```ts +// @noErrors +const call: never; +``` + +
+ +## caller + + + +
+ +```ts +// @noErrors +const caller: never; +``` + +
+ +## length + + + +
+ +```ts +// @noErrors +const length: never; +``` + +
+ +## name + + + +
+ +```ts +// @noErrors +const name: never; +``` + +
+ +## prototype + + + +
+ +```ts +// @noErrors +const prototype: never; +``` + +
+ +## toString + + + +
+ +```ts +// @noErrors +const toString: never; +``` + +
+ diff --git a/apps/svelte.dev/includes/svelte/$effect/index.md b/apps/svelte.dev/includes/svelte/$effect/index.md new file mode 100644 index 0000000000..df6c649d53 --- /dev/null +++ b/apps/svelte.dev/includes/svelte/$effect/index.md @@ -0,0 +1,228 @@ + + +```js +// @noErrors +import { + apply, + arguments, + bind, + call, + caller, + length, + name, + pre, + prototype, + root, + toString, + tracking +} from '$effect'; +``` + +## apply + + + +
+ +```ts +// @noErrors +const apply: never; +``` + +
+ +## arguments + + + +
+ +```ts +// @noErrors +const arguments: never; +``` + +
+ +## bind + + + +
+ +```ts +// @noErrors +const bind: never; +``` + +
+ +## call + + + +
+ +```ts +// @noErrors +const call: never; +``` + +
+ +## caller + + + +
+ +```ts +// @noErrors +const caller: never; +``` + +
+ +## length + + + +
+ +```ts +// @noErrors +const length: never; +``` + +
+ +## name + + + +
+ +```ts +// @noErrors +const name: never; +``` + +
+ +## pre + +Runs code right before a component is mounted to the DOM, and then whenever its dependencies change, i.e. `$state` or `$derived` values. +The timing of the execution is right before the DOM is updated. + +Example: +```ts +$effect.pre(() => console.log('The count is now ' + count)); +``` + +If you return a function from the effect, it will be called right before the effect is run again, or when the component is unmounted. + +Does not run during server side rendering. + +https://svelte-5-preview.vercel.app/docs/runes#$effect-pre + +
+ +```ts +// @noErrors +function pre(fn: () => void | (() => void)): void; +``` + +
+ +## prototype + + + +
+ +```ts +// @noErrors +const prototype: never; +``` + +
+ +## root + +The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for +nested effects that you want to manually control. This rune also allows for creation of effects outside of the component +initialisation phase. + +Example: +```svelte + + + +``` + +https://svelte-5-preview.vercel.app/docs/runes#$effect-root + +
+ +```ts +// @noErrors +function root(fn: () => void | (() => void)): () => void; +``` + +
+ +## toString + + + +
+ +```ts +// @noErrors +const toString: never; +``` + +
+ +## tracking + +The `$effect.tracking` rune is an advanced feature that tells you whether or not the code is running inside a tracking context, such as an effect or inside your template. + +Example: +```svelte + + +

in template: {$effect.tracking()}

+``` + +This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects. + +https://svelte-5-preview.vercel.app/docs/runes#$effect-tracking + +
+ +```ts +// @noErrors +function tracking(): boolean; +``` + +
+ diff --git a/apps/svelte.dev/includes/svelte/$state/index.md b/apps/svelte.dev/includes/svelte/$state/index.md new file mode 100644 index 0000000000..17e366e011 --- /dev/null +++ b/apps/svelte.dev/includes/svelte/$state/index.md @@ -0,0 +1,248 @@ + + +```js +// @noErrors +import { + apply, + arguments, + bind, + call, + caller, + length, + name, + prototype, + raw, + snapshot, + toString +} from '$state'; +``` + +## apply + + + +
+ +```ts +// @noErrors +const apply: never; +``` + +
+ +## arguments + + + +
+ +```ts +// @noErrors +const arguments: never; +``` + +
+ +## bind + + + +
+ +```ts +// @noErrors +const bind: never; +``` + +
+ +## call + + + +
+ +```ts +// @noErrors +const call: never; +``` + +
+ +## caller + + + +
+ +```ts +// @noErrors +const caller: never; +``` + +
+ +## length + + + +
+ +```ts +// @noErrors +const length: never; +``` + +
+ +## name + + + +
+ +```ts +// @noErrors +const name: never; +``` + +
+ +## prototype + + + +
+ +```ts +// @noErrors +const prototype: never; +``` + +
+ +## raw + +Declares state that is _not_ made deeply reactive — instead of mutating it, +you must reassign it. + +Example: +```ts + + + +``` + +https://svelte-5-preview.vercel.app/docs/runes#$state-raw + +
+ +```ts +// @noErrors +function raw(initial: T): T; +``` + +
+ +## raw + + + +
+ +```ts +// @noErrors +function raw(): T | undefined; +``` + +
+ +## snapshot + +To take a static snapshot of a deeply reactive `$state` proxy, use `$state.snapshot`: + +Example: +```ts + +``` + +https://svelte-5-preview.vercel.app/docs/runes#$state.snapshot + +
+ +```ts +// @noErrors +function snapshot(state: T): Snapshot; +``` + +
+ +## toString + + + +
+ +```ts +// @noErrors +const toString: never; +``` + +
+ +## Cloneable + +The things that `structuredClone` can handle — https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm + +
+ +```dts +type Cloneable = + | ArrayBuffer + | DataView + | Date + | Error + | Map + | RegExp + | Set + | TypedArray + // web APIs + | Blob + | CryptoKey + | DOMException + | DOMMatrix + | DOMMatrixReadOnly + | DOMPoint + | DOMPointReadOnly + | DOMQuad + | DOMRect + | DOMRectReadOnly + | File + | FileList + | FileSystemDirectoryHandle + | FileSystemFileHandle + | FileSystemHandle + | ImageBitmap + | ImageData + | RTCCertificate + | VideoFrame; +``` + + +
+ diff --git a/apps/svelte.dev/includes/svelte/svelte/action/index.md b/apps/svelte.dev/includes/svelte/svelte/action/index.md new file mode 100644 index 0000000000..9e0c123165 --- /dev/null +++ b/apps/svelte.dev/includes/svelte/svelte/action/index.md @@ -0,0 +1,105 @@ +## Action + +Actions are functions that are called when an element is created. +You can use this interface to type such actions. +The following example defines an action that only works on `
` elements +and optionally accepts a parameter which it has a default value for: +```ts +export const myAction: Action = (node, param = { someProperty: true }) => { + // ... +} +``` +`Action` and `Action` both signal that the action accepts no parameters. + +You can return an object with methods `update` and `destroy` from the function and type which additional attributes and events it has. +See interface `ActionReturn` for more details. + +Docs: https://svelte.dev/docs/svelte-action + +
+ +```dts +interface Action< + Element = HTMLElement, + Parameter = undefined, + Attributes extends Record = Record< + never, + any + > +> {/*…*/} +``` + +
+ +```dts +( + ...args: undefined extends Parameter + ? [node: Node, parameter?: Parameter] + : [node: Node, parameter: Parameter] +): void | ActionReturn; +``` + +
+
+
+ +## ActionReturn + +Actions can return an object containing the two properties defined in this interface. Both are optional. +- update: An action can have a parameter. This method will be called whenever that parameter changes, + immediately after Svelte has applied updates to the markup. `ActionReturn` and `ActionReturn` both + mean that the action accepts no parameters. +- destroy: Method that is called after the element is unmounted + +Additionally, you can specify which additional attributes and events the action enables on the applied element. +This applies to TypeScript typings only and has no effect at runtime. + +Example usage: +```ts +interface Attributes { + newprop?: string; + 'on:event': (e: CustomEvent) => void; +} + +export function myAction(node: HTMLElement, parameter: Parameter): ActionReturn { + // ... + return { + update: (updatedParameter) => {...}, + destroy: () => {...} + }; +} +``` + +Docs: https://svelte.dev/docs/svelte-action + +
+ +```dts +interface ActionReturn< + Parameter = undefined, + Attributes extends Record = Record< + never, + any + > +> {/*…*/} +``` + +
+ +```dts +update?: (parameter: Parameter) => void; +``` + +
+
+ +
+ +```dts +destroy?: () => void; +``` + +
+
+
+ diff --git a/apps/svelte.dev/includes/svelte/svelte/animate/index.md b/apps/svelte.dev/includes/svelte/svelte/animate/index.md new file mode 100644 index 0000000000..d22185d063 --- /dev/null +++ b/apps/svelte.dev/includes/svelte/svelte/animate/index.md @@ -0,0 +1,123 @@ + + +```js +// @noErrors +import { flip } from 'svelte/animate'; +``` + +## flip + +The flip function calculates the start and end position of an element and animates between them, translating the x and y values. +`flip` stands for [First, Last, Invert, Play](https://aerotwist.com/blog/flip-your-animations/). + +https://svelte.dev/docs/svelte-animate#flip + +
+ +```ts +// @noErrors +function flip( + node: Element, + { + from, + to + }: { + from: DOMRect; + to: DOMRect; + }, + params?: FlipParams +): AnimationConfig; +``` + +
+ +## AnimationConfig + +
+ +```dts +interface AnimationConfig {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: (t: number) => number; +``` + +
+
+ +
+ +```dts +css?: (t: number, u: number) => string; +``` + +
+
+ +
+ +```dts +tick?: (t: number, u: number) => void; +``` + +
+
+
+ +## FlipParams + +
+ +```dts +interface FlipParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number | ((len: number) => number); +``` + +
+
+ +
+ +```dts +easing?: (t: number) => number; +``` + +
+
+
+ diff --git a/apps/svelte.dev/includes/svelte/svelte/compiler/index.md b/apps/svelte.dev/includes/svelte/svelte/compiler/index.md new file mode 100644 index 0000000000..acc01df934 --- /dev/null +++ b/apps/svelte.dev/includes/svelte/svelte/compiler/index.md @@ -0,0 +1,1305 @@ + + +```js +// @noErrors +import { + VERSION, + compile, + compileModule, + migrate, + parse, + preprocess, + walk +} from 'svelte/compiler'; +``` + +## VERSION + +The current version, as set in package.json. + +https://svelte.dev/docs/svelte-compiler#svelte-version + +
+ +```ts +// @noErrors +const VERSION: string; +``` + +
+ +## compile + +`compile` converts your `.svelte` source code into a JavaScript module that exports a component + +https://svelte.dev/docs/svelte-compiler#svelte-compile + +
+ +```ts +// @noErrors +function compile( + source: string, + options: CompileOptions +): CompileResult; +``` + +
+ +## compileModule + +`compileModule` takes your JavaScript source code containing runes, and turns it into a JavaScript module. + +https://svelte.dev/docs/svelte-compiler#svelte-compile + +
+ +```ts +// @noErrors +function compileModule( + source: string, + options: ModuleCompileOptions +): CompileResult; +``` + +
+ +## migrate + +Does a best-effort migration of Svelte code towards using runes, event attributes and render tags. +May throw an error if the code is too complex to migrate automatically. + +
+ +```ts +// @noErrors +function migrate(source: string): { + code: string; +}; +``` + +
+ +## parse + +The parse function parses a component, returning only its abstract syntax tree. + +The `modern` option (`false` by default in Svelte 5) makes the parser return a modern AST instead of the legacy AST. +`modern` will become `true` by default in Svelte 6, and the option will be removed in Svelte 7. + +https://svelte.dev/docs/svelte-compiler#svelte-parse + +
+ +```ts +// @noErrors +function parse( + source: string, + options: { + filename?: string; + modern: true; + } +): AST.Root; +``` + +
+ +## parse + +The parse function parses a component, returning only its abstract syntax tree. + +The `modern` option (`false` by default in Svelte 5) makes the parser return a modern AST instead of the legacy AST. +`modern` will become `true` by default in Svelte 6, and the option will be removed in Svelte 7. + +https://svelte.dev/docs/svelte-compiler#svelte-parse + +
+ +```ts +// @noErrors +function parse( + source: string, + options?: + | { + filename?: string; + modern?: false; + } + | undefined +): Record; +``` + +
+ +## preprocess + +The preprocess function provides convenient hooks for arbitrarily transforming component source code. +For example, it can be used to convert a