Svelte Sandbox Development Guide

A comprehensive skill for developing in a SvelteKit project that follows vertical architecture with minimal abstractions, OpenAPI-generated types, and mandatory browser testing.

Critical Development Rule

**🚨 NEVER IMPLEMENT CODE WITHOUT IMMEDIATELY TESTING IN BROWSER 🚨**

Test EVERY single change in the browser before proceeding

If you write ANY code, you MUST verify it works in the browser

If you cannot test (server down, etc.), STOP and ask user to start server

NO EXCEPTIONS - this is mandatory for ALL code changes

Implementation Workflow

Follow this workflow for ALL development tasks:

1. Before Starting Work

Ensure you understand the requirements completely

Confirm backend server is running on port 8101

If server is not running, request user to start it before proceeding

2. During Development (After EACH Change)

Follow established patterns and conventions from this guide

Use existing components and utilities

Write clean, maintainable code

**🚨 MANDATORY: Test EVERY change immediately in the browser**

**🚨 MANDATORY: Navigate to the relevant page and verify functionality works**

**🚨 MANDATORY: Test user interactions, form submissions, and UI behavior**

**🚨 MANDATORY: Check browser console for any errors**

**🚨 MANDATORY: Do NOT proceed to next change until current change is verified working**

3. After Implementing ALL Changes

**FINAL VERIFICATION: Re-test all modified pages in the browser**

Verify mobile responsiveness if applicable

Confirm no console errors exist

4. Before Committing

Run `pnpm check` to ensure code quality, fix any bugs

Run `pnpm format` to ensure code formatting

Run tests if applicable

Review changes for quality

5. Git Workflow

Commit changes with descriptive messages

Rebase if needed to keep history clean

Push changes to remote repository

Core Architecture Principles

This application follows a **vertical architecture** with **minimal abstractions**:

Minimal Abstractions

**Use OpenAPI-generated types directly** - no custom wrappers or API client classes

**Direct openapi-fetch calls** in actions - no intermediate API layers

**Minimal custom interfaces** - only create when necessary for UI logic

Vertical Feature Organization

Each feature is **self-contained** in `src/lib/app/{feature}/`

**High cohesion** within features, **loose coupling** between features

Feature exports are **barreled** through `index.ts` for clean imports

Developer Experience Focus

**Straightforward patterns** - easy to learn, easy to follow

**Consistent error handling** with simple `{data, error}` structure

**Type-safe** throughout with TypeScript and Zod validation

**Minimal cognitive overhead** - few concepts to learn

**Vertical architecture** - business logic and UI clearly separated

File Structure

```

src/lib/app/{feature}/

├── {feature}-schema.ts # Zod v4 validation schemas + OpenAPI types

├── {feature}-constants.ts # Feature constants (statuses, enums, etc.)

├── config.ts # Feature configuration

├── index.ts # Public exports (barreled)

├── components/ # Route-specific UI components

│ ├── {item}-form.svelte

│ ├── {item}-card.svelte

│ └── {item}-table.svelte

└── actions/ # Business logic (commands & queries)

├── get-{items}.ts # List query

├── get-{item}.ts # Single item query

├── create-{item}.ts # Create command

├── update-{item}.ts # Update command

└── delete-{item}.ts # Delete command

src/routes/{feature}/

├── +page.svelte # List page

├── +page.server.ts # List loader

├── create/

│ ├── +page.svelte

│ └── +page.server.ts

└── [id]/

├── +page.svelte

├── +page.server.ts

├── +server.ts # API endpoint (e.g. DELETE)

└── edit/

├── +page.svelte

└── +page.server.ts

```

Code Style

Use kebab-case for file naming

Run `pnpm format` before committing

Use `import type { PageProps } from './$types';` for +page.svelte files when properties are needed

Always use types from $types if available for +server.ts and +page.ts

Always use an interface to declare Svelte component props

API Types Pattern

Use OpenAPI-generated types directly in schema files:

```typescript

// {feature}-schema.ts

import type { components } from '$lib/api/billing/v1';

// Use OpenAPI generated types directly

export type Item = components['schemas']['Item'];

export type GetItemsResult = Item;

export type CreateUpdateItemRequest = components['schemas']['CreateItemCommand'];

// Custom types only when needed for client-side logic

export interface ItemSummary {

totalItems: number;

totalValue: number;

}

// Form validation schemas

export const createUpdateItemSchema = z.object({

amount: z.number().positive('Amount must be greater than 0')

});

export type CreateUpdateItemSchema = typeof createUpdateItemSchema;

```

Action Patterns

Query Pattern (Read Single Item)

```typescript

// actions/get-{item}.ts

import { ok, error, type ActionResult } from '$lib/utils/action-result';

import client from '$lib/api/billing';

import type { Item } from '../{item}-schema';

export const getItemQuery = async (id: string): Promise<ActionResult<Item>> => {

if (!id?.trim()) {

return error('Item ID is required', 400);

}

const { data, response } = await client.GET('/Items/{id}', {

params: { path: { id } }

});

if (data) {

return ok(data);

}

if (response?.status === 404) {

return error('Item not found', 404);

}

return error('Failed to load item. Please try again later.', response?.status || 500);

};

```

List Query Pattern

```typescript

// actions/get-{items}.ts

import { ok, error, type ActionResult } from '$lib/utils/action-result';

import client from '$lib/api/billing';

import type { GetItemsResult } from '../{item}-schema';

export interface GetItemsQuery {

page?: number;

pageSize?: number;

search?: string;

sortBy?: string;

sortOrder?: 'asc' | 'desc';

status?: string;

}

export const getItemsQuery = async (query?: GetItemsQuery): Promise<ActionResult<GetItemsResult[]>> => {

const { data, response } = await client.GET('/Items', {

params: { query: query as any }

});

if (data) {

const items = (data || []) as GetItemsResult[];

items.sort((a, b) => a.name.localeCompare(b.name));

return ok(items);

}

return error('Failed to load items. Please try again later.', response?.status || 500);

};

```

Command Pattern (Create)

```typescript

// actions/create-{item}.ts

import { ok, error, type ActionResult } from '$lib/utils/action-result';

import client from '$lib/api/billing';

import type { Item } from '../{item}-schema';

export interface CreateItemParams {

amount: number;

currency?: string;

dueDate?: string;

cashierId?: string;

}

export const createItemCommand = async (params: CreateItemParams): Promise<ActionResult<Item>> => {

const { data, response } = await client.POST('/Items', {

body: params as any

});

if (data) {

return ok(data);

}

if (response?.status === 400) {

return error('Invalid request data', 400);

}

if (response?.status === 409) {

return error('Item already exists', 409);

}

return error('Failed to create item. Please try again later.', response?.status || 500);

};

```

Update Pattern

```typescript

// actions/update-{item}.ts

export interface UpdateItemParams {

id: string;

amount: number;

currency?: string;

dueDate?: string;

cashierId?: string;

}

export const updateItemCommand = async (params: UpdateItemParams): Promise<ActionResult<Item>> => {

const { id, ...updateData } = params;

if (!id?.trim()) {

return error('Item ID is required', 400);

}

const { data, response } = await client.PUT('/Items/{id}', {

params: { path: { id } },

body: updateData as any

});

if (data) {

return ok(data);

}

if (response?.status === 404) {

return error('Item not found', 404);

}

if (response?.status === 400) {

return error('Invalid request data', 400);

}

return error('Failed to update item. Please try again later.', response?.status || 500);

};

```

Delete Pattern (Void Operations)

```typescript

// actions/delete-{item}.ts

export const deleteItemCommand = async (id: string): Promise<ActionResult<void>> => {

if (!id?.trim()) {

return error('Item ID is required', 400);

}

const { error: apiError, response } = await client.DELETE('/Items/{id}', {

params: { path: { id } }

});

if (!apiError) {

return ok();

}

if (response?.status === 404) {

return error('Item not found', 404);

}

return error('Failed to delete item. Please try again later.', response?.status || 500);

};

```

Error Handling in Page Loaders

```typescript

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

export const load: PageServerLoad = async ({ params }) => {

const result = await getItemQuery(params.id);

if (!result.error) {

return {

item: result.data

};

}

return error(result.error.code, result.error.message);

};

```

UI Components

**DO NOT** change files directly in `lib/components/ui` folder (shadcn-svelte components)

Install new shadcn components using: `pnpm dlx shadcn-svelte@latest add [component name] -y -o`

Component documentation available via context7 mcp (Library: huntabyte/shadcn-svelte)

Use existing shadcn-svelte components when possible

Adding a New Feature

Follow this mechanical pattern:

1. **Create feature directory**: `src/lib/app/{feature}/`

2. **Define types and schemas**: `{feature}-schema.ts` (import from OpenAPI)

3. **Create actions**: `actions/` directory with queries and commands

4. **Add configuration**: `config.ts` for feature settings

5. **Export public API**: `index.ts` with barrel exports

6. **Create routes**: `src/routes/{feature}/` with pages and loaders

7. **Build UI components**: `components/` within the feature directory

8. **🚨 TEST IMMEDIATELY**: Open browser, navigate to feature, verify all functionality

Key Principles

**OpenAPI types in schema**: All API-generated types in `{feature}-schema.ts`

**Parameters co-located**: Action parameter interfaces in their respective action files

**Type safety**: Leverage generated types from API spec

**Minimal custom interfaces**: Only add when needed for UI logic

**No API client classes**: Actions call openapi-fetch directly

**Simplified parameters**: Single `id` parameters take `id: string` directly, not wrapped in interface

**Test continuously**: Every code change must be verified in browser before proceeding

Remember

**NEVER skip browser testing** - this is the most critical rule

Follow the established patterns for consistency

Keep abstractions minimal

Use vertical architecture for feature organization

Leverage OpenAPI-generated types

Run quality checks before committing

Svelte Sandbox Development Guide

Svelte Sandbox Development Guide

Critical Development Rule

Implementation Workflow

1. Before Starting Work

2. During Development (After EACH Change)

3. After Implementing ALL Changes

4. Before Committing

5. Git Workflow

Core Architecture Principles

Minimal Abstractions

Vertical Feature Organization

Developer Experience Focus

File Structure

Code Style

API Types Pattern

Action Patterns

Query Pattern (Read Single Item)

List Query Pattern

Command Pattern (Create)

Update Pattern

Delete Pattern (Void Operations)

Error Handling in Page Loaders

UI Components

Adding a New Feature

Key Principles

Remember

Reviews (0)