Svelte Shadcn Blocks

SvelteKit provides two types of load functions. Choosing the correct one is critical for security and data serialization.

+page.server.ts (Server-only)

Use this when you need to:

• Access secrets or credentials (e.g., API keys from $env/static/private).
• Connect to a database.
• Call server-only APIs.
• Execute sensitive business logic.

+page.js (Universal)

Use this when you need to:

• Access public APIs.
• Return non-serializable data (e.g., functions, classes, or DOMParser).
• Benefit from client-side caching.

Warning: Never use +page.js for secrets, as this code runs in the browser and will expose your credentials.

// +page.server.ts - CORRECT for secrets
import { STRIPE_SECRET_KEY } from "$env/static/private";

export const load = async ({ fetch }) => {
  const response = await fetch("https://api.stripe.com/charges", {
    headers: { Authorization: `Bearer ${STRIPE_SECRET_KEY}` },
  });
  return { charges: await response.json() };
};

The Context API allows you to share data down the component tree.

Rules of Usage

• Synchronous Initialization: setContext and getContext must be called synchronously during component initialization. Never call setContext inside an $effect or a callback.
• Reactivity: To make context reactive, pass a $state object or an object containing getters/setters.
• Keys: Avoid using generic strings for keys to prevent collisions. Use a Symbol, a unique string (e.g., "myapp:user"), or an object key.

Checking for Context

Use hasContext(key) to check if a context exists before attempting to retrieve it with getContext(key) to avoid errors.

<!-- Reactive Context Example -->
<script>
  import { setContext } from 'svelte';
  let theme = $state('light');

  setContext('theme', {
    get current() { return theme; },
    toggle() { theme = theme === 'light' ? 'dark' : 'light'; }
  });
</script>

You can use TypeScript union types to restrict props to specific allowed values or to create complex conditional prop structures.

Union Type Props

Use string literal unions to restrict a prop to a specific set of strings (e.g., "primary" | "secondary" | "danger").

Discriminated Union Props

For components that change their entire interface based on a specific prop, use a discriminated union. This allows TypeScript to narrow the available props based on a 'type' or 'kind' field, ensuring that if type is 'link', the href property is required, but if type is 'button', an onclick handler is required instead.

<script lang="ts">
  type Props = 
    | { type: "link"; href: string; children: import('svelte').Snippet } 
    | { type: "button"; onclick: () => void; children: import('svelte').Snippet };

  let props: Props = $props();
</script>

{#if props.type === "link"}
  <a href={props.href}>{@render props.children()}</a>
{:else}
  <button onclick={props.onclick}>{@render props.children()}</button>
{/if}

Svelte 5 allows you to define shared, reactive state outside of components using runes in .svelte.js or .svelte.ts files. This enables a centralized state management pattern that can be imported into any component.

Implementation Patterns

1. Shared Counter (Simple State)

Export a $state object and associated functions to manipulate it.

2. Object State with Getters

To expose derived properties or controlled access to state, use a plain object with get and set accessors that wrap a private $state object.

3. Reactive Class Pattern

Encapsulate complex state and logic within a class using $state for properties. Use getters for derived logic (e.g., filtering lists).

Important Constraints

• File Extensions: Shared state files MUST use .svelte.js or .svelte.ts.
• Module Scope: Do not use $derived in the module scope; use standard JavaScript get accessors instead.
• SSR: Avoid initializing browser-only state at the module level to prevent issues during Server-Side Rendering.

// counter.svelte.ts
export const counter = $state({ count: 0 });

export function increment() {
  counter.count++;
}

// user.svelte.ts
const state = $state({ firstName: "", lastName: "", email: "" });
export const user = {
  get firstName() { return state.firstName; },
  set firstName(v) { state.firstName = v; },
  get fullName() { return `${state.firstName} ${state.lastName}`; }
};

// todo.svelte.ts
class TodoStore {
  items = $state([]);
  filter = $state("all");
  get filtered() {
    return this.items.filter(t => t.done);
  }
}
export const todos = new TodoStore();

In SvelteKit, server-side code is shared across requests. Using module-level variables or global stores to hold user-specific data will cause data to leak between different users.

The Golden Rules of SSR Safety

1. No module-level let variables for user data: Variables declared outside the load function in +page.server.ts are singletons shared by all users.
2. No global $state for user data: Global stores initialized on the server will persist across requests.
3. Use event.locals: Pass user-specific data from hooks.server.ts into event.locals, then return it from your load functions.
4. Use Context for Component Trees: For deep component trees, use setContext in a layout to provide data safely.
5. Client-only state: If you must use a global store, ensure it only initializes or operates when browser is true.

// CORRECT: Use locals to avoid sharing state between users
// hooks.server.ts
export const handle = async ({ event, resolve }) => {
  event.locals.user = await authenticate(event);
  return resolve(event);
};

// +page.server.ts
export const load = async ({ locals }) => {
  return { user: locals.user }; // Each request gets its own data
};

Testing Svelte 5 components requires specific Vitest configurations depending on your preferred environment.

Option 1: Vitest Browser Mode (Recommended)

Provides a more realistic testing environment by running tests in a real browser via Playwright.

Option 2: JSDOM

Uses a simulated DOM environment. This is faster but less accurate for complex browser behaviors.

Common Testing Tasks

• Props: Pass props using the props option in render.
• Callbacks: Use vi.fn() to create mock functions and verify they are called.
• Async: Use waitFor from @testing-library/svelte to handle components that load data asynchronously.

// vitest.config.ts (Browser Mode)
import { defineConfig } from "vitest/config";
import { svelte } from "@sveltejs/vite-plugin-svelte";

export default defineConfig({
  plugins: [svelte()],
  test: {
    browser: {
      enabled: true,
      provider: "playwright",
      name: "chromium",
    },
  },
});

// Basic Component Test Example
import { render, screen, fireEvent } from "@testing-library/svelte";
import { expect, test } from "vitest";
import Counter from "./Counter.svelte";

test("increments count when clicked", async () => {
  render(Counter);
  const button = screen.getByRole("button");
  await fireEvent.click(button);
  expect(button).toHaveTextContent("Count: 1");
});

In Svelte 5, the $props() rune requires specific TypeScript patterns. While inline typing is possible, using an interface is the recommended approach for clarity and maintainability.

Basic Props Typing

Use an interface to define the shape of your props, including optional properties with ? and default values during destructuring.

Children and Snippets Typing

To type Svelte snippets, import the Snippet type from svelte. Snippets can be required or optional, and can accept parameters defined as a tuple.

Callback Props Typing

Define callback functions within your props interface using standard TypeScript function signatures (e.g., (value: string) => void).

Rest Props with HTML Attributes

To allow a component to accept all standard HTML attributes (like class, id, etc.), extend the appropriate type from svelte/elements (e.g., HTMLButtonAttributes). Use the spread operator (...rest) to pass these attributes to the underlying element.

Input Element Props

When creating custom input components, extend HTMLInputAttributes. It is common to use Omit<HTMLInputAttributes, "value"> if you intend to redefine the value prop (for example, to make it $bindable).

<script lang="ts">
  interface Props {
    name: string;
    count?: number;
    disabled?: boolean;
  }

  let { name, count = 0, disabled = false }: Props = $props();
</script>