features

212 notes in this subject, read out of this brain and free to use. This is page 3 of 4.

package.json svelte legacy field

The svelte field is a legacy field that enabled tooling to recognize Svelte component libraries. It is no longer necessary when using the svelte export condition, but it is good to keep for backwards compatibility with outdated tooling. It should point to the root entry point.

package.json sideEffects field purpose

The sideEffects field tells bundlers whether a module may contain code with side effects. Side effects include modifying global variables or built-in JavaScript object prototypes. Files marked with side effects will be included in the bundle regardless of whether their exports are used, enabling tree-shaking of side-effect-free code.

Recommended sideEffects configuration for libraries

Libraries should mark CSS files as having side effects to ensure compatibility with webpack. The recommended configuration is {"sideEffects": ["**/*.css"]}. All scripts are marked as side-effect-free by default in newly created projects.

TypeScript moduleResolution for library exports

When a library has non-root exports with type definitions, TypeScript will not resolve the types condition by default. Users need to set moduleResolution to bundler (TypeScript 5+), node16, or nodenext in their tsconfig.json or jsconfig.json to resolve types correctly.

typesVersions for TypeScript type path mapping

The typesVersions field in package.json can be used to provide type definitions for non-root exports when users cannot use bundler/node16/nodenext moduleResolution. Use >4.0 to match TypeScript versions greater than 4.0. When using typesVersions, all type imports including the root import must be declared through it.

Avoid SvelteKit-specific modules in packages

Libraries should avoid using SvelteKit-specific modules like $app/environment unless the package is only for SvelteKit projects. Use alternatives like esm-env instead, or pass values as props rather than relying on $app/state or $app/navigation.

Configure aliases in svelte.config.js for packages

Aliases should be added via svelte.config.js (not vite.config.js or tsconfig.json) so that they are processed by svelte-package.

Breaking changes in package exports

Removing paths from exports or removing export conditions from existing exports should be regarded as breaking changes. Adding new paths or export conditions is not a breaking change. Changing svelte to default is a breaking change.

Declaration maps for library source mapping

Setting declarationMap: true in tsconfig.json creates d.ts.map files that allow editors to go to the original .ts or .svelte file when using features like Go to Definition. Source files must be published alongside dist in a way that relative paths in declaration files lead to files on disk. Add src/lib to files in package.json and exclude test files.

svelte-package command-line options

svelte-package accepts the following options: -w/--watch (watch files for changes and rebuild), -i/--input (input directory, defaults to src/lib), -o/--output (output directory, defaults to dist), -p/--preserve-output (prevent deletion of output directory, defaults to false), -t/--types (whether to create type definitions, defaults to true), --tsconfig (path to tsconfig or jsconfig, searches workspace if not provided).

ESM imports in library files must include file extensions

All relative file imports in SvelteKit component libraries must be fully specified with file extensions, following Node's ESM algorithm. For example, import from './something/index.js' not './something'.

TypeScript imports in library files use .js extension

When importing TypeScript files in a library, use the .js file extension instead of .ts. This is a TypeScript design decision. Setting moduleResolution to NodeNext in tsconfig.json or jsconfig.json helps with this.

File processing in svelte-package

svelte-package processes files as follows: Svelte files are preprocessed, TypeScript files are transpiled to JavaScript, and all other files are copied across as-is.

Vite plugins in SvelteKit projects

SvelteKit projects are built with Vite, allowing the use of Vite plugins to enhance projects. Available Vite plugins can be found at vitejs/awesome-vite repository.

TypeScript support in Svelte 5

TypeScript is supported natively in Svelte 5. If using Svelte 5 and not requiring advanced TypeScript features that emit code, vitePreprocess is not necessary.

Top-level promises no longer auto-awaited in load functions

In SvelteKit 2, top-level promises in load function return objects are no longer automatically awaited. You must explicitly use await to get blocking behavior. Use Promise.all() with await to avoid waterfalls when fetching multiple promises.

preloadCode arguments must include base prefix in v2

In SvelteKit 2, paths passed to preloadCode() must be prefixed with the base path if base is set, matching the behavior of preloadData(). Additionally, preloadCode() now takes a single argument rather than multiple arguments.

$app/stores deprecated in SvelteKit 2.12, use $app/state

SvelteKit 2.12 deprecated $app/stores in favor of $app/state based on Svelte 5 runes API. $app/state provides everything $app/stores provides with more flexibility and fine-grained reactivity. To migrate, replace $app/stores imports with $app/state and remove the $ prefixes from usage sites.

PWA - Progressive web app definition

A progressive web app (PWA) is an app built using web APIs and technologies that functions like a mobile or desktop app. PWAs can be installed, allowing you to add a shortcut to the application on your launcher, home screen, or start menu. Many PWAs utilize service workers to build offline capabilities.

$app/env/private module

The $app/env/private module provides access to private environment variables that are defined in src/env.ts or src/env.js.

page store behavior and purpose

The page store is 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.

page store type signature

The page store has type Readable<Page> from the Svelte store module.

updated store initial value and polling behavior

The updated store is a readable store whose initial value is false. If version.pollInterval is configured with a non-zero value, SvelteKit will poll for new versions of the app and update the store value to true when a new version is detected. The store has a check() method that forces an immediate check for new versions, regardless of polling configuration.

updated store subscription restrictions

On the server, the updated store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time.

updated store type signature

The updated store has type Readable<boolean> with an additional check() method that returns Promise<boolean>.

$app/stores module deprecated in favor of $app/state

The $app/stores module contains store-based equivalents of the exports from $app/state. For SvelteKit 2.12 or later, use $app/state instead. This module is now deprecated and requires migration to Svelte 5.

getStores function signature

The getStores function returns an object with three properties: page (typeof page), navigating (typeof navigating), and updated (typeof updated). It takes no parameters and is used to retrieve the reactive stores.

navigating store behavior and value

The navigating store is a readable store that contains a Navigation object when navigating starts. The Navigation object has properties: from, to, type, and delta (if type === 'popstate'). When navigating finishes, the 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.

navigating store type signature

The navigating store has type Readable<Navigation | null> from the Svelte store module.

updated.check() method

The updated object has a check() method that returns Promise<boolean>. It will force an immediate check for new app versions, regardless of polling settings.

$app/state module provides three objects

SvelteKit makes three read-only state objects available via the $app/state module: page, navigating, and updated. This module was added in SvelteKit 2.12; earlier versions should use $app/stores instead.

navigating object properties and behavior

The navigating object is a read-only object representing an in-progress navigation. It has properties: from, to, type, and (if type === 'popstate') delta. Values are null when no navigation is occurring or during server rendering.

navigating TypeScript type signature

The navigating constant has type: Navigation | { from: null; to: null; type: null; willUnload: null; delta: null; complete: null; }

page object use cases

The page object is a read-only reactive object with information about the current page. It is used for: retrieving the combined data of all pages/layouts anywhere in the component tree, retrieving the current value of the form prop anywhere in the component tree, retrieving the page state set through goto/pushState/replaceState, and retrieving metadata such as the URL, current route, route parameters, and whether there was an error.

page changes only reactive with runes, not legacy syntax

Changes to page are available exclusively with runes. The legacy reactivity syntax (labels with $:) will not reflect any changes to page. Use $derived(page.params.id) instead of $: badId = page.params.id.

page object server-side limitations

On the server, values from page can only be read during rendering, not in load functions or other server-side contexts. In the browser, values can be read at any time.

page TypeScript type signature

The page constant has type: import('@sveltejs/kit').Page

updated object initial value and behavior

The updated object is a read-only reactive value that is initially false. If version.pollInterval is a non-zero value, SvelteKit will poll for new versions of the app and update updated.current to true when it detects one.

updated TypeScript type signature

The updated constant has type: { get current(): boolean; check(): Promise<boolean>; }

$app/server prerender function signature

The prerender function from $app/server creates a remote prerender function. It has three overloads: (1) prerender<Output>(fn: () => MaybePromise<Output>, options?: {inputs?: RemotePrerenderInputsGenerator<void>; dynamic?: boolean;} | undefined) returns RemotePrerenderFunction<void, Output>; (2) prerender<Input, Output>(validate: 'unchecked', fn: (arg: Input) => MaybePromise<Output>, options?: {inputs?: RemotePrerenderInputsGenerator<Input>; dynamic?: boolean;} | undefined) returns RemotePrerenderFunction<Input, Output>; (3) prerender<Schema extends StandardSchemaV1, Output>(schema: Schema, fn: (arg: StandardSchemaV1.InferOutput<Schema>) => MaybePromise<Output>, options?: {inputs?: RemotePrerenderInputsGenerator<StandardSchemaV1.InferInput<Schema>>; dynamic?: boolean;} | undefined) returns RemotePrerenderFunction<StandardSchemaV1.InferInput<Schema>, Output>. When called from the browser, the function is invoked on the server via a fetch call. Available since version 2.27.

$app/server form function signature

The form function from $app/server creates a form object that can be spread onto a <form> element. It has three overloads: (1) form<Output>(fn: () => MaybePromise<Output>) returns RemoteForm<void, Output>; (2) form<Input extends RemoteFormInput, Output>(validate: 'unchecked', fn: (data: Input, issue: InvalidField<Input>) => MaybePromise<Output>) returns RemoteForm<Input, Output>; (3) form<Schema extends StandardSchemaV1<RemoteFormInput, Record<string, any>>, Output>(validate: Schema, fn: (data: StandardSchemaV1.InferOutput<Schema>, issue: InvalidField<StandardSchemaV1.InferInput<Schema>>) => MaybePromise<Output>) returns RemoteForm<StandardSchemaV1.InferInput<Schema>, Output>. The validation overload with a schema enforces that all booleans in form schemas must be optional (e.g., v.optional(v.boolean(), false)) because checkbox inputs do not send a false value when unchecked. Available since version 2.27.

$app/server getRequestEvent function

The getRequestEvent function from $app/server returns the current RequestEvent. It can be used inside server hooks, server load functions, actions, and endpoints (and functions called by them). In environments without AsyncLocalStorage, this must be called synchronously (i.e., not after an await). Signature: function getRequestEvent(): RequestEvent;. Available since version 2.20.0.

$app/server query function signature

The query function from $app/server creates a remote query. It has three overloads: (1) query<Output>(fn: () => MaybePromise<Output>) returns RemoteQueryFunction<void, Output>; (2) query<Input, Output>(validate: 'unchecked', fn: (arg: Input) => MaybePromise<Output>) returns RemoteQueryFunction<Input, Output>; (3) query<Schema extends StandardSchemaV1, Output>(schema: Schema, fn: (arg: StandardSchemaV1.InferOutput<Schema>) => MaybePromise<Output>) returns RemoteQueryFunction<StandardSchemaV1.InferInput<Schema>, Output, StandardSchemaV1.InferOutput<Schema>>. When called from the browser, the function is invoked on the server via a fetch call. Available since version 2.27.

$app/server read function

The read function from $app/server reads the contents of an imported asset from the filesystem. Signature: function read(asset: string): Response;. Example usage: import { read } from '$app/server'; import somefile from './somefile.txt'; const asset = read(somefile); const text = await asset.text();. Available since version 2.4.0.

$app/server requested function

The requested function from $app/server is used inside a remote command or form callback. It returns an iterable of { arg, query } entries for the query instances the client asked to refresh, up to the supplied limit. Each query is a RemoteQuery bound to the original client-side cache key, so refresh() / set() propagate correctly even when the query's schema transforms the input. arg is the validated argument (the value after the schema has run). Arguments that fail validation or exceed limit are recorded as failures in the response to the client. Signature: function requested<Input, Output, Validated = Input>(query: RemoteQueryFunction<Input, Output, Validated>, limit: number): QueryRequestedResult<Validated, Output>; and function requested<Input, Output, Validated = Input>(query: RemoteLiveQueryFunction<Input, Output, Validated>, limit: number): LiveQueryRequestedResult<Validated, Output>;. As a shorthand, you can call refreshAll() on the result to await all refreshes and forward errors. Works with query.batch as well.

$app/server query.batch function

The query.batch function from $app/server creates a batch query function that collects multiple calls and executes them in a single request. It has two overloads: (1) query.batch<Input, Output>(validate: 'unchecked', fn: (args: Input[]) => MaybePromise<(arg: Input, idx: number) => Output>) returns RemoteQueryFunction<Input, Output>; (2) query.batch<Schema extends StandardSchemaV1, Output>(schema: Schema, fn: (args: StandardSchemaV1.InferOutput<Schema>[]) => MaybePromise<(arg: StandardSchemaV1.InferOutput<Schema>, idx: number) => Output>) returns RemoteQueryFunction<StandardSchemaV1.InferInput<Schema>, Output, StandardSchemaV1.InferOutput<Schema>>. Available since version 2.35.

$app/server query.live function

The query.live function from $app/server creates a live remote query. When called from the browser, the function is invoked on the server via a streaming fetch call. It has three overloads: (1) query.live<Output>(fn: (arg: void) => RemoteLiveQueryUserFunctionReturnType<Output>) returns RemoteLiveQueryFunction<void, Output>; (2) query.live<Input, Output>(validate: 'unchecked', fn: (arg: Input) => RemoteLiveQueryUserFunctionReturnType<Output>) returns RemoteLiveQueryFunction<Input, Output>; (3) query.live<Schema extends StandardSchemaV1, Output>(schema: Schema, fn: (arg: StandardSchemaV1.InferOutput<Schema>) => RemoteLiveQueryUserFunctionReturnType<Output>) returns RemoteLiveQueryFunction<StandardSchemaV1.InferInput<Schema>, Output, StandardSchemaV1.InferOutput<Schema>>.

Asset type definition

The Asset type is a union of all filenames of assets in the static directory, plus a string wildcard for asset paths generated from import declarations. Example: type Asset = '/favicon.png' | '/robots.txt' | (string & {});

RequestEvent isRemoteRequest property

RequestEvent has isRemoteRequest boolean property that is true if the request comes from the client via a remote function. The url property will be stripped of internal data request information in this case.

RequestedEntry structure for remote queries

RequestedEntry is yielded by requested() when called with regular query and has structure: {arg: Validated (the validated argument after schema validation and transformation), query: RemoteQuery<Output> (RemoteQuery bound to client's original cache key so refresh()/set() update correct client entry)}.

RequestedResult union type

RequestedResult is a union type that can be either QueryRequestedResult<Validated, Output> or LiveQueryRequestedResult<Validated, Output>.

Snapshot interface for state management

Snapshot interface (exported as 'export const snapshot' from page/layout components) has methods: capture(): T (captures current state), restore(snapshot: T): void (restores state from snapshot).

VERSION constant

VERSION is a string constant exported from @sveltejs/kit representing the version of SvelteKit.

LoadEvent.fetch method

LoadEvent.fetch is equivalent to native fetch with additional features: makes credentialed requests with inherited cookies and auth headers, supports relative requests on server, direct calls to +server.js routes without HTTP overhead, captures and inlines response during SSR, and reads from HTML during hydration.

LoadEvent.data property

LoadEvent.data contains the data returned by the route's server load function in +layout.server.js or +page.server.js, if any.

LoadEvent.setHeaders() method

LoadEvent.setHeaders() sets headers for the response (useful for caching). Must be called only once per header - cannot be called multiple times for the same header. Cannot set set-cookie headers (use cookies API instead). Has no effect when load function runs in browser.

LoadEvent.parent() method

LoadEvent.parent() returns a Promise that resolves data from parent +layout.js load functions. A missing +layout.js is treated as ({ data }) => data, forwarding parent +layout.server.js data. Avoid introducing waterfalls - call after fetching other data.

LoadEvent.depends() method

LoadEvent.depends() declares that the load function has a dependency on URLs or custom identifiers, allowing rerun via invalidate(). Most fetch calls do this automatically. Custom identifiers require lowercase letter prefix and colon to conform to URI spec. Signature: depends(...deps: Array<`${string}:${string}`>): void

LoadEvent.untrack() method

LoadEvent.untrack() opts out of dependency tracking for code synchronously called within the callback. Useful to prevent certain properties like url.pathname from triggering load reruns.

LoadEvent.tracing property

LoadEvent.tracing provides access to spans for tracing. Available since v2.31.0. Has enabled (boolean), root (root span named sveltekit.handle.root), and current (span for current load) properties. Does nothing if tracing not enabled or running in browser.

Give your agent this brain