Tpl Frontend Svelte Sveltekit

PROJECT: [Nome do App]

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: frontend/06-svelte-sveltekit.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CLAUDE.md — SvelteKit + TypeScript + Drizzle ORM Gerado pelo Pack CLAUDE.md Elite

STACK

SVELTEKIT MENTAL MODEL

src/
├── lib/
│   ├── server/          # NUNCA exposto ao cliente (import $lib/server/*)
│   │   ├── db/          # Drizzle config + queries
│   │   │   ├── index.ts # DB connection
│   │   │   └── schema.ts
│   │   └── auth.ts      # Session validation
│   ├── components/      # Componentes .svelte reutilizáveis
│   │   ├── ui/          # Primitivos: Button, Input, Card
│   │   └── layout/      # Header, Sidebar, Footer
│   ├── stores/          # Svelte writable/derived stores
│   └── utils.ts         # Helpers puros
├── routes/
│   ├── +layout.svelte   # Root layout (nav, providers)
│   ├── +layout.server.ts # Root load (session, user)
│   ├── (public)/        # Route group sem auth
│   │   └── +page.svelte
│   ├── (app)/           # Route group com auth
│   │   ├── +layout.server.ts  # Auth guard
│   │   └── dashboard/
│   │       ├── +page.svelte
│   │       ├── +page.server.ts
│   │       └── +error.svelte
│   └── api/             # API routes (+server.ts)
└── hooks.server.ts      # Middleware global (auth, logging)

Key insight: $lib/server/ imports are BLOCKED from client code by SvelteKit. Anything in lib/server/ is guaranteed server-only — no accidental leaks.

DATA FETCHING RULES

Rule: Prefer +page.server.ts over +page.ts unless you need the load to run on client navigation too.

LOAD FUNCTION PATTERN

// routes/(app)/users/+page.server.ts
import { db } from '$lib/server/db';
import { users } from '$lib/server/db/schema';
import { error } from '@sveltejs/kit';
import type { PageServerLoad } from './$types';

export const load: PageServerLoad = async ({ locals }) => {
  if (!locals.user) throw error(401, 'Unauthorized');

  const allUsers = await db.select().from(users).orderBy(users.createdAt);

  return {
    users: allUsers,
    meta: { title: 'Usuários', count: allUsers.length },
  };
};

// In +page.svelte:
// <script lang="ts">
//   export let data;  // Typed automatically from load return
//   // data.users, data.meta — fully typed!
// </script>

FORM ACTIONS + SUPERFORMS PATTERN

// routes/(app)/users/new/schema.ts
import { z } from 'zod';

export const createUserSchema = z.object({
  name: z.string().min(2, 'Nome mínimo 2 caracteres'),
  email: z.string().email('Email inválido'),
  role: z.enum(['admin', 'member']),
});

// routes/(app)/users/new/+page.server.ts
import { superValidate, fail } from 'sveltekit-superforms';
import { zod } from 'sveltekit-superforms/adapters';
import { createUserSchema } from './schema';

export const load = async () => {
  const form = await superValidate(zod(createUserSchema));
  return { form };
};

export const actions = {
  default: async ({ request }) => {
    const form = await superValidate(request, zod(createUserSchema));
    if (!form.valid) return fail(400, { form });

    await db.insert(users).values(form.data);
    return { form };
  },
};

<!-- routes/(app)/users/new/+page.svelte -->
<script lang="ts">
  import { superForm } from 'sveltekit-superforms';
  export let data;

  const { form, errors, enhance, delayed } = superForm(data.form);
</script>

<form method="POST" use:enhance>
  <input name="name" bind:value={$form.name} />
  {#if $errors.name}<span class="text-red-500">{$errors.name}</span>{/if}

  <input name="email" bind:value={$form.email} />
  {#if $errors.email}<span class="text-red-500">{$errors.email}</span>{/if}

  <button disabled={$delayed}>
    {$delayed ? 'Salvando...' : 'Criar Usuário'}
  </button>
</form>

HOOKS (Global Middleware)

// src/hooks.server.ts
import type { Handle } from '@sveltejs/kit';
import { validateSession } from '$lib/server/auth';

export const handle: Handle = async ({ event, resolve }) => {
  // Auth: attach user to locals
  const sessionId = event.cookies.get('session');
  if (sessionId) {
    event.locals.user = await validateSession(sessionId);
  }

  return resolve(event);
};

SVELTE STORES PATTERN

// lib/stores/theme.ts
import { writable, derived } from 'svelte/store';
import { browser } from '$app/environment';

function createThemeStore() {
  const { subscribe, set, update } = writable<'light' | 'dark'>(
    browser ? (localStorage.getItem('theme') as 'light' | 'dark') ?? 'light' : 'light'
  );

  return {
    subscribe,
    toggle: () => update((t) => {
      const next = t === 'light' ? 'dark' : 'light';
      if (browser) localStorage.setItem('theme', next);
      return next;
    }),
    set,
  };
}

export const theme = createThemeStore();

// Derived store example
export const isDark = derived(theme, ($t) => $t === 'dark');

ROUTING TABLE (trigger → action)

TESTING PATTERNS

// tests/users.test.ts
import { describe, it, expect } from 'vitest';
import { createUserSchema } from '$lib/schemas/user';

describe('createUserSchema', () => {
  it('rejects empty name', () => {
    const result = createUserSchema.safeParse({ name: '', email: 'a@b.com', role: 'member' });
    expect(result.success).toBe(false);
  });

  it('accepts valid data', () => {
    const result = createUserSchema.safeParse({
      name: 'Test User',
      email: 'test@example.com',
      role: 'admin',
    });
    expect(result.success).toBe(true);
  });
});

NAMING CONVENTIONS

ENV VARS

DATABASE_URL=libsql://...turso.io
DATABASE_AUTH_TOKEN=...
SESSION_SECRET=...
PUBLIC_APP_URL=http://localhost:5173

BUILD COMMANDS

npm run dev          # Dev server with HMR
npm run build        # Production build
npm run preview      # Preview production locally
npx svelte-check     # TypeScript + Svelte diagnostics
npm test             # Vitest
npm run test:e2e     # Playwright

QUALITY GATES

□ npx svelte-check — 0 errors □ npm test — all pass □ All form actions validate with Zod via Superforms □ No sensitive data in +page.ts (use +page.server.ts) □ CSP headers configured in svelte.config.js □ hooks.server.ts handles auth globally □ All DB imports from $lib/server/ (never $lib/)

FORBIDDEN

• NEVER import from $lib/server/ in client code (SvelteKit blocks it but don't try)
• NEVER use +page.ts for sensitive data (use +page.server.ts)
• NEVER skip Zod validation in form actions
• NEVER access document/window without browser check from $app/environment
• NEVER use inline <style> when Tailwind classes exist
• NEVER put DB connection strings in PUBLIC_ env vars