Project Setup Checklist

Checklist này giúp bạn thiết lập dự án SvelteKit hoặc Astro một cách chuẩn chỉnh ngay từ đầu, tránh các lỗi thường gặp về sau.

Phase 1: Khởi tạo Project

Yêu cầu hệ thống

Khởi tạo

SvelteKit:

npm create svelte@latest my-project
cd my-project
npm install
npm run dev

Astro:

npm create astro@latest my-project
cd my-project
npm install
npm run dev

Phase 2: Cấu trúc Folder

SvelteKit Structure

my-project/
├── src/
│   ├── lib/              # Components, utilities
│   │   ├── components/   # Reusable components
│   │   │   ├── ui/       # UI primitives
│   │   │   └── layout/   # Layout components
│   │   ├── stores/       # Svelte stores
│   │   └── utils/        # Helper functions
│   ├── routes/           # File-based routing
│   │   ├── +layout.svelte
│   │   ├── +page.svelte
│   │   └── +error.svelte
│   ├── app.html          # HTML template
│   └── app.css           # Global styles
├── static/               # Static assets
├── tests/                # Test files
├── svelte.config.js
├── vite.config.js
└── package.json

Astro + Starlight Structure

my-project/
├── src/
│   ├── components/       # Svelte/React components
│   ├── content/
│   │   └── docs/         # Documentation pages
│   ├── styles/           # Global CSS
│   └── assets/           # Images, fonts
├── public/               # Static files
├── astro.config.mjs
└── package.json

Phase 3: CSS & Styling Setup

Global CSS (app.css / custom.css)

/* ✅ ĐÚNG - Định nghĩa đầy đủ */
:root {
  /* Colors */
  --color-primary: #e11d48;
  --color-base-100: #f8fafc;
  --color-base-content: #1e293b;

  /* Typography */
  --font-body: 'Inter', sans-serif;
  --font-mono: 'Fira Code', monospace;

  /* Spacing */
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
}

/* Navigation - Luôn định nghĩa font-size */
.nav-link {
  font-size: 1rem;        /* ← Quan trọng! */
  font-weight: 500;
  color: var(--color-base-content);
}

/* Không dùng opacity cho hover */
.nav-link:hover {
  color: var(--color-primary);  /* Thay vì opacity: 1 */
}

CSS Reset

/* Reset cơ bản */
*, *::before, *::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

html {
  font-size: 16px;
  scroll-behavior: smooth;
}

body {
  font-family: var(--font-body);
  line-height: 1.6;
  color: var(--color-base-content);
  background: var(--color-base-100);
}

img {
  max-width: 100%;
  height: auto;
}

Phase 4: Component Library

UI Components cơ bản

Nên tạo trước các components:

Component Template

<script lang="ts">
  // Props với TypeScript
  interface Props {
    title: string;
    variant?: 'primary' | 'secondary';
  }

  export let title: string;
  export let variant: 'primary' | 'secondary' = 'primary';

  // Reactive state
  $: classes = `component component-${variant}`;
</script>

<div class={classes}>
  <h2>{title}</h2>
  <slot />
</div>

<style>
  .component {
    /* Dùng CSS variables */
    background: var(--color-base-100);
    border: 1px solid var(--color-border);
  }

  .component-primary {
    background: var(--color-primary);
    color: white;
  }
</style>

Phase 5: Dark Mode

CSS Variables Approach

/* Light theme (default) */
:root {
  --color-base-100: #f8fafc;
  --color-base-content: #1e293b;
}

/* Dark theme */
[data-theme="dark"] {
  --color-base-100: #0f172a;
  --color-base-content: #f8fafc;
}

Svelte Toggle Component

<script>
  let theme = 'light';

  function toggleTheme() {
    theme = theme === 'light' ? 'dark' : 'light';
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
  }

  // Load saved theme
  import { onMount } from 'svelte';
  onMount(() => {
    const saved = localStorage.getItem('theme');
    if (saved) {
      theme = saved;
      document.documentElement.setAttribute('data-theme', theme);
    }
  });
</script>

<button on:click={toggleTheme}>
  {theme === 'light' ? '🌙' : '☀️'}
</button>

Phase 6: Pre-launch Checklist

Functionality

Tất cả routes hoạt động đúng
Navigation giữa các trang mượt mà
Form validation hoạt động
Error handling đầy đủ

Performance

Lazy load components nặng
Optimize images (WebP, lazy loading)
Minimize CSS/JS bundle
Check Core Web Vitals

Responsive

Test trên mobile (375px)
Test trên tablet (768px)
Test trên desktop (1440px)
Touch targets đủ lớn (44px+)

Accessibility

Alt text cho images
ARIA labels cho interactive elements
Color contrast đạt chuẩn WCAG AA
Keyboard navigation hoạt động

SEO

Meta tags đầy đủ (title, description, OG)
Semantic HTML
Sitemap.xml
Robots.txt

Phase 7: Deployment

Build & Test

# Build production
npm run build

# Preview locally
npm run preview

Deploy Options

Platform	Lệnh	Lưu ý
Vercel	`vercel --prod`	Tự động detect framework
Netlify	`netlify deploy --prod`	Cần netlify.toml
Cloudflare Pages	Git integration	Build command: `npm run build`