Learn SvelteKit - Configuration & Runtime Config

#Introduction

A good application runs on clear configuration: how much may be prerendered, on which platform it's deployed, and how it distinguishes the development environment from production. Episode 8 covers SvelteKit's configuration layers comprehensively.

One application should be able to run on a local machine, in staging, and in production without changing code. The key is separating configuration values from logic, and choosing the right visibility level for each value — some are safe to expose to the browser, others are server-only.

After this episode, you'll understand the role of each config file, how to use environment variables without leaking secrets, and how adapters determine the shape of the build output.

#svelte.config.js and Runtime Configuration

#The Hub of SvelteKit Configuration

The svelte.config.js file is the main gateway of configuration. All kit options are defined here: adapter, aliases, prerender, csrf, env, and more.

Complete svelte.config.js

import adapter from "@sveltejs/adapter-node";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
 
const config = {
    preprocess: vitePreprocess(),
    kit: {
        adapter: adapter(),
        alias: {
            "@komponen": "src/lib/components"
        },
        prerender: {
            concurrency: 4,
            crawl: true
        }
    }
};
 
export default config;

The kit.alias option adds path aliases available across the whole project, similar to $lib but with a free-form name. The kit.prerender option controls static generation behavior, including the concurrency used while crawling.

#Runtime and Per-Route Configuration

Beyond global configuration, SvelteKit supports per-route configuration through exports from route files: export const prerender = true, export const ssr = false, or export const csr = false. Route-level values override the global configuration, giving you fine-grained control page by page.

#Environment Variables and the $env Module

#Three Visibility Types

SvelteKit provides a dedicated module for environment variables. Access them through this module — not process.env directly — so the substitution happens safely at build time.

Reading environment variables

import { API_KEY } from "$env/static/private";
import { PUBLIC_BASE_URL } from "$env/static/public";
import { env } from "$env/dynamic/private";
 
export const load = async () => {
    return {
        keyTersedia: Boolean(API_KEY),
        baseUrl: PUBLIC_BASE_URL,
        port: env.PORT
    };
};

• $env/static/private — read at build time, server only.
• $env/static/public — read at build time, safe for the browser.
• $env/dynamic/private — read at runtime, server only.
• $env/dynamic/public — read at runtime, safe for the browser.

#Important Rules

Public variables must be prefixed with PUBLIC_ to be accessible from the public modules. Private variables imported into client code will cause a build error — SvelteKit's built-in protection so secrets never reach the browser. Store the real values in .env and .env.example files, and leave .env ignored by git.

#Adapters and Deployment Targets

#The Role of an Adapter

An adapter determines the shape of the build output: static files, a Node server, serverless functions, or edge workers. SvelteKit produces the same code, and the adapter tailors the output to the target platform.

npm install -D @sveltejs/adapter-vercel

Then change svelte.config.js to use that adapter. Common adapters:

• adapter-auto — chooses automatically based on the environment.
• adapter-node — a standalone Node server for self-hosting or Docker.
• adapter-vercel — serverless and edge functions on Vercel.
• adapter-netlify — Netlify functions.
• adapter-cloudflare — Cloudflare Pages and Workers.

The adapter choice affects available features, such as ISR on Vercel or edge caching on Cloudflare. Choose your adapter before deciding your deployment architecture.

#Feature Flags and Build Environment

#Different Builds with Variables

Static variables are inlined at build time: PUBLIC_ values are frozen into the bundle. This way, different builds — development, staging, production — can be produced from different variables without changing code.

PUBLIC_FEATURE_AI=true npm run build
PUBLIC_FEATURE_AI=false npm run build

#Feature Flag Strategy

To decide which features are active without writing branches in many places, collect the flags in a single configuration module:

Feature flags module

import { env } from "$env/dynamic/private";
 
export const flags = {
    aiSearch: env.FEATURE_AI_SEARCH === "true",
    darkMode: env.FEATURE_DARK_MODE !== "false"
};

Feature flags keep the on/off decision for features in one place. For changes that must happen without a rebuild, use $env/dynamic, which is read at runtime. For values that are safe to expose to the client, use the PUBLIC_ prefix with the public dynamic module.

#Closing

Key takeaways:

• svelte.config.js centrally manages adapters, aliases, and kit options; per-route exports give fine-grained control.
• The $env module provides environment variable access with static or dynamic, public or private visibility.
• Private variables imported into the client are rejected by SvelteKit at build time.
• The adapter determines the output shape and deployment platform; choose it before deciding your architecture.
• PUBLIC_ variables are inlined at build time and can distinguish environments without changing code.
• Centralized feature flags make feature activation decisions easy to manage and audit.

In the next episode we discuss assets, images & static content: static assets in the static directory, image optimization and responsive images, sourcing content from Markdown and MDX, plus caching and build-time optimizations.