configuration options

111 notes in this subject, read out of this brain and free to use. This is page 1 of 2.

svelte-preprocess additional functionality

svelte-preprocess provides additional functionality not found in vitePreprocess, including support for Pug, Babel, and global styles. However, vitePreprocess may be faster and require less configuration. CoffeeScript is not supported by SvelteKit.

vitePreprocess function parameters

vitePreprocess accepts a configuration object with two properties: style (boolean, default true) and script (boolean, default false). The style property enables CSS preprocessors including PostCSS, SCSS, Less, Stylus, and SugarSS in <style> tags. The script property should be set to true for projects before Svelte 5 or when using advanced TypeScript features that emit code.

svelte-preprocess installation and setup

To use svelte-preprocess, install it with 'npm i -D svelte-preprocess' and add it to svelte.config.js. After that, you often need to install the corresponding library for your chosen preprocessor, such as 'npm i -D sass' for SCSS or 'npm i -D less' for Less.

vitePreprocess import and usage

vitePreprocess is imported from '@sveltejs/vite-plugin-svelte' and is configured in the preprocess array of svelte.config.js as a SvelteKit Config option.

Generated tsconfig.json stricter in v2

The generated tsconfig.json in SvelteKit 2 is more strict and warns if your tsconfig.json includes paths or baseUrl settings. These should instead be configured using the alias config option in svelte.config.js.

TypeScript configuration changes in SvelteKit 2

The generated tsconfig.json in SvelteKit 2 now uses "moduleResolution": "bundler" and verbatimModuleSyntax. The verbatimModuleSyntax flag replaces importsNotUsedAsValues and preserveValueImports flags, which should be removed if present in your tsconfig.json.

Paths are relative by default in v2

In SvelteKit 2, paths are relative by default when paths.relative configuration is true. This applies consistently to %sveltekit.assets% in app.html and to base and assets imported from $app/paths. The default of true makes apps more portable when the base is unknown at build time or differs from expectations.

vitePreprocess no longer exported from @sveltejs/kit/vite in v2

In SvelteKit 2, vitePreprocess is no longer re-exported from @sveltejs/kit/vite. Import it directly from @sveltejs/vite-plugin-svelte instead, as it is now a peer dependency of SvelteKit.

Replace webpack or rollup config with svelte.config.js

Replace webpack.config.js or rollup.config.js with svelte.config.js as documented in the configuration docs. Move Svelte preprocessor options to config.preprocess.

defineEnvVars utility function

defineEnvVars is a utility function imported from @sveltejs/kit/env for defining environment variables that are made available via $app/env/public and $app/env/private. The function signature is: function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): T;

sveltekit vite plugin configuration from svelte.config.js

Prior to version 2.62.0, the sveltekit function reads configuration from svelte.config.js. From version 2.62.0 onward, you can pass configuration directly to the sveltekit function, in which case svelte.config.js is ignored.

Enable explicit environment variables

To use the $app/env/private module, you must enable the experimental.explicitEnvironmentVariables flag in your project configuration.

$app/env/public module

The $app/env/public module provides access to public environment variables that are defined in src/env.ts or src/env.js. To use this module, you must enable the experimental.explicitEnvironmentVariables flag in your project configuration.

$env/dynamic/private usage example with prefixes

Given environment variables ENVIRONMENT=production and PUBLIC_BASE_URL=http://site.com with default publicPrefix and privatePrefix, importing env from $env/dynamic/private allows access to env.ENVIRONMENT which returns "production", while env.PUBLIC_BASE_URL returns undefined because it has the public prefix.

Environment variables table: runtime vs build time

Environment variables are categorized by access level (Private/Public) and timing (Runtime/Build time). Private runtime variables use $env/dynamic/private. Private build time variables use $env/static/private. Public runtime variables use $env/dynamic/public. Public build time variables use $env/static/public.

$env/dynamic/private variable naming rules

The $env/dynamic/private module includes variables that do not begin with config.kit.env.publicPrefix and do start with config.kit.env.privatePrefix if configured.

$env/dynamic/private module purpose

The $env/dynamic/private module provides access to environment variables set dynamically at runtime and limited to private access.

$env/dynamic/private cannot be imported in client code

The $env/dynamic/private module cannot be imported into client-side code.

Declaring environment variables for correct types

To get correct types, environment variables referenced in your code should be declared in an .env file even if they don't have a value until the app is deployed.

Dynamic environment variables in dev vs prod

In development, $env/dynamic includes environment variables from .env files. In production, this behavior depends on your adapter.

$env/dynamic/public module

The $env/dynamic/public module provides access to environment variables that are set dynamically at runtime and are publicly accessible. This module can be imported into client-side code.

$env/dynamic/public only includes PUBLIC_ prefixed variables

Only environment variables that begin with the config.kit.env.publicPrefix (which defaults to PUBLIC_) are included in $env/dynamic/public.

$env/dynamic/public access control example

With environment variables ENVIRONMENT=production and PUBLIC_BASE_URL=http://example.com, importing from $env/dynamic/public will have env.ENVIRONMENT as undefined (not public) and env.PUBLIC_BASE_URL as "http://example.com" with the default publicPrefix.

Override .env values from command line

You can override .env values from the command line when running npm scripts, for example: MY_FEATURE_FLAG="enabled" npm run dev

Dynamic environment variables platform equivalence

Dynamic environment variables are defined by the platform you are running on. For example, if using adapter-node or running vite preview, this is equivalent to process.env.

EnvVarConfig.static property

EnvVarConfig.static is a boolean (default false) that determines whether the value is determined at build time or when the app runs. If true, the build time value is inlined into the bundle enabling dead-code elimination. If false, the value is read from the environment when the app starts.

EnvVarConfig.public property

EnvVarConfig.public is a boolean (default false) that determines whether the environment variable can be accessed by client-side code. If true, it can be imported from $app/env/public. If false, it can be imported from $app/env/private which is a server-only module.

EnvVarConfig.schema property

EnvVarConfig.schema is a Standard Schema validator applied to the value when the app starts. The validator can output any value, but public non-static values must be serializable by devalue to be sent to the browser. If omitted, the value must be a non-empty string.

EnvVarConfig.description property

EnvVarConfig.description is a string that describes the variable and is used for inline documentation on hover.

SSRManifest properties

SSRManifest has properties: appDir: string, appPath: string, assets: Set<string> (static files from kit.config.files.assets and service worker), mimeTypes: Record<string, string>, and private fields _: {client: BuildData['client'], nodes: SSRNodeLoader[], remotes: Record<string, () => Promise<any>> (hashed filename -> import), routes: SSRRoute[], prerendered_routes: Set<string>, matchers: () => Promise<Record<string, ParamMatcher>>, server_assets: Record<string, number> ([file]: size map of assets imported by server code)}.

Csp namespace ActionSource type

Csp.ActionSource is type 'strict-dynamic' | 'report-sample'.

Csp namespace BaseSource type

Csp namespace CryptoSource type

Csp.CryptoSource is type `${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}` (template literal type).

Csp namespace FrameSource type

Csp.FrameSource is type HostSource | SchemeSource | 'self' | 'none'.

Csp namespace HostSource type

Csp.HostSource is type `${HostProtocolSchemes}${HostNameScheme}${PortScheme}` where HostProtocolSchemes is `${string}://` | '', HostNameScheme is `${string}.${string}` | 'localhost', PortScheme is `:${number}` | '' | ':*'.

Csp namespace SchemeSource type

Csp.SchemeSource is type 'http:' | 'https:' | 'ws:' | 'wss:' | 'data:' | 'mediastream:' | 'blob:' | 'filesystem:' | (`${string}:` & {}).

Csp namespace Source type

Csp.Source is union type: HostSource | SchemeSource | CryptoSource | BaseSource.

CspDirectives directive list

CspDirectives has optional properties: 'child-src', 'default-src' (allows ActionSource), 'frame-src', 'worker-src', 'connect-src', 'font-src', 'img-src', 'manifest-src', 'media-src', 'object-src', 'prefetch-src', 'script-src' (allows ActionSource), 'script-src-elem', 'script-src-attr', 'style-src' (allows ActionSource), 'style-src-elem', 'style-src-attr', 'base-uri' (allows ActionSource), sandbox (array of sandbox tokens), 'form-action' (allows ActionSource), 'frame-ancestors' (HostSource | SchemeSource | FrameSource), 'navigate-to' (allows ActionSource), 'report-uri', 'report-to', 'require-trusted-types-for', 'trusted-types', 'upgrade-insecure-requests'. Deprecated: 'require-sri-for', 'block-all-mixed-content', 'plugin-types', referrer.

TrailingSlash type values

TrailingSlash is type 'never' | 'always' | 'ignore'.

Environment variable modules matrix

SvelteKit provides four environment variable modules organized by access type and loading time: $env/dynamic/private (runtime, private), $env/static/private (build time, private), $env/dynamic/public (runtime, public), and $env/static/public (build time, public).

$env/static/public module overview

The $env/static/public module provides access to environment variables that are injected statically into the bundle at build time and are publicly accessible.

$env/static/public import error on private variables

Attempting to import a non-public environment variable (one without the publicPrefix) from $env/static/public will throw an error during build. For example, importing ENVIRONMENT when the publicPrefix is 'PUBLIC_' will throw an error because ENVIRONMENT does not start with 'PUBLIC_'.

$env/static/public static replacement behavior

Environment variables imported from $env/static/public are statically replaced in code with their build time values. This means the values will be the same even if different values are set at runtime.

$env/static/public loading mechanism

Static environment variables are loaded by Vite from .env files and process.env at build time, then statically injected into the bundle at build time. This enables optimizations like dead code elimination.

$env/static/public prefix filtering

Only environment variables that begin with the publicPrefix (which defaults to 'PUBLIC_') are included in the $env/static/public module. The publicPrefix is configured via config.kit.env.publicPrefix.

$env/static/public is client-side accessible

The $env/static/public module can be imported into client-side code, unlike the private variants.

Generated tsconfig.json paths alias for $lib

The generated .svelte-kit/tsconfig.json includes a paths alias mapping $lib to ../src/lib and $lib/* to ../src/lib/*, allowing access to common components and utilities without relative paths.

tsconfig.json must extend .svelte-kit/tsconfig.json

Your own tsconfig.json or jsconfig.json should extend from the generated .svelte-kit/tsconfig.json (where .svelte-kit is your outDir) for type generation to work properly.

Generated tsconfig.json rootDirs configuration

The generated .svelte-kit/tsconfig.json includes rootDirs set to ["..", "./types"], which allows importing $types from sibling files.

app.d.ts contains ambient App namespace

The app.d.ts file is home to ambient types of your app that are available without explicitly importing them. It always contains an App namespace with interfaces that influence the shape of SvelteKit features.

App namespace interfaces in app.d.ts

The App namespace can contain the following interfaces to type SvelteKit features: Error, Locals, PageData, PageState, and Platform.

Generated tsconfig.json compilerOptions for SvelteKit

The generated .svelte-kit/tsconfig.json includes these compilerOptions: verbatimModuleSyntax: true (ensures types are imported with import type), isolatedModules: true (Vite compiles one module at a time), noEmit: true (TS used for type-checking only), lib: ["esnext", "DOM", "DOM.Iterable"], moduleResolution: "bundler", module: "esnext", target: "esnext".

Extend tsconfig.json using typescript.config setting

Use the typescript.config setting in svelte.config.js to extend or modify the generated tsconfig.json.

app.d.ts requires export statement for imports

The app.d.ts file requires an export {} statement at the end because without it, the file would be treated as an ambient module which prevents you from adding import declarations. If you need ambient declare module declarations, put them in a separate file like src/ambient.d.ts.

files.errorTemplate configuration option

The files.errorTemplate option specifies the location of the template for fallback error responses. Default is 'src/error.html'. This feature is deprecated in favor of monorepos.

svelte.config.js location and purpose

Your project's configuration lives in a svelte.config.js file at the root of your project. This config object is used by SvelteKit and other tooling that integrates with Svelte such as editor extensions.

Configuration in Vite config since v2.62.0

Since version 2.62.0, you can pass your configuration to the sveltekit plugin in your Vite config (vite.config.js) along with the Svelte compiler options, instead of using svelte.config.js. If the config is defined via the plugin, the svelte.config.js file is ignored.

Config interface extends SvelteConfig

The Config interface extends SvelteConfig and has two properties: kit (SvelteKit options) and [key: string]: any (any additional options required by tooling that integrates with Svelte).

adapter configuration option

The adapter configuration option determines how the output is converted for different platforms. It is run when executing vite build. Default is undefined.

alias configuration option

The alias option is an object containing zero or more aliases used to replace values in import statements. These aliases are automatically passed to Vite and TypeScript. Default is {}. You need to run npm run dev to have SvelteKit automatically generate the required alias configuration in jsconfig.json or tsconfig.json.

Give your agent this brain