sveltekit-svelte5-tailwind-skill

SvelteKit 2 + Svelte 5 + Tailwind v4 集成技能

此技能为使用 SvelteKit 2 + Svelte 5 + Tailwind CSS v4 技术栈构建现代 Web 应用提供全面指导。

关于此集成技术栈

SvelteKit 2 是一个现代全栈框架，具备以下功能：

• 基于文件的路由和布局
• 服务端渲染（SSR）和静态站点生成（SSG）
• 支持渐进增强的表单操作
• 多种部署适配器（Vercel、Cloudflare、Node、静态）

Svelte 5 引入了全新的响应式系统，具备以下特性：

• Runes：$state()、$derived()、$effect()、$props()
• 简化组件编写
• 更好的 TypeScript 支持
• 使用 Snippets 替代 slots

Tailwind CSS v4 提供：

• CSS 优先的配置
• 全新的 Vite 插件架构
• 更出色的 JIT 性能
• 简化的设置流程

此技能解决的集成难题：

• 配置这三种工具协同工作
• 理解 SSR 环境下的 Svelte 5 runes
• 使用表单操作实现渐进增强
• 在开发和生产环境中加载 CSS
• 在不同平台上部署
• 从早期版本迁移

如何使用此技能

重要：先研究，再实施

当用户要求你使用此技术栈构建内容时：

1. 先研究——搜索文档，了解：

   • SvelteKit 如何处理此用例
   • 适用哪些 Svelte 5 runes 模式
   • 如何使用 Tailwind v4 进行样式设计
   • 应避免哪些常见集成问题

2. 再执行——运用从文档中获得的知识实施解决方案

原因：

• 此集成有特定限制（例如，runes 在 SSR 中无法工作）
• 文档提供了权威的配置指南
• 先研究可以避免需要返工的错误
• 你将实施符合最佳实践的解决方案

工作流：

1. 用户提出请求：“帮我用 SvelteKit/Svelte 5/Tailwind 构建 [功能]”
2. 你按照以下流程搜索文档
3. 你了解推荐的做法
4. 你首次实施即可正确完成解决方案

文档集合

此技能包含两个可搜索的文档集合：

references/（针对问题的指南）

17 份精心整理的指南，解决特定集成难题：

• 设置：getting-started.md、project-setup.md
• 核心概念：svelte5-runes.md、routing-patterns.md、server-rendering.md、data-loading.md
• 表单与样式：forms-and-actions.md、styling-with-tailwind.md、styling-patterns.md
• 部署：deployment-guide.md
• 迁移：migration-svelte4-to-5.md、tailwind-v4-migration.md
• 优化：best-practices.md、performance-optimization.md
• 故障排查：common-issues.md、troubleshooting.md
• 搜索系统：documentation-search-system.md

docs/（完整参考资料）

7 份改编后的文档指南，涵盖完整 API：

• sveltekit-configuration.md - 完整的 svelte.config.js 和 Vite 配置
• svelte5-api-reference.md - 所有 Svelte 5 runes 和模板语法
• tailwind-configuration.md - Tailwind v4 配置选项
• adapters-reference.md - 部署适配器规范
• advanced-routing.md - 高级 SvelteKit 路由模式
• advanced-ssr.md - SSR 钩子、流式传输和优化
• integration-patterns.md - 完整的集成示例

搜索文档

重要：实施前务必先搜索！

此技能采用 5 阶段搜索流程，以便高效查找文档：

阶段 0：发现可用文档

查找所有文档索引：

find . -name "index.jsonl" -type f

预期输出：

• ./references/index.jsonl（17 份针对问题的指南）
• ./docs/index.jsonl（7 份完整参考资料）

抽样查看每个集合，了解其范围：

Read references/index.jsonl with offset: 1, limit: 5
Read docs/index.jsonl with offset: 1, limit: 5

确定与你的查询相关的集合。

阶段 1：加载相关索引

读取所选集合的完整索引文件：

Read references/index.jsonl  # For how-to guides and troubleshooting
Read docs/index.jsonl         # For API reference and configuration

第 2 阶段：分析候选文件

分析摘要，找出 3-4 个最相关的文件：

关于配置的问题 → references/getting-started.md、references/project-setup.md 关于 runes 的问题 → references/svelte5-runes.md、docs/svelte5-api-reference.md 关于表单的问题 → references/forms-and-actions.md、docs/integration-patterns.md 关于样式的问题 → references/styling-with-tailwind.md、docs/tailwind-configuration.md 关于 SSR 的问题 → references/server-rendering.md、docs/advanced-ssr.md 关于部署的问题 → references/deployment-guide.md、docs/adapters-reference.md 关于错误的问题 → references/common-issues.md、references/troubleshooting.md

请考虑：

• 查询意图（如何操作、是什么还是故障排查）
• 集成特定问题还是单个包的问题
• 入门还是进阶主题

第 3 阶段：获取章节详情

对于 3-4 个候选文件，读取其 sections.jsonl 条目：

Read references/sections.jsonl with offset: {index}, limit: 1
Read docs/sections.jsonl with offset: {index}, limit: 1

重要： index.jsonl 中的索引编号 = sections.jsonl 中的行号

分析章节摘要，确定哪些章节与查询相关。

第 4 阶段：读取目标章节

只读取相关章节：

Read references/getting-started.md with offset: 45, limit: 89
Read docs/svelte5-api-reference.md with offset: 120, limit: 65

使用 sections.jsonl 数据中的 offset 和 limit 精确读取。

第 5 阶段：综合并作答

综合多个来源的信息：

1. 直接回答用户的问题
2. 代码示例（完整且可运行）
3. 集成特定注意事项
4. 供进一步阅读的文件引用

文件引用示例：

See: references/svelte5-runes.md:156-245 (Server-Side Constraints)
See: docs/advanced-ssr.md:89-134 (SSR Load Functions)

关于完整的搜索方法和示例，请参阅 references/documentation-search-system.md

快速入门（5 分钟）

如需完整的操作指南，请搜索 references/getting-started.md

基本配置命令：

# 1. Create SvelteKit project
npm create svelte@latest my-app
cd my-app
npm install

# 2. Add Tailwind v4
npm install -D tailwindcss@next @tailwindcss/vite@next

# 3. Configure Vite (vite.config.js)
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';

export default {
  plugins: [
    tailwindcss(),  // MUST be before sveltekit()
    sveltekit()
  ]
};

# 4. Create app.css
@import "tailwindcss";

# 5. Import in root layout (src/routes/+layout.svelte)
<script>
  import '../app.css';
</script>
<slot />

# 6. Verify
npm run dev

关键配置：

• 在 vite.config.js 中，Tailwind 插件必须位于 SvelteKit 插件之前
• 在根目录的 +layout.svelte 中导入 CSS（而不是 app.html）
• Tailwind v4 软件包使用 @next 标签

常见用例

配置与设置 → 搜索：references/getting-started.md、references/project-setup.md → 关键章节：安装、Vite 配置、目录结构

使用 SSR 的 Svelte 5 Runes → 搜索：references/svelte5-runes.md → 关键提示：“服务器端限制”章节——$state() 在 SSR 中不起作用！

表单与渐进式增强 → 搜索：references/forms-and-actions.md → 关键模式：使用手动 enhance() 以兼容 rune

组件样式 → 搜索：references/styling-with-tailwind.md、references/styling-patterns.md → 关键主题：动态类、暗色模式、组件模式

数据加载 → 搜索：references/data-loading.md、docs/advanced-ssr.md → 关键模式：将 load() 数据传递给 rune 状态

部署 → 搜索：references/deployment-guide.md、docs/adapters-reference.md → 特定平台：Vercel、Cloudflare、Node、静态部署

错误故障排查 → 首先搜索：references/common-issues.md（快速修复） → 然后搜索：references/troubleshooting.md（系统化调试）

常见问题与快速修复

CSS 在生产环境中未加载 → 搜索：references/common-issues.md 中的 “CSS Loading Issues” 章节 → 快速检查：Vite 插件顺序、CSS 导入位置

Runes 导致 SSR 错误 → 搜索：references/svelte5-runes.md 中的 “Server-Side Constraints” 章节 → 快速修复：不要在 SSR 组件中使用 $state() 或 $effect()

表单提交后丢失状态 → 搜索：references/forms-and-actions.md 中的 “Handling use:enhance Reactivity” 章节 → 快速修复：使用手动 enhance() 回调

HMR 出现问题 → 搜索：references/common-issues.md 中的 “Hot Module Reload Problems” 章节 → 快速修复：检查 Vite 插件顺序和文件监视设置

Tailwind 类不起作用 → 搜索：references/styling-with-tailwind.md 中的 “Content Detection and Purging” 章节 → 快速修复：检查配置中的内容路径，并使用完整类名

如需系统化故障排查，请参阅 references/troubleshooting.md

集成模式

服务端与客户端组件拆分

<script>
  export let data;
</script>

<ClientCounter initialCount={data.count} />


<script>
  let { initialCount } = $props();
  let count = $state(initialCount);
</script>

渐进增强表单

<script>
  import { enhance } from '$app/forms';
  let { form } = $props();
  let submitting = $state(false);
</script>

<form method="POST" use:enhance={() => {
  submitting = true;
  return async ({ result, update }) => {
    submitting = false;
    await update();
  };
}}>
  
</form>

条件 Tailwind 类

<script>
  let active = $state(false);
</script>


<div class:bg-blue-500={active} class:bg-gray-200={!active}>
  Button
</div>


<div class="bg-{active ? 'blue' : 'gray'}-500">
  Button
</div>

如需查看完整模式，请搜索 docs/integration-patterns.md

最佳实践

搜索 references/best-practices.md，获取以下方面的全面指导：

• 项目组织与架构
• 组件设计模式
• 状态管理策略
• 样式约定
• 性能优化
• 安全注意事项
• 测试策略
• 无障碍指南

迁移指南

在 SvelteKit 中从 Svelte 4 迁移到 Svelte 5 → 搜索：references/migration-svelte4-to-5.md → 重点主题：从 Stores 迁移到 runes、从响应式语句迁移到 $derived、从插槽迁移到片段

从 Tailwind v3 迁移到 v4 → 搜索：references/tailwind-v4-migration.md → 重点主题：CSS 优先配置、Vite 插件、语法变更

性能优化

搜索 references/performance-optimization.md，了解以下内容：

• 包体积优化
• CSS 清除与压缩
• 代码拆分策略
• 图像与字体优化
• 延迟加载模式
• Core Web Vitals 优化
• Lighthouse 评分提升

版本信息

此技能涵盖：

• SvelteKit：2.x（最新稳定版）
• Svelte：5.x（使用 runes）
• Tailwind CSS：4.x（CSS 优先配置）

所有代码示例和模式均已使用这些版本进行测试。

获取帮助

1. 从搜索开始：使用上述 5 阶段搜索流程
2. 查看常见问题：通过 references/common-issues.md 快速解决问题
3. 系统化调试：参阅 references/troubleshooting.md 了解方法
4. 查阅参考资料：针对特定主题的问题指南
5. 查看 API 文档：获取配置详情的全面参考资料

技能结构

sveltekit-svelte5-tailwind-skill/
├── SKILL.md                           # This file
├── references/                        # Problem-focused guides (17 files)
│   ├── index.jsonl                    # Search index
│   ├── sections.jsonl                 # Section details
│   ├── index.meta.json               # Collection metadata
│   ├── documentation-search-system.md # Complete search methodology
│   ├── getting-started.md
│   ├── project-setup.md
│   ├── svelte5-runes.md
│   ├── forms-and-actions.md
│   ├── styling-with-tailwind.md
│   ├── server-rendering.md
│   ├── data-loading.md
│   ├── deployment-guide.md
│   ├── routing-patterns.md
│   ├── styling-patterns.md
│   ├── best-practices.md
│   ├── performance-optimization.md
│   ├── migration-svelte4-to-5.md
│   ├── tailwind-v4-migration.md
│   ├── common-issues.md
│   └── troubleshooting.md
├── docs/                              # Comprehensive references (7 files)
│   ├── index.jsonl                    # Search index
│   ├── sections.jsonl                 # Section details
│   ├── index.meta.json               # Collection metadata
│   ├── sveltekit-configuration.md
│   ├── svelte5-api-reference.md
│   ├── tailwind-configuration.md
│   ├── adapters-reference.md
│   ├── advanced-routing.md
│   ├── advanced-ssr.md
│   └── integration-patterns.md
├── provenance.jsonl                   # Source attribution
└── skill.manifest.json                # Skill metadata

分发模式

此技能采用仅作者分发：

• 所有内容均为新编写
• 不包含供应商文档的逐字内容
• 源材料仅供参考
• 所有指南均在 frontmatter 中标注来源（adapted_from）

请记住

实现之前务必先搜索文档！ 研究优先的方法可避免常见错误，并确保遵循集成最佳实践。

从第 0 阶段（发现索引）开始，并针对每个问题完成 5 阶段搜索流程。