# Core Architecture Standards for Svelte

This document outlines the core architectural standards for Svelte projects, focusing on project structure, organization, and fundamental architectural patterns. This guide is intended to promote maintainability, performance, and scalability in Svelte applications.

## 1. Project Structure and Organization

A well-defined project structure is crucial for maintainability and collaboration. Svelte projects benefit from a structure that separates concerns and promotes reusability.

### 1.1 Standard Directory Structure

**Do This:** Adhere to a standardized directory structure that aligns with SvelteKit's conventions and best practices.

**Don't Do This:** Avoid haphazardly placing files and folders without a clear organizational scheme.

**Why:** A consistent structure makes it easier for developers to navigate and understand the project. It also facilitates automated tooling and deployment processes.

"""

├── src/

│ ├── lib/ # Reusable components, utilities, and stores

│ │ ├── components/ # Presentational and container components

│ │ ├── utils/ # Utility functions

│ │ ├── stores/ # Svelte stores for state management

│ │ └── assets/ # Images, SVGs, and other static assets

│ ├── routes/ # SvelteKit routes (pages and API endpoints)

│ │ ├── +page.svelte # Page component

│ │ ├── +page.ts # Page data loading logic

│ │ ├── +server.ts # API endpoints

│ │ └── components/ # Route-specific components

│ ├── app.html # Root HTML template

│ ├── app.d.ts # TypeScript definitions

│ └── hooks.server.ts # Server-side hooks

├── static/ # Static assets (images, fonts, etc.)

├── svelte.config.js # Svelte configuration

├── vite.config.ts # Vite configuration

├── package.json # Project dependencies and scripts

├── README.md # Project documentation

└── tsconfig.json # TypeScript configuration

"""

* **"src/lib":** Contains reusable components, utilities, and Svelte stores. This directory should be further organized by functionality.

* **"src/routes":** Holds SvelteKit routes, where each directory represents a route. "+page.svelte" files are the Svelte components for each page, and "+page.ts" files are used for loading data into the page. "+server.ts" defines API endpoints.

* **"static":** Contains static assets like images and fonts. These are served directly.

* **"svelte.config.js":** SvelteKit configuration file. Includes adapters, preprocessors, and other Svelte-specific settings.

* **"vite.config.ts":** Vite configuration file. Controls the build process, including plugins and optimizations.

### 1.2 Component Organization within "lib"

**Do This:** Organize components within the "src/lib/components" directory into logical groupings based on feature or domain. Create subdirectories for related components.

**Don't Do This:** Dump all components into a single "components" directory.

**Why:** Grouping components makes it easier to locate and understand the purpose of each component.

"""

src/lib/components/

├── UserProfile/

│ ├── UserProfileCard.svelte

│ ├── UserProfileEditor.svelte

│ └── UserAvatar.svelte

├── ProductCard.svelte

└── Button.svelte

"""

**Example:**

"""svelte

{user.name}

{user.bio}

"""

### 1.3 Route-Specific Components

**Do This:** When a component is only used within a specific route, place it in a "components" subdirectory within the route directory.

**Don't Do This:** Place route-specific components in the global "src/lib/components" directory.

**Why:** This improves encapsulation and reduces the global namespace of components, leading to better maintainability.

"""

src/routes/

└── blog/

├── [slug]/

│ ├── +page.svelte

│ └── components/

│ └── BlogPostContent.svelte

"""

### 1.4 Utility Functions

**Do This:** Place reusable utility functions in the "src/lib/utils" directory. Group related functions into separate modules (e.g., "date.ts", "string.ts").

**Don't Do This:** Scatter utility functions throughout the codebase or duplicate them in multiple places.

**Why:** Centralized utility functions promote code reuse and reduce redundancy.

"""typescript

// src/lib/utils/date.ts

export function formatDate(date: Date): string {

return new Intl.DateTimeFormat('en-US').format(date);

}

"""

### 1.5 Svelte Stores

**Do This:** Centralize state management using Svelte stores in the "src/lib/stores" directory. Use separate files for different domains of application state (e.g., "user.ts", "settings.ts").

**Don't Do This:** Manage state in a haphazard way or rely heavily on prop drilling.

**Why:** Svelte stores provide a reactive and efficient way to manage application state.

"""typescript

// src/lib/stores/user.ts

import { writable } from 'svelte/store';

export const user = writable({

id: null,

name: '',

email: ''

});

export function setUser(userData) {

user.set(userData);

}

export function clearUser() {

user.set({ id: null, name: '', email: '' });

}

"""

## 2. Architectural Patterns

Svelte applications can benefit from well-established architectural patterns to improve organization, testability, and scalability.

### 2.1 Component-Based Architecture

**Do This:** Embrace a component-based architecture, breaking down the user interface into reusable components.

**Don't Do This:** Create monolithic components that handle too much logic and rendering.

**Why:** Component-based architecture promotes code reuse, testability, and maintainability. Svelte's core design encourages this naturally.

"""svelte

{label}

"""

### 2.2 Container/Presentational Component Pattern

**Do This:** Separate components into "container" (or "smart") components that handle data fetching and logic, and "presentational" (or "dumb") components that focus on rendering UI.

**Don't Do This:** Mix data fetching and complex logic directly within presentational components.

**Why:** This separation makes it easier to test and reuse components. Container components can be responsible for connecting to stores or APIs, while presentational components focus on displaying data.

"""svelte

{#each products as product (product.id)}

{product.name} - ${product.price}

{/each}

"""

### 2.3 Actions for DOM Manipulation

**Do This:** Use Svelte actions for DOM manipulation and side effects related to specific elements.

**Don't Do This:** Directly manipulate the DOM within component logic.

**Why:** Actions provide a clean and declarative way to interact with DOM elements.

"""svelte

export function tooltip(node: HTMLElement, text: string) {

let tooltipElement: HTMLDivElement;

function createTooltip() {

tooltipElement = document.createElement('div');

tooltipElement.textContent = text;

tooltipElement.style.position = 'absolute';

tooltipElement.style.background = 'black';

tooltipElement.style.color = 'white';

tooltipElement.style.padding = '5px';

document.body.appendChild(tooltipElement);

}

function destroyTooltip() {

if (tooltipElement) {

tooltipElement.remove();

tooltipElement = null;

}

function updateTooltipPosition(event: MouseEvent) {

if (tooltipElement) {

tooltipElement.style.top = "${event.pageY + 10}px";

tooltipElement.style.left = "${event.pageX + 10}px";

}

node.addEventListener('mouseover', createTooltip);

node.addEventListener('mousemove', updateTooltipPosition);

node.addEventListener('mouseout', destroyTooltip);

return {

update(newText: string) {

text = newText;

if (tooltipElement) {

tooltipElement.textContent = text;

}

destroy() {

node.removeEventListener('mouseover', createTooltip);

node.removeEventListener('mousemove', updateTooltipPosition);

node.removeEventListener('mouseout', destroyTooltip);

destroyTooltip();

}

};

}

"""

"""svelte

Hover me

"""

### 2.4 Form Handling with Actions

**Do This:** Employ Svelte actions for managing form state and validation instead of directly binding to input elements. This promotes cleaner, more reusable, and testable form logic. Libraries like "felte" are an excellent choice.

**Don't Do This:** Use inline event handlers and manually manage input values within your components.

**Why:** Using actions and form helper libraries encapsulates form logic and improves the overall architecture of forms.

"""bash

npm install @felte/core @felte/validator-zod zod

"""

"""svelte

First Name

{#if $errors.firstName}

{$errors.firstName}

{/if}

Last Name

{#if $errors.lastName}

{$errors.lastName}

{/if}

{#if $errors.email}

{$errors.email}

{/if}

Submit

"""

## 3. State Management

Efficient state management is essential for complex Svelte applications.

### 3.1 Choosing the Right State Management Approach

**Do This:** Evaluate the scale of state complexity required for each project when choosing a state management solution. Choose Svelte stores for local component state and simple application-wide state. Consider more robust solutions, like Zustand or Redux, for complex scenarios. Pinia is a great choice if using Vue previously as it mimics the API.

**Don't Do This:** Over-engineer state management in small projects or under-engineer it in large projects.

**Why:** Appropriate state management prevents performance problems, improves maintainability, and enhances code readability.

### 3.2 Global State with Svelte Stores

**Do This:** Use Svelte stores for managing global application state. Leverage derived stores for computed values and read-only stores for immutable data.

**Don't Do This:** Mutate store values directly without using the "set", "update", or "subscribe" methods.

**Why:** Stores provide a reactive and predictable way to manage application state. Using the built-in methods ensures that components are properly updated when the state changes.

"""typescript

// src/lib/stores/cart.ts

import { writable, derived } from 'svelte/store';

export const cartItems = writable([]);

export const totalItems = derived(cartItems, ($cartItems) => $cartItems.length);

export const totalPrice = derived(cartItems, ($cartItems) => {

return $cartItems.reduce((total, item) => total + item.price * item.quantity, 0);

});

"""

"""svelte

Total items: {$totalItems}

Total price: {$totalPrice}

"""

### 3.3 Context API for Component-Specific State

**Do This:** Use the Svelte context API ("setContext", "getContext") to share state and functionality between related components in a localized scope (such as within a specific route or component tree).

**Don't Do This:** Overuse the context API for global state management. Svelte stores are generally better for that purpose.

**Why:** The context API provides a way to avoid prop drilling and pass data down the component tree without explicitly passing props through each intermediate component.

"""svelte

"""

"""svelte

Current theme: {$theme}

Toggle Theme

"""

## 4. API Communication

Consider best practices for fetching data and interacting with APIs.

### 4.1 SvelteKit Load Functions

**Do This:** Use SvelteKit's "load" functions ("+page.ts", "+layout.ts") to fetch data for routes and layouts. This allows for server-side rendering and improved SEO.

**Don't Do This:** Fetch data directly in components using "onMount" unless it is client-side specific.

**Why:** "load" functions execute on the server during SSR and can pre-render the page with data, improving performance and SEO.

"""typescript

// src/routes/+page.ts

import type { PageLoad } from './$types';

export const load: PageLoad = async ({ fetch }) => {

const response = await fetch('/api/products');

const products = await response.json();

return {

products

};

"""

"""svelte

{#each products as product (product.id)}

{product.name} - ${product.price}

{/each}

"""

### 4.2 API Endpoints with SvelteKit

**Do This:** Create API endpoints using SvelteKit's server routes ("+server.ts"). Follow RESTful principles for endpoint design.

**Don't Do This:** Implement complex business logic directly within components.

**Why:** Server routes allow you to create clean, maintainable APIs that can be used by your Svelte application and other clients.

"""typescript

// src/routes/api/products/+server.ts

import { json } from '@sveltejs/kit';

import type { RequestHandler } from './$types';

const products = [

{ id: 1, name: 'Product A', price: 20 },

{ id: 2, name: 'Product B', price: 30 }

];

export const GET: RequestHandler = async () => {

return json(products);

};

"""

### 4.3 Error Handling

**Do This:** Implement robust error handling for API requests. Use "try...catch" blocks and provide informative error messages to the user.

**Don't Do This:** Ignore potential errors or display generic error messages.

**Why:** Proper error handling improves the user experience and helps debug issues.

"""typescript

// Example within a SvelteKit load function

export const load: PageLoad = async ({ fetch }) => {

try {

const response = await fetch('/api/products');

if (!response.ok) {

throw new Error("Failed to fetch products: ${response.status}");

}

const products = await response.json();

return {

products

};

} catch (error) {

console.error(error);

return {

status: 500,

error: new Error('Could not load products')

};

}

};

"""

## 5. Naming Conventions

Consistent naming conventions improve code readability and maintainability.

### 5.1 Components

**Do This:** Use PascalCase for component names (e.g., "UserProfileCard.svelte").

**Don't Do This:** Use camelCase or snake_case for component names.

**Why:** PascalCase is the standard convention for components in most UI frameworks.

### 5.2 Variables and Functions

**Do This:** Use camelCase for variables and functions (e.g., "userName", "formatDate").

**Don't Do This:** Use PascalCase or snake_case for variables and functions.

**Why:** camelCase is the standard convention for variables and functions in JavaScript and TypeScript.

### 5.3 Files and Directories

**Do This:** Use kebab-case for file and directory names (e.g., "user-profile.svelte", "api-utils").

**Don't Do This:** Use camelCase or snake_case for file and directory names.

**Why:** kebab-case is a common convention for file and directory names in web development.

### 5.4 Svelte Stores

**Do This:** Use camelCase for store names (e.g., "user", "settings"). Consider adding a "$" prefix when referencing the store's value in the template (e.g. "$user.name").

**Don't Do This:** Use PascalCase or snake_case for store names.

**Why:** camelCase aligns with JavaScript naming conventions, and the "$" prefix clearly indicates that you're accessing a reactive value.

## 6. TypeScript Usage

Leverage TypeScript to improve code quality and maintainability.

### 6.1 Strict Typing

**Do This:** Enable strict mode in your "tsconfig.json" file (""strict": true").

**Don't Do This:** Disable strict mode or use "any" type excessively.

**Why:** Strict typing helps catch errors early and improves code reliability.

### 6.2 Explicit Types

**Do This:** Provide explicit types for component props, store values, and function parameters.

**Don't Do This:** Rely solely on type inference, especially for complex types.

**Why:** Explicit types improve code readability and prevent unexpected type errors.

"""typescript

// src/lib/components/Button.svelte

{label}

"""

### 6.3 Interfaces and Types

**Do This:** Define interfaces or types for data structures used in your application.

**Don't Do This:** Use inline type definitions or anonymous types.

**Why:** Interfaces and types provide a clear and reusable way to define data structures.

"""typescript

// src/lib/types/user.ts

export interface User {

id: number;

name: string;

email: string;

}

"""

"""typescript

// Usage in a store:

import { writable } from 'svelte/store';

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

export const user = writable(null);

"""

By adhering to these core architectural standards, Svelte developers can create maintainable, performant, and scalable applications. This document is a living guide and should be updated as new best practices and features emerge in the Svelte ecosystem.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Core Architecture Standards for Svelte

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Testing Methodologies Standards for Svelte

Deployment and DevOps Standards for Svelte

Performance Optimization Standards for Svelte

Code Style and Conventions Standards for Svelte

API Integration Standards for Svelte