SvelteKitCore concepts

Environment variables

Environment variables are values your app needs that exist separately from the app’s source code. They allow you to use sensitive information like API keys and database credentials without storing them in version control.

During development, and at build time, variables defined in a .env or .env.local file will be added to the environment:

.env

API_KEY=19f401ba-e8b0-48c4-8c77-b0ebb26d97fe

After following the setup below, they can be imported via the following modules:

Legacy mode
The $env/* modules, along with $app/environment were deprecated in SvelteKit 3 (and will be removed in SvelteKit 4) in favour of explicit environment variables that were added in SvelteKit 2.62 as an experimental option.

Setup

Add a src/env.ts (or src/env.js) file that exports a variables object:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';

export const variablesconst variables: DefinedEnvVars<{}> = defineEnvVars(alias) defineEnvVars<{}>(variables: {}): DefinedEnvVars<{}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	// ...});

Each value in the object passed to defineEnvVars is an EnvVarConfig object that configures the environment variable.

defineEnvVars returns its argument unaltered — it exists purely to help with type safety.

Private variables

By default, all variables are considered private. For example, you don’t want to reveal your API_KEY:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';

export const variablesconst variables: DefinedEnvVars<{
    API_KEY: {};
}> = defineEnvVars(alias) defineEnvVars<{
    API_KEY: {};
}>(variables: {
    API_KEY: {};
}): DefinedEnvVars<{
    API_KEY: {};
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	API_KEY(property) API_KEY: {}: {}
});

Since no configuration is needed for this variable, we can use an empty object ({}).

Now that API_KEY is defined, it can be imported into app code via $app/env/private:

import { API_KEYimport API_KEY } from '$app/env/private';

The $app/env/private module cannot be imported into code that runs in the browser, so that you can’t accidentally reveal your secrets in a JavaScript bundle.

Public variables

Some variables are perfectly safe — necessary, even — to expose to the browser. For these, we can specify public: true:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';

export const variablesconst variables: DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
    };
}>(variables: {
    GOOGLE_ANALYTICS_ID: {
        public: true;
    };
}): DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	GOOGLE_ANALYTICS_ID(property) GOOGLE_ANALYTICS_ID: {
    public: true;
}: {
		public(property) public: true: true
	}
});

GOOGLE_ANALYTICS_ID can now be imported from $app/env/public, or used in your app.html template as %sveltekit.env.GOOGLE_ANALYTICS_ID%:

src/app

<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" href="%sveltekit.assets%/favicon.png" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		%sveltekit.head%

		<script
			async
			src="https://www.googletagmanager.com/gtag/js?id=%sveltekit.env.GOOGLE_ANALYTICS_ID%"
		></script>

		<script>
			window.dataLayer ??= [];
			function gtag(){dataLayer.push(arguments)}
			gtag('js', new Date());
			gtag('config', '%sveltekit.env.GOOGLE_ANALYTICS_ID%');
		</script>
	</head>
	<body data-sveltekit-preload-data="hover">
		<div style="display: contents">%sveltekit.body%</div>
	</body>
</html>

Validation

You can specify a Standard Schema validator such as Zod or Valibot to check that an environment variable value is correct:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';
import * as vimport v from 'valibot';

export const variablesconst variables: DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
    };
}>(variables: {
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
    };
}): DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	GOOGLE_ANALYTICS_ID(property) GOOGLE_ANALYTICS_ID: {
    public: true;
    schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
}: {
		public(property) public: true: true,
		schema(property) schema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>: vimport v.pipe(alias) pipe<v.StringSchema<undefined>, v.RegexAction<string, undefined>>(schema: v.StringSchema<undefined>, item1: v.RegexAction<string, undefined> | v.PipeAction<string, string, v.RegexIssue<string>>): v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]> (+20 overloads)
export pipeAdds a pipeline to a schema, that can validate and transform its input.
schema The root schema.
item1 The first pipe item.
A schema with a pipeline.
(vimport v.string(alias) string(): v.StringSchema<undefined> (+1 overload)
export stringCreates a string schema.
A string schema.
(), vimport v.regex(alias) regex<string>(requirement: RegExp): v.RegexAction<string, undefined> (+1 overload)
export regexCreates a regex validation action.
Hint: Be careful with the global flag g in your regex pattern, as it can lead to unexpected results. See MDN for more information.
requirement The regex pattern.
A regex action.
(/G-[A-Z0-9]+/))
	}
});

If you don’t want to bring in a schema library, you can pass a function that returns the (possibly transformed) value, or throws an error explaining the problem:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';

export const variablesconst variables: DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: (value: string | undefined) => string;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: (value: string | undefined) => string;
    };
}>(variables: {
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: (value: string | undefined) => string;
    };
}): DefinedEnvVars<{
    GOOGLE_ANALYTICS_ID: {
        public: true;
        schema: (value: string | undefined) => string;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	GOOGLE_ANALYTICS_ID(property) GOOGLE_ANALYTICS_ID: {
    public: true;
    schema: (value: string | undefined) => string;
}: {
		public(property) public: true: true,
		schema(property) schema: (value: string | undefined) => string: (value(parameter) value: string | undefined) => {
			if (!value(parameter) value: string | undefined?.startsWith(method) String.startsWith(searchString: string, position?: number): booleanReturns true if the sequence of elements of searchString converted to a String is the
same as the corresponding elements of this object (converted to a String) starting at
position. Otherwise returns false.
('G-')) throw new Errorvar Error: ErrorConstructor
new (message?: string, options?: ErrorOptions) => Error (+1 overload)('expected a Google Analytics ID');
			return value(parameter) value: string;
		}
	}
});

If a value is invalid, the app will fail to start (or build). To opt out of one or the other, use building from $app/env along with a validator that accepts an optional value:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';
import { building(alias) const building: boolean
import buildingSvelteKit analyses your app during the build step by running it. During this process, building is true. This also applies during prerendering.
reference } from '$app/env'
import * as vimport v from 'valibot';

export const variablesconst variables: DefinedEnvVars<{
    SECRET: {
        schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    SECRET: {
        schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>;
    };
}>(variables: {
    SECRET: {
        schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>;
    };
}): DefinedEnvVars<{
    SECRET: {
        schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	SECRET(property) SECRET: {
    schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>;
}: {
		// optional when building but required when starting the app		schema(property) schema: v.StringSchema<undefined> | v.OptionalSchema<v.StringSchema<undefined>, undefined>: building(alias) const building: boolean
import buildingSvelteKit analyses your app during the build step by running it. During this process, building is true. This also applies during prerendering.
reference ? vimport v.optional(alias) optional<v.StringSchema<undefined>>(wrapped: v.StringSchema<undefined>): v.OptionalSchema<v.StringSchema<undefined>, undefined> (+1 overload)
export optionalCreates an optional schema.
wrapped The wrapped schema.
An optional schema.
(vimport v.string(alias) string(): v.StringSchema<undefined> (+1 overload)
export stringCreates a string schema.
A string schema.
()) : vimport v.string(alias) string(): v.StringSchema<undefined> (+1 overload)
export stringCreates a string schema.
A string schema.
()
	}
});

You can use validators to make values optional, or transform them (such as turning a string into a boolean, or parsing JSON) — see your validation library’s documentation to learn how.

Static variables

By default, variables are dynamic. If a variable is configured with static: true, it will be inlined into your application code, enabling optimisations like dead-code elimination:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';
import * as vimport v from 'valibot';

export const variablesconst variables: DefinedEnvVars<{
    SHOW_DEBUG_OVERLAY: {
        public: true;
        static: true;
        schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    SHOW_DEBUG_OVERLAY: {
        public: true;
        static: true;
        schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>;
    };
}>(variables: {
    SHOW_DEBUG_OVERLAY: {
        public: true;
        static: true;
        schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>;
    };
}): DefinedEnvVars<{
    SHOW_DEBUG_OVERLAY: {
        public: true;
        static: true;
        schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	SHOW_DEBUG_OVERLAY(property) SHOW_DEBUG_OVERLAY: {
    public: true;
    static: true;
    schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>;
}: {
		public(property) public: true: true,
		static(property) static: true: true,
		// coerce to true/false		schema(property) schema: v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]>: vimport v.pipe(alias) pipe<v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>>(schema: v.OptionalSchema<v.StringSchema<undefined>, "">, item1: v.TransformAction<string, boolean> | v.PipeAction<string, boolean, never>): v.SchemaWithPipe<readonly [v.OptionalSchema<v.StringSchema<undefined>, "">, v.TransformAction<string, boolean>]> (+20 overloads)
export pipeAdds a pipeline to a schema, that can validate and transform its input.
schema The root schema.
item1 The first pipe item.
A schema with a pipeline.
(
			vimport v.optional(alias) optional<v.StringSchema<undefined>, "">(wrapped: v.StringSchema<undefined>, default_: ""): v.OptionalSchema<v.StringSchema<undefined>, ""> (+1 overload)
export optionalCreates an optional schema.
wrapped The wrapped schema.
default_ The default value.
An optional schema.
(vimport v.string(alias) string(): v.StringSchema<undefined> (+1 overload)
export stringCreates a string schema.
A string schema.
(), ''),
			vimport v.transform(alias) transform<string, boolean>(operation: (input: string) => boolean): v.TransformAction<string, boolean>
export transformCreates a custom transformation action.
operation The transformation operation.
A transform action.
((str(parameter) str: string) => str(parameter) str: string !== '')
		)
	}
});

Because this variable is static, the <DebugOverlay> component shown here will be excluded from the JavaScript bundle unless SHOW_DEBUG_OVERLAY is truthy:

<script>
	import { SHOW_DEBUG_OVERLAY } from '$app/env/public';
	import DebugOverlay from '#lib/components/DebugOverlay.svelte';
</script>

{#if SHOW_DEBUG_OVERLAY}
	<DebugOverlay />
{/if}

But if the variable is set before building the app...

SHOW_DEBUG_OVERLAY=true npm run build

...then the component will be included and shown.

Documenting variables

You can document the purpose of an environment variable by adding a description:

src/env

import { defineEnvVars(alias) function defineEnvVars<T extends Record<string, EnvVarConfig<any>>>(variables: T): DefinedEnvVars<T>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference } from '@sveltejs/kit/env';

export const variablesconst variables: DefinedEnvVars<{
    CACHE_TTL_SECONDS: {
        description: string;
    };
}> = defineEnvVars(alias) defineEnvVars<{
    CACHE_TTL_SECONDS: {
        description: string;
    };
}>(variables: {
    CACHE_TTL_SECONDS: {
        description: string;
    };
}): DefinedEnvVars<{
    CACHE_TTL_SECONDS: {
        description: string;
    };
}>
import defineEnvVarsUtility for defining environment variables,
which are made available via $app/env/public and $app/env/private.
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';

export const variables = defineEnvVars({
	API_URL: {
		schema: v.pipe(v.string(), v.url())
	},
	PORT: {
		schema: (value) => {
			if (value === undefined) return 3000;
			const port = Number(value);
			if (!Number.isInteger(port)) throw new Error('PORT must be an integer');
			return port;
		}
	}
});reference({
	CACHE_TTL_SECONDS(property) CACHE_TTL_SECONDS: {
    description: string;
}: {
		description(property) description: string: 'How long to cache responses, in seconds'
	}
});

Hovering over CACHE_TTL_SECONDS in your app code will show the description.

Edit this page on GitHub llms.txt

previous next

Remote functions Building your app