@icarusmx/creta 1.5.11 → 1.5.13

package/lib/exercises/05-svelte-first-steps.md

@@ -0,0 +1,1340 @@
+# SvelteKit First Steps - Project Structure Without the Confusion
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 LazyVim Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold under cursor)
+
+This document uses fold markers `{{{` and `}}}` for organized reading.
+
+}}}
+
+## 🚨 Problem: "Where Does This File Go?" {{{
+
+You're building a SvelteKit app and constantly wondering:
+- **"Should this component go in `src/lib` or `src/routes`?"**
+- **"What's the difference between a `.svelte` file and a `+page.svelte` file?"**
+- **"Do I need to write something in `index.js`?"**
+- **"Where do API endpoints go?"**
+
+**Common confusion:**
+- Components scattered between routes and lib
+- Not understanding the `$lib` alias
+- Creating `+server.js` files in the wrong place
+- Overengineering with unnecessary barrel exports
+
+**The root cause:** SvelteKit has special file naming conventions that aren't immediately obvious.
+
+}}}
+
+## ✅ Solution: Understanding SvelteKit's File Structure {{{
+
+SvelteKit uses **file-based routing** with special file names that have specific meanings.
+
+**Think of it like this:**
+- **`src/routes/`** = Your website's pages and API endpoints (what users can visit)
+- **`src/lib/`** = Your shared toolbox (reusable code that powers your pages)
+
+**What SvelteKit gives you:**
+- 📁 **Clear separation** - Routes vs reusable code
+- 🔗 **$lib alias** - Import from anywhere with `$lib/...`
+- 🎯 **Convention over configuration** - Special file names do special things
+- ⚡ **Automatic routing** - File structure = URL structure
+
+**Core concept:** The `src/routes/` folder structure directly maps to your URLs, while `src/lib/` is your private code library.
+
+}}}
+
+## 🎯 Core Concepts {{{
+
+### src/routes/ - Your Website Structure {{{
+
+**What lives here:**
+- Pages users can visit (`+page.svelte`)
+- Layouts that wrap pages (`+layout.svelte`)
+- API endpoints (`+server.js`)
+- Server-side logic (`+page.server.js`, `+layout.server.js`)
+
+**File structure = URL structure:**
+```
+src/routes/
+├── +page.svelte              → /
+├── about/
+│   └── +page.svelte          → /about
+├── blog/
+│   ├── +page.svelte          → /blog
+│   └── [slug]/
+│       └── +page.svelte      → /blog/my-post
+└── api/
+    ├── contact/
+    │   └── +server.js        → /api/contact (POST, GET, etc.)
+    └── users/
+        └── +server.js        → /api/users
+```
+
+**Special files in routes:**
+- `+page.svelte` - A page component
+- `+layout.svelte` - Wraps multiple pages
+- `+server.js` - API endpoint (handles HTTP requests)
+- `+page.server.js` - Server-side page logic
+- `+error.svelte` - Error page
+
+**Example URL mapping:**
+```bash
+src/routes/products/+page.svelte           → https://yoursite.com/products
+src/routes/products/[id]/+page.svelte      → https://yoursite.com/products/123
+src/routes/api/products/+server.js         → https://yoursite.com/api/products
+```
+
+}}}
+
+### src/lib/ - Your Code Toolbox {{{
+
+**What lives here:**
+- Reusable components (`Footer.svelte`, `Navbar.svelte`)
+- Utility functions (`formatDate.js`, `validation.js`)
+- API client code (functions that CALL external APIs)
+- Shared constants and configs
+- Database query functions
+- Any code used by multiple routes
+
+**Common structure:**
+```
+src/lib/
+├── components/
+│   ├── Footer.svelte
+│   ├── Navbar.svelte
+│   └── Button.svelte
+├── utils/
+│   ├── formatDate.js
+│   └── validation.js
+├── api/
+│   └── emailClient.js        # Functions that call external APIs
+├── db/
+│   └── queries.js            # Database helper functions
+└── index.js                  # Optional barrel exports
+```
+
+**The `$lib` alias:**
+```javascript
+// Import from anywhere in your app
+import Footer from '$lib/components/Footer.svelte';
+import { formatDate } from '$lib/utils/formatDate.js';
+import { sendEmail } from '$lib/api/emailClient.js';
+```
+
+**Key insight:** `$lib` is just an alias for `src/lib/`. You can import from ANY file inside `src/lib/` directly using this alias.
+
+}}}
+
+### The Optional index.js {{{
+
+**What it does:**
+`src/lib/index.js` is an **optional convenience file** for barrel exports.
+
+**Without index.js (direct imports):**
+```javascript
+import Footer from '$lib/components/Footer.svelte';
+import Navbar from '$lib/components/Navbar.svelte';
+import { formatDate } from '$lib/utils/formatDate.js';
+```
+
+**With index.js (barrel exports):**
+```javascript
+// src/lib/index.js
+export { default as Footer } from './components/Footer.svelte';
+export { default as Navbar } from './components/Navbar.svelte';
+export { formatDate } from './utils/formatDate.js';
+```
+
+Then you can do:
+```javascript
+import { Footer, Navbar, formatDate } from '$lib';
+```
+
+**When to use it:**
+- ✅ **Use barrel exports** if you have many related exports and want a cleaner import
+- ❌ **Skip it** for simple projects where direct imports are clearer (preferred for most cases)
+
+**Pro tip:** For simple projects, direct imports are more explicit and easier to trace. Don't overengineer with barrel exports unless you have a real need.
+
+}}}
+
+### +server.js - API Endpoints {{{
+
+**IMPORTANT:** `+server.js` files **ONLY** go in `src/routes/`
+
+**What they do:**
+Create API endpoints your app exposes to the world.
+
+**Example - Contact Form API:**
+```javascript
+// src/routes/api/contact/+server.js
+export async function POST({ request }) {
+  const data = await request.json();
+
+  // Process the contact form
+  await sendEmail(data.email, data.message);
+
+  return new Response(
+    JSON.stringify({ success: true }),
+    { headers: { 'Content-Type': 'application/json' } }
+  );
+}
+```
+
+This creates: `https://yoursite.com/api/contact` (POST)
+
+**HTTP methods:**
+```javascript
+// src/routes/api/users/+server.js
+export async function GET() {
+  return new Response(JSON.stringify({ users: [...] }));
+}
+
+export async function POST({ request }) {
+  // Create new user
+}
+
+export async function PUT({ request }) {
+  // Update user
+}
+
+export async function DELETE({ request }) {
+  // Delete user
+}
+```
+
+**Key distinction:**
+- `src/routes/api/**/+server.js` → API endpoints your app **exposes**
+- `src/lib/api/client.js` → Functions that **call** external APIs (helper code)
+
+**You NEVER write `+server.js` files in `src/lib/`** - that's not how it works!
+
+}}}
+
+}}}
+
+## 🏗️ Setting Up Your First SvelteKit Project {{{
+
+### Step 1: Create a New Project {{{
+
+**Using create-svelte:**
+```bash
+# Create new project
+npm create svelte@latest my-app
+
+# Choose options:
+# - SvelteKit demo app (for learning) or Skeleton project
+# - No TypeScript (if you prefer JavaScript)
+# - Add ESLint and Prettier
+
+# Navigate and install
+cd my-app
+npm install
+```
+
+**Start dev server:**
+```bash
+npm run dev -- --open
+# Server runs on http://localhost:5173
+```
+
+**Initial structure:**
+```
+my-app/
+├── src/
+│   ├── routes/
+│   │   └── +page.svelte       # Homepage
+│   ├── lib/
+│   │   └── index.js           # Empty initially
+│   └── app.html               # HTML template
+├── static/                     # Static assets (favicon, images)
+├── svelte.config.js            # SvelteKit config
+└── package.json
+```
+
+}}}
+
+### Step 2: Create Your First Reusable Component {{{
+
+**Create a Navbar component:**
+```bash
+# Create components directory
+mkdir -p src/lib/components
+```
+
+**src/lib/components/Navbar.svelte:**
+```svelte
+<script>
+  let menuOpen = false;
+
+  function toggleMenu() {
+    menuOpen = !menuOpen;
+  }
+</script>
+
+<nav>
+  <div class="logo">MyApp</div>
+  <button on:click={toggleMenu}>Menu</button>
+
+  {#if menuOpen}
+    <ul>
+      <li><a href="/">Home</a></li>
+      <li><a href="/about">About</a></li>
+      <li><a href="/contact">Contact</a></li>
+    </ul>
+  {/if}
+</nav>
+
+<style>
+  nav {
+    padding: 1rem;
+    background: #333;
+    color: white;
+  }
+</style>
+```
+
+**Use it in your layout:**
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import Navbar from '$lib/components/Navbar.svelte';
+</script>
+
+<Navbar />
+<main>
+  <slot />  <!-- Pages render here -->
+</main>
+```
+
+**What happened:**
+- Created reusable Navbar in `src/lib/components/`
+- Imported using `$lib/` alias
+- Used in layout so it appears on all pages
+
+}}}
+
+### Step 3: Create a Page {{{
+
+**Create an About page:**
+```svelte
+<!-- src/routes/about/+page.svelte -->
+<script>
+  import { formatDate } from '$lib/utils/formatDate.js';
+
+  const today = formatDate(new Date());
+</script>
+
+<h1>About Us</h1>
+<p>Page last updated: {today}</p>
+```
+
+**Create the utility function:**
+```javascript
+// src/lib/utils/formatDate.js
+export function formatDate(date) {
+  return date.toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  });
+}
+```
+
+**URL created:** `http://localhost:5173/about`
+
+}}}
+
+### Step 4: Create an API Endpoint {{{
+
+**Create a contact form endpoint:**
+```javascript
+// src/routes/api/contact/+server.js
+import { json } from '@sveltejs/kit';
+
+export async function POST({ request }) {
+  const { name, email, message } = await request.json();
+
+  // Validate
+  if (!email || !message) {
+    return json(
+      { error: 'Email and message are required' },
+      { status: 400 }
+    );
+  }
+
+  // Process (send email, save to DB, etc.)
+  console.log('Contact form:', { name, email, message });
+
+  return json({ success: true });
+}
+```
+
+**Use the endpoint from a page:**
+```svelte
+<!-- src/routes/contact/+page.svelte -->
+<script>
+  let formData = { name: '', email: '', message: '' };
+  let status = '';
+
+  async function handleSubmit(e) {
+    e.preventDefault();
+
+    const response = await fetch('/api/contact', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(formData)
+    });
+
+    const result = await response.json();
+    status = result.success ? 'Message sent!' : 'Error sending message';
+  }
+</script>
+
+<form on:submit={handleSubmit}>
+  <input bind:value={formData.name} placeholder="Name" />
+  <input bind:value={formData.email} placeholder="Email" required />
+  <textarea bind:value={formData.message} placeholder="Message" required />
+  <button type="submit">Send</button>
+</form>
+
+{#if status}
+  <p>{status}</p>
+{/if}
+```
+
+**What happened:**
+1. Created API endpoint at `/api/contact`
+2. Endpoint handles POST requests
+3. Contact form page sends data to the endpoint
+4. All API logic is in `src/routes/api/`
+
+}}}
+
+}}}
+
+## 🎯 Decision Tree: Where Should This File Go? {{{
+
+### Is it a page users can visit? {{{
+
+**YES** → `src/routes/[name]/+page.svelte`
+
+**Examples:**
+- Homepage → `src/routes/+page.svelte`
+- About page → `src/routes/about/+page.svelte`
+- Blog post → `src/routes/blog/[slug]/+page.svelte`
+- User profile → `src/routes/users/[id]/+page.svelte`
+
+}}}
+
+### Is it an API endpoint? {{{
+
+**YES** → `src/routes/api/[name]/+server.js`
+
+**Examples:**
+- Contact form → `src/routes/api/contact/+server.js`
+- User CRUD → `src/routes/api/users/+server.js`
+- Webhook handler → `src/routes/webhook/+server.js`
+
+**Remember:** `+server.js` files **ONLY** go in `src/routes/`!
+
+}}}
+
+### Is it a component used by multiple pages? {{{
+
+**YES** → `src/lib/components/[Name].svelte`
+
+**Examples:**
+- Navbar → `src/lib/components/Navbar.svelte`
+- Footer → `src/lib/components/Footer.svelte`
+- Button → `src/lib/components/Button.svelte`
+- Card → `src/lib/components/Card.svelte`
+
+}}}
+
+### Is it a utility function? {{{
+
+**YES** → `src/lib/utils/[name].js`
+
+**Examples:**
+- Date formatting → `src/lib/utils/formatDate.js`
+- Validation → `src/lib/utils/validation.js`
+- String helpers → `src/lib/utils/strings.js`
+
+}}}
+
+### Does it call external APIs? {{{
+
+**YES** → `src/lib/api/[name].js`
+
+**Examples:**
+- Email service → `src/lib/api/emailClient.js`
+- Payment processing → `src/lib/api/stripe.js`
+- External API wrapper → `src/lib/api/github.js`
+
+}}}
+
+### Is it database-related? {{{
+
+**YES** → `src/lib/db/[name].js`
+
+**Examples:**
+- Database queries → `src/lib/db/queries.js`
+- Database connection → `src/lib/db/connection.js`
+- ORM models → `src/lib/db/models.js`
+
+}}}
+
+### Is it server-only page logic? {{{
+
+**YES** → `src/routes/[path]/+page.server.js`
+
+**Use case:** Load data on the server before rendering the page
+
+**Example:**
+```javascript
+// src/routes/blog/[slug]/+page.server.js
+export async function load({ params }) {
+  const post = await db.getPost(params.slug);
+  return { post };
+}
+```
+
+}}}
+
+}}}
+
+## 🧪 Practice Exercises {{{
+
+### Exercise 1: Build a Reusable Card Component {{{
+
+**Goal:** Create a card component in `src/lib` and use it on multiple pages
+
+**Create the component:**
+```svelte
+<!-- src/lib/components/Card.svelte -->
+<script>
+  export let title;
+  export let description;
+  export let href = null;
+</script>
+
+<div class="card">
+  <h3>{title}</h3>
+  <p>{description}</p>
+  {#if href}
+    <a {href}>Learn more →</a>
+  {/if}
+</div>
+
+<style>
+  .card {
+    border: 1px solid #ddd;
+    border-radius: 8px;
+    padding: 1.5rem;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+  }
+
+  h3 {
+    margin-top: 0;
+  }
+</style>
+```
+
+**Use it on homepage:**
+```svelte
+<!-- src/routes/+page.svelte -->
+<script>
+  import Card from '$lib/components/Card.svelte';
+</script>
+
+<h1>Welcome</h1>
+
+<div class="grid">
+  <Card
+    title="Feature 1"
+    description="Amazing feature description"
+    href="/features/1"
+  />
+  <Card
+    title="Feature 2"
+    description="Another cool feature"
+    href="/features/2"
+  />
+</div>
+
+<style>
+  .grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+    gap: 1rem;
+  }
+</style>
+```
+
+**Key learning:** Components in `src/lib/components/` can be reused anywhere with the `$lib` alias.
+
+}}}
+
+### Exercise 2: Create a Todo API {{{
+
+**Goal:** Build a simple todo API with GET and POST endpoints
+
+**Create the API endpoint:**
+```javascript
+// src/routes/api/todos/+server.js
+import { json } from '@sveltejs/kit';
+
+// In-memory storage (would be a database in production)
+let todos = [
+  { id: 1, text: 'Learn SvelteKit', done: false },
+  { id: 2, text: 'Build an app', done: false }
+];
+
+let nextId = 3;
+
+// GET all todos
+export async function GET() {
+  return json(todos);
+}
+
+// POST new todo
+export async function POST({ request }) {
+  const { text } = await request.json();
+
+  if (!text) {
+    return json({ error: 'Text is required' }, { status: 400 });
+  }
+
+  const newTodo = {
+    id: nextId++,
+    text,
+    done: false
+  };
+
+  todos.push(newTodo);
+  return json(newTodo, { status: 201 });
+}
+
+// DELETE todo
+export async function DELETE({ request }) {
+  const { id } = await request.json();
+  todos = todos.filter(todo => todo.id !== id);
+  return json({ success: true });
+}
+```
+
+**Create a page to use the API:**
+```svelte
+<!-- src/routes/todos/+page.svelte -->
+<script>
+  import { onMount } from 'svelte';
+
+  let todos = [];
+  let newTodoText = '';
+
+  onMount(async () => {
+    await loadTodos();
+  });
+
+  async function loadTodos() {
+    const response = await fetch('/api/todos');
+    todos = await response.json();
+  }
+
+  async function addTodo() {
+    if (!newTodoText.trim()) return;
+
+    await fetch('/api/todos', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text: newTodoText })
+    });
+
+    newTodoText = '';
+    await loadTodos();
+  }
+
+  async function deleteTodo(id) {
+    await fetch('/api/todos', {
+      method: 'DELETE',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id })
+    });
+
+    await loadTodos();
+  }
+</script>
+
+<h1>My Todos</h1>
+
+<form on:submit|preventDefault={addTodo}>
+  <input bind:value={newTodoText} placeholder="New todo..." />
+  <button type="submit">Add</button>
+</form>
+
+<ul>
+  {#each todos as todo}
+    <li>
+      {todo.text}
+      <button on:click={() => deleteTodo(todo.id)}>Delete</button>
+    </li>
+  {/each}
+</ul>
+```
+
+**What you built:**
+- API endpoint at `/api/todos` with GET, POST, DELETE
+- Todo list page at `/todos` that uses the API
+- Full CRUD operations for todos
+
+}}}
+
+### Exercise 3: Organize a Full App Structure {{{
+
+**Goal:** Build a blog with proper file organization
+
+**Structure:**
+```
+src/
+├── lib/
+│   ├── components/
+│   │   ├── Navbar.svelte
+│   │   ├── Footer.svelte
+│   │   └── BlogCard.svelte
+│   ├── utils/
+│   │   ├── formatDate.js
+│   │   └── slugify.js
+│   └── db/
+│       └── posts.js          # Mock database
+└── routes/
+    ├── +layout.svelte         # App layout with Navbar/Footer
+    ├── +page.svelte           # Homepage
+    ├── blog/
+    │   ├── +page.svelte       # Blog list
+    │   ├── +page.server.js    # Load posts
+    │   └── [slug]/
+    │       ├── +page.svelte   # Single post
+    │       └── +page.server.js
+    └── api/
+        └── posts/
+            └── +server.js     # Posts API
+```
+
+**Mock database:**
+```javascript
+// src/lib/db/posts.js
+export const posts = [
+  {
+    slug: 'svelte-basics',
+    title: 'SvelteKit Basics',
+    excerpt: 'Learn the fundamentals...',
+    content: 'Full post content here...',
+    date: new Date('2025-01-01')
+  },
+  {
+    slug: 'routing-guide',
+    title: 'Routing in SvelteKit',
+    excerpt: 'Understanding file-based routing...',
+    content: 'Full routing guide...',
+    date: new Date('2025-01-15')
+  }
+];
+
+export function getAllPosts() {
+  return posts;
+}
+
+export function getPostBySlug(slug) {
+  return posts.find(post => post.slug === slug);
+}
+```
+
+**Blog list page:**
+```javascript
+// src/routes/blog/+page.server.js
+import { getAllPosts } from '$lib/db/posts.js';
+
+export function load() {
+  const posts = getAllPosts();
+  return { posts };
+}
+```
+
+```svelte
+<!-- src/routes/blog/+page.svelte -->
+<script>
+  export let data;
+  import BlogCard from '$lib/components/BlogCard.svelte';
+</script>
+
+<h1>Blog</h1>
+
+<div class="posts">
+  {#each data.posts as post}
+    <BlogCard {post} />
+  {/each}
+</div>
+```
+
+**Single post page:**
+```javascript
+// src/routes/blog/[slug]/+page.server.js
+import { getPostBySlug } from '$lib/db/posts.js';
+import { error } from '@sveltejs/kit';
+
+export function load({ params }) {
+  const post = getPostBySlug(params.slug);
+
+  if (!post) {
+    throw error(404, 'Post not found');
+  }
+
+  return { post };
+}
+```
+
+```svelte
+<!-- src/routes/blog/[slug]/+page.svelte -->
+<script>
+  export let data;
+  import { formatDate } from '$lib/utils/formatDate.js';
+</script>
+
+<article>
+  <h1>{data.post.title}</h1>
+  <time>{formatDate(data.post.date)}</time>
+  <div class="content">
+    {@html data.post.content}
+  </div>
+</article>
+```
+
+**Key learning:** Proper separation of concerns - components in `lib/`, pages in `routes/`, data logic in `lib/db/`.
+
+}}}
+
+}}}
+
+## 🛡️ Best Practices {{{
+
+### Keep Routes Clean {{{
+
+**❌ Bad - Logic in page component:**
+```svelte
+<!-- src/routes/users/+page.svelte -->
+<script>
+  import { onMount } from 'svelte';
+
+  let users = [];
+
+  onMount(async () => {
+    const response = await fetch('https://api.example.com/users');
+    users = await response.json();
+  });
+</script>
+```
+
+**✅ Good - Logic in server file:**
+```javascript
+// src/routes/users/+page.server.js
+export async function load({ fetch }) {
+  const response = await fetch('https://api.example.com/users');
+  const users = await response.json();
+  return { users };
+}
+```
+
+```svelte
+<!-- src/routes/users/+page.svelte -->
+<script>
+  export let data;
+</script>
+
+<h1>Users</h1>
+{#each data.users as user}
+  <p>{user.name}</p>
+{/each}
+```
+
+**Why:** Server-side loading is faster and more secure (API keys stay on server).
+
+}}}
+
+### Extract Reusable Logic to $lib {{{
+
+**❌ Bad - Duplicated validation:**
+```svelte
+<!-- src/routes/contact/+page.svelte -->
+<script>
+  function validateEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  }
+</script>
+```
+
+```svelte
+<!-- src/routes/signup/+page.svelte -->
+<script>
+  function validateEmail(email) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+  }
+</script>
+```
+
+**✅ Good - Shared utility:**
+```javascript
+// src/lib/utils/validation.js
+export function validateEmail(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+```
+
+```svelte
+<!-- Both pages -->
+<script>
+  import { validateEmail } from '$lib/utils/validation.js';
+</script>
+```
+
+}}}
+
+### Use Proper Import Paths {{{
+
+**❌ Bad - Relative imports:**
+```javascript
+import Footer from '../../lib/components/Footer.svelte';
+import { formatDate } from '../../../lib/utils/formatDate.js';
+```
+
+**✅ Good - $lib alias:**
+```javascript
+import Footer from '$lib/components/Footer.svelte';
+import { formatDate } from '$lib/utils/formatDate.js';
+```
+
+**Why:** Easier to refactor, clearer intent, no need to count `../`.
+
+}}}
+
+### Separate API Client from API Routes {{{
+
+**Confusion to avoid:**
+```
+src/routes/api/email/+server.js  ← API endpoint you expose
+src/lib/api/email.js             ← Helper that calls external email service
+```
+
+**Example:**
+```javascript
+// src/lib/api/emailClient.js
+// Helper function that calls SendGrid (external API)
+export async function sendEmail(to, subject, body) {
+  const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${import.meta.env.VITE_SENDGRID_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ to, subject, body })
+  });
+  return response.json();
+}
+```
+
+```javascript
+// src/routes/api/contact/+server.js
+// Your API endpoint that uses the helper
+import { json } from '@sveltejs/kit';
+import { sendEmail } from '$lib/api/emailClient.js';
+
+export async function POST({ request }) {
+  const { email, message } = await request.json();
+  await sendEmail(email, 'Contact Form', message);
+  return json({ success: true });
+}
+```
+
+**Remember:**
+- `src/lib/api/` = Functions that CALL external APIs (tools)
+- `src/routes/api/` = Endpoints your app EXPOSES (routes)
+
+}}}
+
+### Don't Overengineer with Barrel Exports {{{
+
+**❌ Overkill for small projects:**
+```javascript
+// src/lib/index.js
+export { default as Navbar } from './components/Navbar.svelte';
+export { default as Footer } from './components/Footer.svelte';
+export { default as Button } from './components/Button.svelte';
+export { formatDate } from './utils/formatDate.js';
+export { validateEmail } from './utils/validation.js';
+// ... 50 more exports
+```
+
+**✅ Keep it simple:**
+```javascript
+// Just import directly
+import Navbar from '$lib/components/Navbar.svelte';
+import { formatDate } from '$lib/utils/formatDate.js';
+```
+
+**When barrel exports make sense:**
+- You have a component library with 20+ components
+- You want consistent import patterns across a large team
+- You're building a published package
+
+**For most projects:** Direct imports are clearer and easier to maintain.
+
+}}}
+
+}}}
+
+## 📚 Quick Reference {{{
+
+### File Naming Conventions {{{
+
+```
++page.svelte           → Page component (URL endpoint)
++page.server.js        → Server-side page logic
++layout.svelte         → Layout wrapping multiple pages
++layout.server.js      → Server-side layout logic
++server.js             → API endpoint (GET, POST, etc.)
++error.svelte          → Error page
+```
+
+}}}
+
+### Directory Mapping {{{
+
+```
+src/routes/            → Pages and API endpoints (public URLs)
+src/lib/               → Reusable code (internal)
+  ├── components/      → Reusable UI components
+  ├── utils/           → Helper functions
+  ├── api/             → External API client functions
+  ├── db/              → Database queries and models
+  └── index.js         → Optional barrel exports
+
+static/                → Static assets (images, fonts)
+  └── favicon.png      → Available at /favicon.png
+```
+
+}}}
+
+### Import Patterns {{{
+
+```javascript
+// Components
+import Navbar from '$lib/components/Navbar.svelte';
+import Footer from '$lib/components/Footer.svelte';
+
+// Utilities
+import { formatDate } from '$lib/utils/formatDate.js';
+import { validateEmail } from '$lib/utils/validation.js';
+
+// API clients
+import { sendEmail } from '$lib/api/emailClient.js';
+
+// Database
+import { getUsers } from '$lib/db/queries.js';
+
+// From static folder
+<img src="/logo.png" alt="Logo">
+```
+
+}}}
+
+### Common Patterns {{{
+
+**Load data server-side:**
+```javascript
+// +page.server.js
+export async function load() {
+  const data = await fetchData();
+  return { data };
+}
+```
+
+**Create API endpoint:**
+```javascript
+// +server.js
+import { json } from '@sveltejs/kit';
+
+export async function POST({ request }) {
+  const data = await request.json();
+  return json({ success: true });
+}
+```
+
+**Dynamic routes:**
+```
+src/routes/blog/[slug]/+page.svelte       → /blog/anything
+src/routes/users/[id]/+page.svelte        → /users/123
+src/routes/[...catchall]/+page.svelte     → Matches everything
+```
+
+}}}
+
+}}}
+
+## 🐛 Troubleshooting {{{
+
+### "$lib not found" Error {{{
+
+**Symptom:**
+```
+Error: Cannot find module '$lib/components/Navbar.svelte'
+```
+
+**Common causes:**
+1. File doesn't exist at that path
+2. Wrong file extension (`.svelte` vs `.js`)
+3. Typo in path
+
+**Fix:**
+```bash
+# Verify file exists
+ls src/lib/components/Navbar.svelte
+
+# Check import statement matches actual file name (case-sensitive)
+import Navbar from '$lib/components/Navbar.svelte';  # Correct
+import Navbar from '$lib/components/navbar.svelte';  # Wrong if file is Navbar.svelte
+```
+
+}}}
+
+### "Cannot read property of undefined" in Component {{{
+
+**Symptom:**
+```javascript
+<!-- BlogCard.svelte -->
+<h2>{post.title}</h2>  <!-- Error: post is undefined -->
+```
+
+**Common cause:** Forgot to export the prop
+
+**Fix:**
+```svelte
+<script>
+  export let post;  // Must export props!
+</script>
+
+<h2>{post.title}</h2>
+```
+
+}}}
+
+### API Endpoint Not Working {{{
+
+**Symptom:**
+```
+404 Not Found when calling /api/contact
+```
+
+**Checklist:**
+```bash
+# 1. Verify file exists at correct location
+ls src/routes/api/contact/+server.js
+
+# 2. Check file exports HTTP methods
+# File must export: GET, POST, PUT, DELETE, etc.
+
+# 3. Restart dev server
+# Sometimes needed after creating new +server.js files
+Ctrl+C
+npm run dev
+```
+
+**Common mistake:**
+```javascript
+// ❌ Wrong - not exporting
+async function POST() { ... }
+
+// ✅ Correct
+export async function POST() { ... }
+```
+
+}}}
+
+### Layout Not Applying to Page {{{
+
+**Symptom:** Navbar/Footer not showing on a page
+
+**Cause:** Layout must be in parent directory
+
+**Structure:**
+```
+src/routes/
+├── +layout.svelte           ← Applies to ALL pages
+├── +page.svelte             ← Homepage (has layout)
+└── blog/
+    ├── +layout.svelte       ← Applies only to /blog routes
+    └── +page.svelte         ← Blog page (has both layouts)
+```
+
+**Layout must have `<slot />`:**
+```svelte
+<!-- +layout.svelte -->
+<Navbar />
+<slot />  <!-- Pages render here -->
+<Footer />
+```
+
+}}}
+
+### Component Not Re-rendering {{{
+
+**Symptom:** Component doesn't update when data changes
+
+**Common cause:** Not using reactive statements
+
+**Fix with Svelte 5 runes:**
+```svelte
+<script>
+  // Old way (Svelte 4)
+  let count = 0;
+  $: doubled = count * 2;  // Reactive statement
+
+  // New way (Svelte 5)
+  let count = $state(0);
+  let doubled = $derived(count * 2);  // Derived state
+</script>
+```
+
+}}}
+
+}}}
+
+## 💡 Pro Tips {{{
+
+1. **Use +page.server.js for data fetching:**
+   - Keeps API keys secure
+   - Faster initial load
+   - Better SEO
+
+2. **Colocate related route files:**
+   ```
+   src/routes/blog/[slug]/
+   ├── +page.svelte
+   ├── +page.server.js
+   └── BlogComments.svelte  ← Component only used by this page
+   ```
+
+3. **Use +layout.svelte for shared UI:**
+   ```svelte
+   <!-- src/routes/+layout.svelte -->
+   <script>
+     import Navbar from '$lib/components/Navbar.svelte';
+     import Footer from '$lib/components/Footer.svelte';
+   </script>
+
+   <Navbar />
+   <main>
+     <slot />  <!-- All pages render here -->
+   </main>
+   <Footer />
+   ```
+
+4. **Organize by feature, not file type:**
+   ```
+   ✅ Good:
+   src/lib/
+   ├── auth/
+   │   ├── Login.svelte
+   │   ├── Signup.svelte
+   │   └── auth.js
+   └── blog/
+       ├── BlogCard.svelte
+       └── blogUtils.js
+
+   ❌ Less maintainable:
+   src/lib/
+   ├── components/
+   │   ├── Login.svelte
+   │   ├── Signup.svelte
+   │   └── BlogCard.svelte
+   └── utils/
+       ├── auth.js
+       └── blogUtils.js
+   ```
+
+5. **Use TypeScript JSDoc for better autocomplete (without TypeScript):**
+   ```javascript
+   // src/lib/utils/formatDate.js
+   /**
+    * Format a date for display
+    * @param {Date} date - The date to format
+    * @returns {string} Formatted date string
+    */
+   export function formatDate(date) {
+     return date.toLocaleDateString();
+   }
+   ```
+
+6. **Create a $lib/config.js for constants:**
+   ```javascript
+   // src/lib/config.js
+   export const SITE_NAME = 'My Awesome App';
+   export const MAX_UPLOAD_SIZE = 5 * 1024 * 1024; // 5MB
+   export const API_URL = import.meta.env.VITE_API_URL;
+   ```
+
+7. **Use the static/ folder for public assets:**
+   ```
+   static/
+   ├── favicon.png        → /favicon.png
+   ├── logo.svg           → /logo.svg
+   └── images/
+       └── hero.jpg       → /images/hero.jpg
+   ```
+
+   ```svelte
+   <img src="/images/hero.jpg" alt="Hero">
+   ```
+
+8. **Create error pages:**
+   ```svelte
+   <!-- src/routes/+error.svelte -->
+   <script>
+     import { page } from '$app/stores';
+   </script>
+
+   <h1>{$page.status}: {$page.error.message}</h1>
+   ```
+
+}}}
+
+## 🚀 Next Steps {{{
+
+**Master these progressively:**
+
+1. ✅ **Level 1:** Understand `src/routes` vs `src/lib`
+2. ✅ **Level 2:** Create reusable components with `$lib`
+3. ✅ **Level 3:** Build API endpoints with `+server.js`
+4. 🎯 **Level 4:** Server-side data loading with `+page.server.js`
+5. 🎯 **Level 5:** Advanced routing (layouts, groups, optional params)
+6. 🎯 **Level 6:** Form actions and progressive enhancement
+
+**Related concepts:**
+- **SvelteKit routing** - Nested layouts, dynamic routes, route groups
+- **Form actions** - Handle form submissions without JavaScript
+- **Stores** - Global state management with `$app/stores`
+- **Hooks** - Intercept requests with `hooks.server.js`
+- **Adapters** - Deploy to Vercel, Netlify, Node.js, etc.
+
+**Resources:**
+- SvelteKit Docs: https://svelte.dev/docs/kit
+- Svelte Tutorial: https://svelte.dev/tutorial
+- SvelteKit LLM Docs: https://svelte.dev/docs/kit/llms-small.txt
+
+}}}
+
+---
+
+**Remember:** File structure in SvelteKit is intuitive once you understand the core principle: `src/routes/` is for URLs (pages and APIs), `src/lib/` is for your code toolbox. When in doubt, ask: "Do users visit this directly?" If yes → routes. If no → lib. 🚀