Load Functions

/**
 * Universal load function that runs on server and client
 * Defined in +page.ts or +layout.ts files
 */
type Load<
  Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
  Data extends Record<string, unknown> | null = Record<string, any> | null,
  ParentData extends Record<string, any> = Record<string, any>,
  OutputData extends Record<string, any> | void = Record<string, any> | void,
  RouteId extends string | null = string | null
> = (event: LoadEvent<Params, Data, ParentData, RouteId>) => OutputData | Promise<OutputData>;

interface LoadEvent<
  Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
  Data extends Record<string, unknown> | null = Record<string, any> | null,
  ParentData extends Record<string, any> = Record<string, any>,
  RouteId extends string | null = string | null
> {
  fetch: typeof fetch;
  params: Params;
  route: { id: RouteId };
  url: URL;
  /**
   * Contains the data returned by the route's server load function (in +layout.server.js or +page.server.js), if any.
   */
  data: Data;
  /**
   * Returns data from parent +layout.js load functions.
   */
  parent(): Promise<ParentData>;
  depends(...deps: Array<`${string}:${string}`>): void;
  untrack<T>(fn: () => T): T;
  setHeaders(headers: Record<string, string>): void;
  tracing: {
    enabled: boolean;
    root: Span;
    current: Span;
  };
}

// src/routes/blog/[slug]/+page.ts
import type { Load } from './$types';

export const load: Load = async ({ fetch, params }) => {
  const response = await fetch(`/api/posts/${params.slug}`);
  const post = await response.json();

  return { post };
};

// Using parent data
export const load: Load = async ({ parent, fetch }) => {
  const { user } = await parent();
  const posts = await fetch(`/api/users/${user.id}/posts`).then(r => r.json());

  return { posts };
};

// Explicit dependencies for invalidation
export const load: Load = async ({ fetch, depends }) => {
  depends('app:posts');

  const posts = await fetch('/api/posts').then(r => r.json());
  return { posts };
};

// Untrack specific reads to prevent reactivity
export const load: Load = async ({ url, untrack }) => {
  const filter = url.searchParams.get('filter');
  // This won't trigger rerun when untracked param changes
  const stable = untrack(() => url.searchParams.get('stable'));

  return { filter, stable };
};

/**
 * Server-only load function with access to cookies, locals, and request
 * Defined in +page.server.ts or +layout.server.ts files
 */
type ServerLoad<
  Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
  ParentData extends Record<string, any> = Record<string, any>,
  OutputData extends Record<string, any> | void = Record<string, any> | void,
  RouteId extends string | null = string | null
> = (event: ServerLoadEvent<Params, ParentData, RouteId>) => OutputData | Promise<OutputData>;

interface ServerLoadEvent<
  Params extends Partial<Record<string, string>> = Partial<Record<string, string>>,
  ParentData extends Record<string, any> = Record<string, any>,
  RouteId extends string | null = string | null
> extends RequestEvent<Params, RouteId> {
  /**
   * Returns data from parent +layout.server.js load functions.
   */
  parent(): Promise<ParentData>;
  /**
   * Declares that the load function has a dependency on one or more URLs or custom identifiers.
   */
  depends(...deps: string[]): void;
  /**
   * Opt out of dependency tracking for everything synchronously called within the callback.
   */
  untrack<T>(fn: () => T): T;
  /**
   * Access to spans for tracing (available when tracing is enabled).
   */
  tracing: {
    enabled: boolean;
    root: Span;
    current: Span;
  };
}

// src/routes/dashboard/+page.server.ts
import { error } from '@sveltejs/kit';
import type { ServerLoad } from './$types';

export const load: ServerLoad = async ({ locals, cookies }) => {
  if (!locals.user) {
    error(401, 'Must be logged in');
  }

  const preferences = cookies.get('preferences');

  return {
    user: locals.user,
    preferences: preferences ? JSON.parse(preferences) : null
  };
};

// Set response headers
export const load: ServerLoad = async ({ setHeaders, fetch }) => {
  const data = await fetch('/api/data').then(r => r.json());

  setHeaders({
    'Cache-Control': 'public, max-age=3600'
  });

  return { data };
};

// Access platform-specific context (e.g., Cloudflare)
export const load: ServerLoad = async ({ platform }) => {
  const kv = platform?.env?.MY_KV_NAMESPACE;
  const value = await kv?.get('key');

  return { value };
};

// Get client IP address
export const load: ServerLoad = async ({ getClientAddress }) => {
  const ip = getClientAddress();
  console.log('Request from:', ip);

  return {};
};

// Return data object
type LoadOutput = Record<string, any> | void;

// Returned data is automatically serialized and passed to page
// Supports: JSON-serializable data, Promises, nested objects

// Return plain data
export const load = async () => {
  return {
    title: 'My Page',
    count: 42,
    items: ['a', 'b', 'c']
  };
};

// Return promises (will be awaited)
export const load = async ({ fetch }) => {
  return {
    posts: fetch('/api/posts').then(r => r.json()),
    users: fetch('/api/users').then(r => r.json())
  };
};

// Return void (no data)
export const load = async ({ depends }) => {
  depends('app:reload');
  // No return statement or return nothing
};

interface Cookies {
  get(name: string, opts?: CookieParseOptions): string | undefined;
  getAll(opts?: CookieParseOptions): Array<{ name: string; value: string }>;
  set(name: string, value: string, opts?: CookieSerializeOptions): void;
  delete(name: string, opts?: CookieSerializeOptions): void;
  serialize(name: string, value: string, opts?: CookieSerializeOptions): string;
}