Install

Installation has three parts: install the package, add the Svelte preprocessor, and add the Vite plugin. If you plan to use remote functions, also enable SvelteKit's remote function flag.

When to use this

Use this page when starting a new SvelteKit app or when adding Effect support to an existing app. The setup is intentionally small, but the Svelte preprocessor is required for component yield*.

Minimal working example

pnpm add svelte-effect-runtime effect

Wire the Svelte preprocessor in svelte.config.js:

import adapter from "@sveltejs/adapter-auto";
import { preprocess } from "svelte-effect-runtime";

const config = {
  compilerOptions: {
    experimental: {
      async: true,
    },
  },
  kit: {
    adapter: adapter(),
  },
  preprocess: [preprocess()],
};

export default config;

Then add the Vite plugin before sveltekit():

import { sveltekit } from "@sveltejs/kit/vite";
import { defineConfig } from "vite";
import { effect } from "svelte-effect-runtime";

export default defineConfig({
  plugins: [effect(), sveltekit()],
});

Enable remote functions in the same Svelte config when you use Query, Command, Form, or Prerender:

import adapter from "@sveltejs/adapter-auto";
import { preprocess } from "svelte-effect-runtime";

const config = {
  compilerOptions: {
    experimental: {
      async: true,
    },
  },
  kit: {
    adapter: adapter(),
    experimental: {
      remoteFunctions: true,
    },
  },
  preprocess: [preprocess()],
};

export default config;

Realistic variant

Many apps start with the default runtime and add custom services later:

import { ClientRuntime } from "svelte-effect-runtime";
import { Layer } from "effect";

export const init = () => {
  ClientRuntime.make(Layer.empty);
};

SER emits Svelte async rendering expressions for component yield*, so compilerOptions.experimental.async is required for component integration.

Put client runtime setup in src/hooks.client.ts and server runtime setup in src/hooks.server.ts.

Why both hooks are needed

The Svelte preprocessor lowers <script effect> and markup yield* before Svelte parses the component. The Vite plugin handles server import rewrites and wraps SvelteKit's generated remote client exports in Effect-returning adapters.

Common mistakes

• Forgetting preprocess: [preprocess()] in svelte.config.js.
• Placing effect() after sveltekit() in the Vite plugin list.
• Enabling remote functions only after writing remote files, then debugging missing routes.
• Installing the runtime package but forgetting the peer Effect package in package managers that do not hoist it for you.
• Forgetting to rebuild or reinstall the language server or VS Code extension after changing syntax transforms.

Related pages

• Mental model
• Vite plugin reference
• Client runtime