Getting Started Guide

This guide will help you set up your development environment and get started with the theme.

Quick Start

Prerequisites

• Node.js 18+ or Bun 1.0+
• Docker (recommended)
• Git
• Code editor (VS Code recommended)

Installation

1. Clone the Repository

   git clone https://github.com/your-org/theme-name.git
   cd theme-name

2. Using Docker (Recommended)

   # Start development environment
   docker compose up -d
   
   # View logs (optional)
   docker compose logs -f
   
   # Stop environment
   docker compose down

3. Local Development

   # Install dependencies
   bun install
   
   # Start development server
   bun run dev

4. Access the Site

   • Development: http://localhost:4322
   • Documentation: http://localhost:4322/showcase

Development Environment

Docker Setup

We use Docker for consistent development environments:

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: development
    ports:
      - "4322:4322"
    volumes:
      - .:/app
      - node_modules:/app/node_modules

Development Commands

# Add a new UI component
docker compose exec app bun run ui:add button

# Run tests
docker compose exec app bun run test

# Build for production
docker compose exec app bun run build

Local Setup

If you prefer local development:

1. Environment Variables

   # Copy example env
   cp .env.example .env

2. IDE Setup (VS Code)

   // Recommended extensions
   {
     "recommendations": [
       "astro-build.astro-vscode",
       "bradlc.vscode-tailwindcss",
       "dbaeumer.vscode-eslint"
     ]
   }

3. Development Commands

   # Start dev server
   bun run dev
   
   # Type checking
   bun run typecheck
   
   # Linting
   bun run lint

Project Structure

src/
├── components/         # UI Components
│   ├── ui/            # Base UI components
│   ├── layout/        # Layout components
│   └── forms/         # Form components
├── content/           # Content collections
│   ├── posts/         # Blog posts
│   └── showcase/      # Documentation
├── styles/            # Global styles
│   └── tokens/        # Design tokens
└── types/             # TypeScript types

Configuration Files

1. TypeScript (tsconfig.json)

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

2. Tailwind (tailwind.config.mjs)

export default {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
  theme: {
    extend: {
      // Theme extensions
    }
  }
}

3. Astro (astro.config.mjs)

export default defineConfig({
  integrations: [
    react(),
    tailwind(),
    mdx()
  ],
  output: 'static'
})

Development Workflow

1. Start Development

   # With Docker
   docker compose up -d
   
   # Local
   bun run dev

2. Adding Components

   # Add shadcn/ui component
   bun run ui:add button
   
   # Create custom component
   touch src/components/ui/MyComponent.tsx

3. Content Updates

   # Add new post
   touch src/content/posts/my-post.mdx
   
   # Add documentation
   touch src/content/showcase/my-guide.mdx

4. Testing Changes

   # Type checking
   bun run typecheck
   
   # Run tests
   bun run test
   
   # Build check
   bun run build

Common Tasks

Adding a New Page

1. Create the page:

   touch src/pages/my-page.astro

2. Basic page structure:

   ---
   import BaseLayout from '@/layouts/BaseLayout.astro';
   ---
   
   <BaseLayout title="My Page">
     <main class="container">
       <h1>My Page</h1>
     </main>
   </BaseLayout>

Creating a New Component

1. Create component file:

   touch src/components/ui/MyComponent.tsx

2. Component template:

   import { cn } from "@/lib/utils";
   
   interface Props {
     className?: string;
   }
   
   export function MyComponent({ className }: Props) {
     return (
       <div className={cn("base-styles", className)}>
         {/* Content */}
       </div>
     );
   }

Adding Content

1. Create content file:

   touch src/content/posts/my-post.mdx

2. Content template:

   ---
   title: "My Post"
   description: "Post description"
   publicationDate: 2025-01-19
   ---
   
   # My Post
   
   Content goes here...

Build & Deployment

Production Build

# Build the site
bun run build

# Preview build
bun run preview

Environment Variables

Required environment variables:

# Required
PUBLIC_SITE_URL=https://example.com

# Optional
PUBLIC_GA_ID=G-XXXXXXXXXX

Troubleshooting

Common Issues

1. Build Errors

   • Check Node.js/Bun version
   • Verify all dependencies are installed
   • Run bun install to refresh dependencies

2. Type Errors

   • Run bun run typecheck for detailed errors
   • Check import paths and types
   • Verify component props

3. Docker Issues

   • Ensure Docker is running
   • Try rebuilding: docker compose build --no-cache
   • Check container logs: docker compose logs

Getting Help

1. Check documentation in /showcase
2. Search GitHub issues
3. Create a new issue with:
   • Environment details
   • Steps to reproduce
   • Expected vs actual behavior

Next Steps

1. Review the Theme System Guide
2. Explore Component Variants
3. Read the Module System Guide
4. Check Token System documentation