Skip to content

SvelteKit

Archil.Website.SvelteKit deploys a SvelteKit app to an Archil sandbox, with the Node adapter injected; prerendered pages are served first. The site is the program of its own sandbox, on port 3000, at a public https://3000-…archil.app URL. A stopped sandbox starts again on the next request.

Install

Section titled “Install”

The build integration is not bundled with alchemy. Install @alchemy.run/frontend-frameworks; the resource loads its /sveltekit and /sveltekit/node exports from your project at deploy time. It is only used at build time, so a dev dependency is enough:

Terminal window
pnpm add -D https://pkg.alchemy.run/@alchemy.run/frontend-frameworks/pr:2930:d8eb8a5

Configure SvelteKit

Section titled “Configure SvelteKit”

Your project’s vite.config.ts loads natively — your Vite plugins and the kit options in your sveltekit(...) call all apply as usual. Alchemy injects its Node adapter (replacing any adapter you declare, with a warning), so a fresh SvelteKit project deploys as-is. Deploy-specific kit overrides can also be passed via the kit prop, which merges over your sveltekit(...) options — see Kit options below. A project without a vite.config.* works too: the resource falls back to a fully programmatic build.

Declare the Website

Section titled “Declare the Website”

Declare the site as a module-level const:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";


export const Website = Archil.Website.SvelteKit("Website");

sandbox sizes the site’s sandbox and sets its image, timeouts, disks and network policy:

alchemy.run.ts
export const Website = Archil.Website.SvelteKit("Website", {
  sandbox: { vcpuCount: 2, memSizeMiB: 4096, idleTtlSeconds: 600 },
});

Add it to the Stack

Section titled “Add it to the Stack”

Yield the site from your Stack and return its URL:

alchemy.run.ts
import * as Archil from "@alchemy.run/archil";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";


export const Website = Archil.Website.SvelteKit("Website");


export default Alchemy.Stack(
  "MySvelteKitSite",
  {
    providers: Archil.providers(),
    state: Alchemy.localState(),
  },
  Effect.gen(function* () {
    const site = yield* Website;
    return { url: site.url };
  }),
);

Run alchemy deploy. url is the site’s https://3000-…archil.app URL. site.sandbox is the sandbox behind it, and undefined under alchemy dev.

See examples/archil-website-sveltekit for the checked-in example.

Add environment variables

Section titled “Add environment variables”

Process environment is a top-level env map:

alchemy.run.ts
export const Website = Archil.Website.SvelteKit("Website", {
  env: {
    GREETING: "Hello from alchemy",
    API_BASE: "https://api.example.com",
  },
});

The values are copied onto process.env before the build (and the dev server) and onto the program at deploy time, so server code reads the same keys in both modes.

Read the environment in server code

Section titled “Read the environment in server code”

The Kit server runs in Node in the sandbox, so server routes read the environment from process.env (or kit’s $env/dynamic/private, which is initialized from it):

src/routes/+page.server.ts
export const load = () => {
  return { greeting: process.env.GREETING ?? "hello" };
};

Kit options

Section titled “Kit options”

Since kit v3 there is no svelte.config.js — kit options live in the sveltekit(...) call in your vite.config.ts, which loads natively:

vite.config.ts
import { sveltekit } from "@sveltejs/kit/vite";
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";


export default defineConfig({
  plugins: [
    tailwindcss(),
    sveltekit({
      prerender: { handleHttpError: "warn" },
    }),
  ],
});

The kit prop on the resource is a deploy-time override layer merged over those options (the override wins). It must be JSON-serializable:

alchemy.run.ts
export const Website = Archil.Website.SvelteKit("Website", {
  kit: {
    paths: { base: "/docs" },
  },
});

Don’t set kit.adapter — Alchemy injects its Node adapter (an adapter declared in your sveltekit(...) call is replaced with a warning).

Local dev

Section titled “Local dev”
Terminal window
bun alchemy dev

alchemy dev runs SvelteKit’s own Vite dev server — Node SSR with full HMR — instead of deploying; site.url is the local address and no Archil resources are created (sandbox is undefined). Wrap the site in Alchemy.remote() to deploy the live Server even during dev.

Where next

Section titled “Where next”