sveltekit-svelte5-tailwind-skill

SKILL.md

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:

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

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:

User requests: "Help me build [feature] with SvelteKit/Svelte 5/Tailwind"

You search documentation using the process below

You understand the recommended approach

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:

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:

Direct answer to the user's question

Code examples (complete and runnable)

Integration-specific considerations

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:

# 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

Troubleshooting Errors
→ Search: references/common-issues.md first (quick fixes)
→ Then: references/troubleshooting.md (systematic debugging)

Common Issues and Quick Fixes

CSS not loading in production
→ Search: references/common-issues.md section "CSS Loading Issues"
→ Quick check: Vite plugin order, CSS import location

Runes causing SSR errors
→ Search: references/svelte5-runes.md section "Server-Side Constraints"
→ Quick fix: Don't use $state() or $effect() in SSR components

Form losing state on submit
→ Search: references/forms-and-actions.md section "Handling use:enhance Reactivity"
→ Quick fix: Use manual enhance() callback

HMR breaking
→ Search: references/common-issues.md section "Hot Module Reload Problems"
→ Quick fix: Check Vite plugin order and file watch settings

Tailwind classes not working
→ Search: references/styling-with-tailwind.md section "Content Detection and Purging"
→ Quick fix: Check content paths in config, use full class names

For systematic troubleshooting, see references/troubleshooting.md

Integration Patterns

Server + Client Component Split

<!-- +page.svelte (SSR-safe) -->
<script>
  export let data;
</script>

<ClientCounter initialCount={data.count} />

<!-- ClientCounter.svelte (client-only runes) -->
<script>
  let { initialCount } = $props();
  let count = $state(initialCount);
</script>

Form with Progressive Enhancement

<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 fields -->
</form>

Conditional Tailwind Classes

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

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

<!-- ❌ BAD: Dynamic class parts -->
<div class="bg-{active ? 'blue' : 'gray'}-500">
  Button
</div>

For complete patterns, search docs/integration-patterns.md

Best Practices

Search references/best-practices.md for comprehensive guidance on:

Project organization and architecture

Component design patterns

State management strategies

Styling conventions

Performance optimization

Security considerations

Testing strategies

Accessibility guidelines

Migration Guides

Migrating from Svelte 4 to Svelte 5 in SvelteKit
→ Search: references/migration-svelte4-to-5.md
→ Key topics: Stores to runes, reactive statements to $derived, slots to snippets

Migrating from Tailwind v3 to v4
→ Search: references/tailwind-v4-migration.md
→ Key topics: CSS-first config, Vite plugin, syntax changes

Performance Optimization

Search references/performance-optimization.md for:

Bundle size optimization

CSS purging and minification

Code splitting strategies

Image and font optimization

Lazy loading patterns

Core Web Vitals optimization

Lighthouse score improvements

Version Information

This skill covers:

SvelteKit: 2.x (latest stable)

Svelte: 5.x (with runes)

Tailwind CSS: 4.x (CSS-first configuration)

All code examples and patterns are tested with these versions.

Getting Help

Start with search: Use the 5-stage search process above

Check common issues: references/common-issues.md for quick fixes

Systematic debugging: references/troubleshooting.md for methodology

Consult references: Problem-focused guides for specific topics

Check API docs: Comprehensive references for configuration details

Skill Structure

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

Distribution Mode

This skill uses author-only distribution:

All content is newly authored

No verbatim vendor documentation

Source materials used for reference only

All guides cite sources in frontmatter (adapted_from)

Remember

Always search documentation before implementing! The research-first approach prevents common mistakes and ensures you follow integration best practices.

Start with Stage 0 (discover indexes) and work through the 5-stage search process for every question.