Back to Details

sveltekit-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

When to use

适用场景

Use this skill when working with SvelteKit or Svelte 5 code. AI agents are trained on Svelte 4 patterns and frequently generate outdated code using stores, reactive declarations, and export let. This skill enforces Svelte 5 runes, load functions, and form actions.
当你处理SvelteKit或Svelte 5代码时使用本技能。AI Agent通常基于Svelte 4模式训练，经常生成使用stores、响应式声明和export let的过时代码。本技能强制使用Svelte 5的Runes、load函数和表单操作。

Critical Rules

核心规则

1. Use Svelte 5 runes - never Svelte 4 stores or reactive declarations

1. 使用Svelte 5 Runes - 绝不使用Svelte 4的stores或响应式声明

Wrong (agents do this):
svelte
<script>
  import { writable, derived } from 'svelte/store';
  let count = writable(0);
  $: doubled = $count * 2;
  $: if (count > 5) alert('too high');
</script>
<p>{$count}</p>
Correct:
svelte
<script>
  let count = $state(0);
  let doubled = $derived(count * 2);
  $effect(() => {
    if (count > 5) alert('too high');
  });
</script>
<p>{count}</p>
Why: Svelte 5 runes ($state, $derived, $effect) replace stores and $: syntax. Agents default to Svelte 4 patterns.
错误示例（Agent常这么写）：
svelte
<script>
  import { writable, derived } from 'svelte/store';
  let count = writable(0);
  $: doubled = $count * 2;
  $: if (count > 5) alert('too high');
</script>
<p>{$count}</p>
正确示例：
svelte
<script>
  let count = $state(0);
  let doubled = $derived(count * 2);
  $effect(() => {
    if (count > 5) alert('too high');
  });
</script>
<p>{count}</p>
原因： Svelte 5的Runes（$state、$derived、$effect）替代了stores和$:语法。Agent默认使用Svelte 4模式。

2. Use $state for reactive state - not let with reactive assignments

2. 使用$state定义响应式状态 - 不要用普通let加响应式赋值

Wrong:
svelte
<script>
  let count = 0;
  count = count + 1;
</script>
Correct:
svelte
<script>
  let count = $state(0);
  count = count + 1;
</script>
Why: In Svelte 5, reactivity is opt-in via $state. Plain let is not reactive.
错误示例：
svelte
<script>
  let count = 0;
  count = count + 1;
</script>
正确示例：
svelte
<script>
  let count = $state(0);
  count = count + 1;
</script>
原因： 在Svelte 5中，响应式需要通过$state主动启用。普通let不具备响应式。

3. Use $derived for computed values - not $: reactive declarations

3. 使用$derived定义计算值 - 不要用$:响应式声明

Wrong:
svelte
<script>
  let firstName = $state('John');
  let lastName = $state('Doe');
  $: fullName = `${firstName} ${lastName}`;
</script>
Correct:
svelte
<script>
  let firstName = $state('John');
  let lastName = $state('Doe');
  let fullName = $derived(`${firstName} ${lastName}`);
</script>
Why: $: is Svelte 4. Svelte 5 uses $derived for derivations.
错误示例：
svelte
<script>
  let firstName = $state('John');
  let lastName = $state('Doe');
  $: fullName = `${firstName} ${lastName}`;
</script>
正确示例：
svelte
<script>
  let firstName = $state('John');
  let lastName = $state('Doe');
  let fullName = $derived(`${firstName} ${lastName}`);
</script>
原因： $:是Svelte 4的写法。Svelte 5使用$derived处理派生值。

4. Use $effect for side effects - not $: reactive statements

4. 使用$effect处理副作用 - 不要用$:响应式语句

Wrong:
svelte
<script>
  let count = $state(0);
  $: if (count > 5) console.log('count is high');
</script>
Correct:
svelte
<script>
  let count = $state(0);
  $effect(() => {
    if (count > 5) console.log('count is high');
  });
</script>
Why: $effect runs when dependencies change. $: for side effects is deprecated.
错误示例：
svelte
<script>
  let count = $state(0);
  $: if (count > 5) console.log('count is high');
</script>
正确示例：
svelte
<script>
  let count = $state(0);
  $effect(() => {
    if (count > 5) console.log('count is high');
  });
</script>
原因： $effect会在依赖项变化时执行。使用$:处理副作用已被弃用。

5. Use $props() for component props - not export let

5. 使用$props()定义组件属性 - 不要用export let

Wrong:
svelte
<script>
  export let title = 'Default';
  export let count;
</script>
<h1>{title}</h1>
Correct:
svelte
<script>
  let { title = 'Default', count } = $props();
</script>
<h1>{title}</h1>
Why: export let is Svelte 4. Svelte 5 uses $props().
错误示例：
svelte
<script>
  export let title = 'Default';
  export let count;
</script>
<h1>{title}</h1>
正确示例：
svelte
<script>
  let { title = 'Default', count } = $props();
</script>
<h1>{title}</h1>
原因： export let是Svelte 4的写法。Svelte 5使用$props()。

6. Use $bindable() for two-way binding props

6. 使用$bindable()实现双向绑定属性

Wrong:
svelte
<script>
  let { value } = $props();
</script>
<input bind:value={value} />
Correct:
svelte
<script>
  let { value = $bindable() } = $props();
</script>
<input bind:value={value} />
Why: Props are one-way by default. $bindable() enables bind:value from parent.
错误示例：
svelte
<script>
  let { value } = $props();
</script>
<input bind:value={value} />
正确示例：
svelte
<script>
  let { value = $bindable() } = $props();
</script>
<input bind:value={value} />
原因： 属性默认是单向绑定。$bindable()允许从父组件使用bind:value。

7. Use load functions (+page.server.ts) for data fetching - not onMount fetch

7. 使用load函数（+page.server.ts）获取数据 - 不要在onMount中fetch

Wrong:
svelte
<script>
  import { onMount } from 'svelte';
  let data = $state(null);
  onMount(async () => {
    data = await fetch('/api/users').then(r => r.json());
  });
</script>
{#if data}{data.name}{/if}
Correct:
typescript
// +page.server.ts
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ fetch }) => ({
  data: await fetch("/api/users").then((r) => r.json()),
});
svelte
<!-- +page.svelte -->
<script>
  let { data } = $props();
</script>
{#if data}{data.name}{/if}
Why: Load runs on server for SSR, avoids loading flicker, and integrates with SvelteKit routing.
错误示例：
svelte
<script>
  import { onMount } from 'svelte';
  let data = $state(null);
  onMount(async () => {
    data = await fetch('/api/users').then(r => r.json());
  });
</script>
{#if data}{data.name}{/if}
正确示例：
typescript
// +page.server.ts
import type { PageServerLoad } from "./$types";
export const load: PageServerLoad = async ({ fetch }) => ({
  data: await fetch("/api/users").then((r) => r.json()),
});
svelte
<!-- +page.svelte -->
<script>
  let { data } = $props();
</script>
{#if data}{data.name}{/if}
原因： Load函数在服务器端执行以实现SSR，避免加载闪烁，并且与SvelteKit路由集成。

8. Use form actions for mutations - not API routes for form submissions

8. 使用表单操作处理修改 - 不要用API路由处理表单提交

Wrong:
svelte
<form on:submit={async (e) => {
  e.preventDefault();
  await fetch('/api/login', { method: 'POST', body: new FormData(e.target) });
  goto('/dashboard');
}}>
Correct:
typescript
// +page.server.ts
import type { Actions } from "./$types";
export const actions = {
  default: async ({ request, cookies }) => {
    const data = await request.formData();
    // validate, authenticate, set cookie
    return { type: "redirect", location: "/dashboard" };
  },
};
svelte
<form method="POST" use:enhance>
Why: Form actions enable progressive enhancement, work without JS, and avoid client-side fetch boilerplate.
错误示例：
svelte
<form on:submit={async (e) => {
  e.preventDefault();
  await fetch('/api/login', { method: 'POST', body: new FormData(e.target) });
  goto('/dashboard');
}}>
正确示例：
typescript
// +page.server.ts
import type { Actions } from "./$types";
export const actions = {
  default: async ({ request, cookies }) => {
    const data = await request.formData();
    // 验证、认证、设置cookie
    return { type: "redirect", location: "/dashboard" };
  },
};
svelte
<form method="POST" use:enhance>
原因： 表单操作支持渐进式增强，无需JS也能工作，避免客户端fetch的样板代码。

9. Use +layout.server.ts for shared layout data

9. 使用+layout.server.ts共享布局数据

Wrong:
svelte
<!-- Multiple pages each fetch user -->
<script>
  let user = $state(null);
  onMount(() => fetchUser().then(u => user = u));
</script>
Correct:
typescript
// +layout.server.ts
export const load = async ({ locals }) => ({
  user: locals.user,
});
Why: Layout load runs once, data is available to all child pages. No duplicate fetches.
错误示例：
svelte
<!-- 多个页面各自获取用户信息 -->
<script>
  let user = $state(null);
  onMount(() => fetchUser().then(u => user = u));
</script>
正确示例：
typescript
// +layout.server.ts
export const load = async ({ locals }) => ({
  user: locals.user,
});
原因： 布局的load函数只执行一次，数据可用于所有子页面。避免重复请求。

10. Use +error.svelte for error pages

10. 使用+error.svelte处理错误页面

Correct:
svelte
<!-- +error.svelte -->
<script>
  let { status, message } = $props();
</script>
<h1>{status}</h1>
<p>{message}</p>
Why: SvelteKit uses +error.svelte to render load/action errors. Use it instead of try/catch in every page.
正确示例：
svelte
<!-- +error.svelte -->
<script>
  let { status, message } = $props();
</script>
<h1>{status}</h1>
<p>{message}</p>
原因： SvelteKit使用+error.svelte渲染load/操作错误。不要在每个页面中使用try/catch，改用它。

11. Use +page.ts for universal load (server and client)

11. 使用+page.ts实现通用加载（服务器端和客户端）

When data is needed on both server and client (e.g. from $app/stores or browser APIs), put logic in +page.ts. Use +page.server.ts when data is server-only.
当数据同时需要在服务器端和客户端使用时（例如来自$app/stores或浏览器API），将逻辑放在+page.ts中。仅当数据仅在服务器端使用时，使用+page.server.ts。

12. Use hooks.server.ts for middleware (auth, redirects)

12. 使用hooks.server.ts作为中间件（认证、重定向）

Correct:
typescript
// hooks.server.ts
export const handle = async ({ event, resolve }) => {
  event.locals.user = await getUser(event);
  if (!event.locals.user && event.url.pathname.startsWith("/dashboard")) {
    return redirect(302, "/login");
  }
  return resolve(event);
};
Why: Handle runs before every request. Use for auth, redirects, and setting locals.
正确示例：
typescript
// hooks.server.ts
export const handle = async ({ event, resolve }) => {
  event.locals.user = await getUser(event);
  if (!event.locals.user && event.url.pathname.startsWith("/dashboard")) {
    return redirect(302, "/login");
  }
  return resolve(event);
};
原因： Handle函数在每个请求前执行。用于认证、重定向和设置locals。

13. Use $app/stores sparingly - prefer load function data

13. 谨慎使用$app/stores - 优先使用load函数的数据

Prefer passing data via load props. Use $page, $navigating, etc. only when you need client-side routing state.
优先通过load属性传递数据。仅当需要客户端路由状态时，才使用$page、$navigating等。

14. Use snippet blocks for reusable template chunks (Svelte 5)

14. 使用代码片段块复用模板片段（Svelte 5）

Wrong:
svelte
<script>
  export let slots;
</script>
{#if slots.header}<slot name="header" />{/if}
Correct:
svelte
<script>
  let { header = @render(() => {}) } = $props();
</script>
{@render header()}
Why: Svelte 5 snippets replace slot-based composition with @render and snippet props.
错误示例：
svelte
<script>
  export let slots;
</script>
{#if slots.header}<slot name="header" />{/if}
正确示例：
svelte
<script>
  let { header = @render(() => {}) } = $props();
</script>
{@render header()}
原因： Svelte 5的代码片段通过@render和片段属性替代了基于slot的组合方式。

Patterns

推荐模式

  • Page data: +page.server.ts load returns object, +page.svelte receives via $props() with 
    data
  • Form with enhance: 
    method="POST"
    and 
    use:enhance
    from 
    $app/forms
  • Streaming: Return promises from load without await; use 
    {#await data.promise}
    in template
  • TypeScript: Use 
    import type { PageServerLoad, PageProps } from './$types'
  • 页面数据：+page.server.ts的load函数返回对象，+page.svelte通过$props()的
    data
    接收
  • 带enhance的表单：使用
    method="POST"
    和来自
    $app/forms
    的
    use:enhance
  • 流式加载：从load函数返回Promise而不使用await；在模板中使用
    {#await data.promise}
  • TypeScript：使用
    import type { PageServerLoad, PageProps } from './$types'

Anti-Patterns

反模式

  • Do not use writable, readable, derived, get from svelte/store
  • Do not use $: for derivations or side effects
  • Do not use export let for props
  • Do not fetch in onMount when data is needed for SSR
  • Do not create +server.ts API routes just for form POST handling
  • Do not use bind:value with a prop unless the prop is $bindable()
  • 不要使用svelte/store中的writable、readable、derived、get
  • 不要使用$:处理派生值或副作用
  • 不要使用export let定义属性
  • 当数据需要用于SSR时，不要在onMount中fetch
  • 不要只为处理表单POST请求创建+server.ts API路由
  • 除非属性是$bindable()，否则不要对属性使用bind:value