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.