frontend-dev-guidelines

Frontend Development Guidelines

Purpose

Comprehensive guide for modern Svelte 5 development, emphasizing runes-based reactivity, proper file organization, SvelteKit integration, and performance optimization.

When to Use This Skill

• Creating new Svelte components or pages
• Building new features with Svelte 5 runes
• Setting up routing with SvelteKit
• Managing state with stores and runes
• Styling components with Tailwind CSS
• Performance optimization
• Organizing frontend code
• TypeScript best practices in Svelte

---

Quick Start

New Component Checklist

Creating a component? Follow this checklist:

• Use <script lang="ts"> for TypeScript support
• Define props with let { prop1, prop2 }: Props = $props()
• Use $state() rune for reactive state
• Use $derived() for computed values
• Use $effect() for side effects
• Import aliases: $lib/, $app/, custom aliases
• Export component props interface
• Use bind: for two-way data binding when needed
• Implement proper TypeScript types
• Use slots/​snippets for content projection

New Feature Checklist

Creating a feature? Set up this structure:

• Create src/​lib/​{feature-name}/ directory
• Create subdirectories: stores/, components/, utils/, types/
• Create store file: stores/​{feature}.svelte.ts
• Set up TypeScript types in types/
• Create route in src/​routes/​{feature-name}/​+page.svelte
• Set up load functions in +page.ts or +page.server.ts
• Use proper error boundaries with +error.svelte
• Export public API from feature index.ts

---

Import Aliases Quick Reference

These are SvelteKit's built-in aliases. Custom aliases can be defined in vite.config.js.

---

Common Imports Cheatsheet

// Svelte imports
import { onMount, onDestroy, setContext, getContext } from 'svelte';
import { writable, readable, derived, get } from 'svelte/​store';

// SvelteKit imports
import { page, navigating } from '$app/​stores';
import { goto, invalidate, invalidateAll } from '$app/​navigation';
import { browser, dev } from '$app/​environment';
import type { PageData, PageLoad } from './​$types';

// Component imports
import Button from '$lib/​components/​Button.svelte';
import Modal from '$lib/​components/​Modal.svelte';

// Store imports
import { userStore } from '$lib/​stores/​user.svelte.ts';

// Types
import type { User } from '$lib/​types/​user';

// Environment variables
import { PUBLIC_API_URL } from '$env/​static/​public';
import { PRIVATE_API_KEY } from '$env/​static/​private';

---

Topic Guides

🎨 Component Patterns

Modern Svelte 5 components use:

• Runes ($state, $derived, $effect) for reactivity
• <script lang="ts"> for TypeScript support
• Props with $props() and $bindable()
• Snippets for content projection

Key Concepts:

• Use $state() for reactive state
• Use $derived() for computed values
• Use $effect() for side effects
• Component structure: Script → Markup → Style

📖 Complete Guide: resources/​component-patterns.md

---

📊 Data Fetching

PRIMARY PATTERNS:

• SvelteKit load functions (+page.ts, +page.server.ts)
• Native fetch with proper error handling
• Stores for client-side state
• Form actions for mutations

Data Loading:

• Use load functions for SSR/​CSR data
• Return data from +page.server.ts for server-only
• Use invalidate() to refresh data
• Handle errors with +error.svelte

📖 Complete Guide: resources/​data-fetching.md

---

📁 File Organization

lib/ vs routes/:

• src/​lib/: Reusable code (components, stores, utils)
• src/​routes/: Page routes and layouts

Library Structure:

src/​lib/
  components/     # Reusable components
  stores/         # Global stores
  utils/          # Helper functions
  types/          # TypeScript types
  server/         # Server-only code

📖 Complete Guide: resources/​file-organization.md

---

🎨 Styling

Styling Options:

• Scoped styles in <style> blocks
• Tailwind CSS classes (if configured)
• CSS modules with .module.css
• Global styles in app.css

Best Practices:

• Use scoped styles by default
• CSS custom properties for theming
• Conditional classes with class directive

Example:

<div class="container" class:active={isActive}>
<style>
  .container { padding: 1rem; }
  .active { background: var(--primary); }
</​style>

📖 Complete Guide: resources/​styling-guide.md

---

🛣️ Routing

SvelteKit File-Based Routing:

• Routes defined by file structure
• +page.svelte for pages
• +layout.svelte for layouts
• +server.ts for API endpoints

Route Files:

src/​routes/
  +page.svelte         # /
  about/​+page.svelte   # /​about
  blog/[slug]/
    +page.svelte       # /​blog/:slug
    +page.ts           # Load function

Load Functions:

// +page.ts
export const load: PageLoad = async ({ params }) => {
    const post = await fetchPost(params.slug);
    return { post };
};

📖 Complete Guide: resources/​routing-guide.md

---

⏳ Loading & Error States

Loading States:

• Use {#await} blocks for promises
• Show loading indicators during data fetch
• Streaming SSR with +page.server.ts

Error Handling:

{#await promise}
  <p>Loading...</​p>
{:then data}
  <p>{data}</​p>
{:catch error}
  <p>Error: {error.message}</​p>
{/​await}

Error Boundaries:

• +error.svelte for route errors
• app.html for app-wide errors
• Form validation with enhance

📖 Complete Guide: resources/​loading-and-error-states.md

---

⚡ Performance

Optimization Patterns:

• $derived for expensive computations
• Svelte's built-in reactivity optimization
• Lazy loading with dynamic imports
• Debounced actions with timers
• onDestroy for cleanup

Key Features:

• Compile-time optimizations
• No virtual DOM overhead
• Fine-grained reactivity
• Automatic batching

📖 Complete Guide: resources/​performance.md

---

📘 TypeScript

Standards:

• Use lang="ts" in script tags
• Define props interfaces
• Type imports: import type { User } from '$lib/​types'
• Generic components with generics attribute

Component Types:

<script lang="ts">
  interface Props {
    name: string;
    age?: number;
  }
  let { name, age = 0 }: Props = $props();
</​script>

📖 Complete Guide: resources/​typescript-standards.md

---

🔧 Common Patterns

Covered Topics:

• Form handling with use:enhance
• Store patterns and subscriptions
• Two-way binding with bind:
• Context API usage
• Component composition with slots

📖 Complete Guide: resources/​common-patterns.md

---

📚 Complete Examples

Full working examples:

• Modern component with all patterns
• Complete feature structure
• API service layer
• Route with lazy loading
• Suspense + useSuspenseQuery
• Form with validation

📖 Complete Guide: resources/​complete-examples.md

---

Navigation Guide

---

Core Principles

1. Runes for Reactivity: Use $state, $derived, $effect
2. File-Based Routing: SvelteKit's file structure defines routes
3. Server-First: Leverage SSR and server-side data loading
4. Type Safety: TypeScript in all components
5. Scoped Styles: Component styles are scoped by default
6. Built-in Optimization: Svelte compiles to optimal JavaScript
7. Progressive Enhancement: Works without JavaScript
8. Form Actions: Server-side form handling

---

Quick Reference: File Structure

src/
  lib/
    components/
      Button.svelte           # Reusable component
      Modal.svelte           
    stores/
      user.svelte.ts         # Global state
      auth.svelte.ts
    utils/
      api.ts                  # Utility functions
      format.ts
    types/
      index.ts                # TypeScript types
    server/
      db.ts                   # Server-only code

  routes/
    +layout.svelte            # Root layout
    +page.svelte              # Home page
    about/
      +page.svelte            # About page
    blog/
      +page.svelte            # Blog list
      [slug]/
        +page.svelte          # Blog post
        +page.ts              # Load function
    api/
      posts/
        +server.ts            # API endpoint

---

Modern Component Template (Quick Copy)

<script lang="ts">
  import { onMount } from 'svelte';
  import type { User } from '$lib/​types';
  
  interface Props {
    id: number;
    onAction?: () => void;
  }
  
  let { id, onAction }: Props = $props();
  
  let user = $state<User | null>(null);
  let loading = $state(true);
  let count = $state(0);
  
  const doubled = $derived(count * 2);
  
  $effect(() => {
    console.log(`Count changed to ${count}`);
  });
  
  onMount(async () => {
    const response = await fetch(`/​api/​users/​${id}`);
    user = await response.json();
    loading = false;
  });
  
  function handleClick() {
    count++;
    onAction?.();
  }
</​script>

{#if loading}
  <p>Loading...</​p>
{:else if user}
  <div class="container">
    <h2>{user.name}</​h2>
    <button onclick={handleClick}>
      Count: {count} (doubled: {doubled})
    </​button>
  </​div>
{/​if}

<style>
  .container {
    padding: 1rem;
    border-radius: 8px;
    background: var(--surface);
  }
</​style>

For complete examples, see resources/​complete-examples.md

---

Related Skills

• error-tracking: Error tracking with Sentry (applies to frontend too)
• backend-dev-guidelines: Backend API patterns that frontend consumes

---

Skill Status: Modular structure with progressive loading for optimal context management