sveltekit-svelte5-tailwind-skill

What this skill does

# SvelteKit 2 + Svelte 5 + Tailwind v4 Integration Skill

This skill provides comprehensive guidance for building modern web applications with the SvelteKit 2 + Svelte 5 + Tailwind CSS v4 stack.

## About This Integration Stack

**SvelteKit 2** is a modern full-stack framework with:
- File-based routing with layouts
- Server-side rendering (SSR) and static site generation (SSG)
- Form actions with progressive enhancement
- Multiple deployment adapters (Vercel, Cloudflare, Node, static)

**Svelte 5** introduces a new reactivity system with:
- Runes: `$state()`, `$derived()`, `$effect()`, `$props()`
- Simplified component authoring
- Better TypeScript support
- Snippets replacing slots

**Tailwind CSS v4** offers:
- CSS-first configuration
- New Vite plugin architecture
- Improved JIT performance
- Simplified setup

**Integration challenges this skill addresses:**
- Configuring all three tools to work together
- Understanding Svelte 5 runes in SSR context
- Progressive enhancement with form actions
- CSS loading in development and production
- Deployment across different platforms
- Migration from earlier versions

## How to Use This Skill

**CRITICAL: Research-First Methodology**

When a user asks you to build something with this stack:

1. **Research first** - Search the documentation to understand:
   - How SvelteKit handles this use case
   - What Svelte 5 runes patterns apply
   - How to style with Tailwind v4
   - Common integration pitfalls to avoid

2. **Then execute** - Implement the solution using the knowledge gained from documentation

**Why this matters:**
- This integration has specific constraints (e.g., runes don't work in SSR)
- The documentation provides authoritative guidance on configuration
- Researching first prevents mistakes that require rework
- You'll implement solutions that follow best practices

**Workflow:**
1. User requests: "Help me build [feature] with SvelteKit/Svelte 5/Tailwind"
2. You search documentation using the process below
3. You understand the recommended approach
4. You implement the solution correctly the first time

## Documentation Collections

This skill includes two searchable documentation collections:

### references/ (Problem-Focused Guides)
17 curated guides addressing specific integration challenges:
- **Setup**: getting-started.md, project-setup.md
- **Core Concepts**: svelte5-runes.md, routing-patterns.md, server-rendering.md, data-loading.md
- **Forms & Styling**: forms-and-actions.md, styling-with-tailwind.md, styling-patterns.md
- **Deployment**: deployment-guide.md
- **Migration**: migration-svelte4-to-5.md, tailwind-v4-migration.md
- **Optimization**: best-practices.md, performance-optimization.md
- **Troubleshooting**: common-issues.md, troubleshooting.md
- **Search System**: documentation-search-system.md

### docs/ (Comprehensive Reference)
7 adapted documentation guides covering complete APIs:
- sveltekit-configuration.md - Complete svelte.config.js and Vite config
- svelte5-api-reference.md - All Svelte 5 runes and template syntax
- tailwind-configuration.md - Tailwind v4 configuration options
- adapters-reference.md - Deployment adapter specifications
- advanced-routing.md - Advanced SvelteKit routing patterns
- advanced-ssr.md - SSR hooks, streaming, and optimization
- integration-patterns.md - Complete integration examples

## Searching Documentation

**IMPORTANT: Always search before implementing!**

This skill uses a 5-stage search process for efficient documentation lookup:

### Stage 0: Discover Available Documentation

Find all documentation indexes:
```bash
find . -name "index.jsonl" -type f
```

Expected output:
- `./references/index.jsonl` (17 problem-focused guides)
- `./docs/index.jsonl` (7 comprehensive references)

Sample each collection to understand its scope:
```
Read references/index.jsonl with offset: 1, limit: 5
Read docs/index.jsonl with offset: 1, limit: 5
```

Determine which collection(s) are relevant to your query.

### Stage 1: Load Relevant Indexes

Read the complete index file(s) for your chosen collection(s):
```
Read references/index.jsonl  # For how-to guides and troubleshooting
Read docs/index.jsonl         # For API reference and configuration
```

### Stage 2: Reason About Candidates

Analyze the summaries to identify 3-4 most relevant files:

**For setup questions** → references/getting-started.md, references/project-setup.md
**For runes questions** → references/svelte5-runes.md, docs/svelte5-api-reference.md
**For forms questions** → references/forms-and-actions.md, docs/integration-patterns.md
**For styling questions** → references/styling-with-tailwind.md, docs/tailwind-configuration.md
**For SSR questions** → references/server-rendering.md, docs/advanced-ssr.md
**For deployment** → references/deployment-guide.md, docs/adapters-reference.md
**For errors** → references/common-issues.md, references/troubleshooting.md

Consider:
- Query intent (how-to vs what-is vs troubleshooting)
- Integration-specific vs single-package questions
- Beginner vs advanced topics

### Stage 3: Get Section Details

For your 3-4 candidates, read their sections.jsonl entries:
```
Read references/sections.jsonl with offset: {index}, limit: 1
Read docs/sections.jsonl with offset: {index}, limit: 1
```

**Important:** Index number from index.jsonl = line number in sections.jsonl

Analyze the section summaries to identify which sections address your query.

### Stage 4: Read Targeted Sections

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

Use the offset and limit from the sections.jsonl data for precise reading.

### Stage 5: Synthesize and Answer

Combine information from multiple sources:
1. Direct answer to the user's question
2. Code examples (complete and runnable)
3. Integration-specific considerations
4. File references for further reading

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

**For complete search methodology with examples, see references/documentation-search-system.md**

## Quick Start (5 Minutes)

For a complete walkthrough, search references/getting-started.md

Basic setup commands:
```bash
# 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
```

**Critical configuration:**
- Tailwind plugin MUST come before SvelteKit plugin in vite.config.js
- Import CSS in root +layout.svelte (not app.html)
- Use `@next` tag for Tailwind v4 packages

## Common Use Cases

**Setup and Configuration**
→ Search: references/getting-started.md, references/project-setup.md
→ Key sections: Installation, Vite Configuration, Directory Structure

**Svelte 5 Runes with SSR**
→ Search: references/svelte5-runes.md
→ Critical: "Server-Side Constraints" section - $state() doesn't work in SSR!

**Forms and Progressive Enhancement**
→ Search: references/forms-and-actions.md
→ Key pattern: Manual enhance() for rune compatibility

**Styling Components**
→ Search: references/styling-with-tailwind.md, references/styling-patterns.md
→ Key topics: Dynamic classes, dark mode, component patterns

**Data Loading**
→ Search: references/data-loading.md, docs/advanced-ssr.md
→ Key pattern: Passing load() data to rune state

**Deployment**
→ Search: references/deployment-guide.md, docs/adapters-reference.md
→ Platform-specific: Vercel, Cloudflare, Node, static