Add post: Environment variables in SvelteKit

Fixes #985

Author: maiertech

src/routes/api/posts/2025/+server.ts

@@ -1,13 +1,14 @@
 import { resolvePost } from '$lib/server/resolvers';
 import postDroppingRequestsInSvelteKit from '$posts/(2025)/dropping-requests-in-sveltekit/meta';
+import postEnvVarsInSvelteKit from '$posts/(2025)/environment-variables-in-sveltekit/meta';
 import { json } from '@sveltejs/kit';
 import type { RequestHandler } from './$types';
 
 export const prerender = true;
 
 export const GET: RequestHandler = async (event) => {
 	// Sort order: latest first.
-	const posts = [postDroppingRequestsInSvelteKit];
+	const posts = [postEnvVarsInSvelteKit, postDroppingRequestsInSvelteKit];
 
 	const resolvedPosts = await Promise.all(
 		posts.map((post) => {

src/routes/api/tags/[id]/tags.ts

@@ -73,6 +73,11 @@ const tags: Tag[] = [
 		label: 'TypeScript',
 		path: '/tags/typescript'
 	},
+	{
+		id: 'vercel',
+		label: 'Vercel',
+		path: '/tags/vercel'
+	},
 	{
 		id: 'vscode',
 		label: 'VS Code',

src/routes/posts/(2025)/environment-variables-in-sveltekit/+page.server.ts

@@ -0,0 +1,10 @@
+import { resolvePost } from '$lib/server/resolvers';
+import type { PageServerLoad } from './$types';
+import meta from './meta';
+
+export const load: PageServerLoad = async (event) => {
+	const post = await resolvePost({ postMeta: meta, event });
+	const { title, description, ogImageUrl } = post;
+
+	return { post, seo: { title, description, ogImageUrl } };
+};

src/routes/posts/(2025)/environment-variables-in-sveltekit/+page.svx

@@ -0,0 +1,83 @@
+Much has been written about environment variables in SvelteKit. Yet, I was often unsure which of the
+four options SvelteKit offers for environment variables is the right one. Until I realized that you
+have to put the four options into the context of your hosting environment to make sense.
+
+Let's first look at where in a SvelteKit app you might need environment variables:
+
+1. **On the server:** Some of your SvelteKit code will run on a server, be it in a serverless
+   function on Vercel or on a Node.js server, possibly inside a Docker container. The server waits
+   for requests, processes them, and returns a response. The code on the server is considered
+   secure, which means that its code and the environment cannot be accessed or inspected. That's why
+   you can store secrets on a server, either in environment variables or baked into the code that
+   runs on the server.
+
+2. **In the JavaScript code that runs in the browser:** When the server sends a response, it adds
+   client-side code that runs in the browser. This highly optimized and bundled code is what creates
+   a great UX for the users of your SvelteKit app. The server can send pre-bundled code containing
+   values from environment variables, or it can dynamically add the values of environment variables
+   into the code that it sends to the browser. In any case, these values must not contain any
+   secrets, because as much as you may try to obfuscate them, they are part of the code shipped to
+   the browser and can be inspected.
+
+3. **During the build step:** When you build your SvelteKit app, the build runs in a safe
+   environment. Either on your development machine (which you hopefully update regularly) or on a
+   build server, for example Vercel or a service like Railway. During the build step, the values of
+   environment variables can be bundled into the code. If a bundle is meant to run on the server
+   only, it can normally contain secrets (with some exceptions). If a bundle is meant to be shipped
+   to the browser, it must not contain any secrets.
+
+Therefore, SvelteKit makes a distinction between environment variables that are secrets, referred to
+as **private variables**, and those that are safe to ship to a browser, referred to as **public
+variables**.
+
+When you are dealing with private variables, you have to be mindful of how you deploy your SvelteKit
+app. If you deploy to Vercel, it's safe to embed private variables code that runs on Vercel. There
+is no way anyone can inspect the deployed serverless functions.
+
+But when you deploy with a Docker container, you have to be careful. If your container is private
+and can never be accessed by anyone, you can safely embed private variables into SvelteKit's server
+code. But if you publish a Docker container to a registry, anyone with access could reverse engineer
+the container and extract the secrets.
+
+With the distinction between public and private variables in mind, let's look at SvelteKit's four
+options for environment variables:
+
+- [`$env/static/public`](https://svelte.dev/docs/kit/$env-static-public): These environment
+  variables start with a configurable prefix, `PUBLIC_`, to signal that they are safe to ship to the
+  browser. They must exist at build time, not runtime. They are baked into the code during the build
+  and cannot be changed at runtime. Environment variables in this category are suitable for pages
+  that are prerendered.
+
+  Example: The public tracking ID of an analytics tool, `PUBLIC_ANALYTICS_ID`.
+
+- [`$env/dynamic/public`](https://svelte.dev/docs/kit/$env-dynamic-public): These environment
+  variables cannot be accessed at build time. Therefore, they are not suitable for pages that are
+  prerendered. On the server, there must be an environment variable prefixed with `PUBLIC_` that can
+  be modified by the server during runtime. You can send this variable to the browser using a load
+  function.
+
+  Example: A variable that triggers maintenance mode on the server, `PUBLIC_MAINTENANCE_MODE=false`.
+
+- [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private): Like its public
+  counterpart, static private variables must exist during the build step and cannot be changed at
+  runtime. SvelteKit will throw an error if you try to import these variables into code that ships
+  to the browser. Any page that uses these variables can be prerendered. Do not use in combination
+  with published Docker containers.
+
+  Example: A private API key, `API_KEY`.
+
+- [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private): These environment
+  variables cannot be accessed during the build and, like their public counterpart, are not suitable
+  for pages that are prerendered. They can be changed at runtime.
+
+  Example: A feature flag for a new feature, `CHAT_FEATURE_FLAG`, so DevOps can turn off the
+  feature without redeploying if they detect a problem.
+
+When I build for Vercel, most of the time I use static private variables with
+`$env/static/private`. Occasionally, I need a static public variable using `$env/static/public`, for
+example, to make a `PUBLIC_ANALYTICS_ID` available client-side.
+
+If I ship a SvelteKit app as a Docker container, I should default to dynamic private variables with
+`$env/dynamic/private`. But this often interferes with prerendering. So, even with Docker, I prefer
+using static environment variables. In a published Docker container, you should skip prerendering
+if it means you risk exposing a secret.

src/routes/posts/(2025)/environment-variables-in-sveltekit/meta.ts

@@ -0,0 +1,11 @@
+import type { PostMeta } from '@maiertech/sveltekit-helpers';
+
+export default {
+	title: 'Environment variables in SvelteKit',
+	author: 'thilo',
+	publishedDate: '2025-08-01',
+	description: 'TODO.',
+	tags: ['svelte', 'vercel'],
+	path: '/posts/environment-variables-in-sveltekit',
+	filepath: 'src/routes/posts/(2025)/environment-variables-in-sveltekit/+page.svx'
+} satisfies PostMeta;