Quick Start Guide

Get up and running with Constellation in 10 minutes.

1. Setup (2 minutes)

# Clone repository
git clone https://github.com/your-org/constellation.git
cd constellation

# Install dependencies
bun install

# Create environment file
cp .env.example .env.local

# Start development server
bun dev

Open http://localhost:3000 in your browser. ✅

---

2. Understand Project Structure (2 minutes)

src/
├── app/              ← Next.js pages (routes)
├── components/       ← Reusable React components
├── features/         ← Feature-specific logic
├── hooks/            ← Custom React hooks
├── services/         ← API communication
├── lib/              ← Utilities & helpers
├── types/            ← TypeScript definitions
└── i18n/             ← Multi-language support

Key Insight: Components go in src/components/, pages go in src/app/, logic goes in src/lib/ or src/services/.

---

3. Create Your First Component (3 minutes)

Create src/components/common/MyFirstComponent.tsx:

'use client'; // Mark as client component

import React from 'react';

export function MyFirstComponent() {
  const [count, setCount] = React.useState(0);

  return (
    <div className="p-4 border rounded-lg">
      <h2 className="text-xl font-bold mb-4">My First Component</h2>
      <p className="text-gray-600 mb-4">Count: {count}</p>
      <button
        onClick={() => setCount(count + 1)}
        className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
      >
        Increment
      </button>
    </div>
  );
}

Key Points: - Use 'use client' for interactive components - Use Tailwind classes for styling (e.g., className="p-4 border rounded-lg") - Export as named export

---

4. Use the Component (2 minutes)

Update src/app/page.tsx:

import { MyFirstComponent } from '@/src/components/common/MyFirstComponent';

export default function Home() {
  return (
    <main className="container mx-auto py-10">
      <h1 className="text-3xl font-bold mb-8">Welcome to Constellation</h1>
      <MyFirstComponent />
    </main>
  );
}

Refresh browser at http://localhost:3000 - your component appears! ✅

---

5. Write a Test (1 minute)

Create src/components/common/MyFirstComponent.test.tsx:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MyFirstComponent } from './MyFirstComponent';

describe('MyFirstComponent', () => {
  it('should render and increment count', async () => {
    const user = userEvent.setup();
    render(<MyFirstComponent />);

    const button = screen.getByRole('button', { name: /increment/i });
    await user.click(button);

    expect(screen.getByText(/count: 1/i)).toBeInTheDocument();
  });
});

Run test:

bun test

Output: ✅ Test passes

---

6. Run Linter (1 minute)

# Check code quality
bun lint

# Auto-fix issues
bun lint --fix

---

Common Tasks

Add API Call

import { useEffect, useState } from 'react';
import { apiClient } from '@/src/lib/api';

export function DataComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchData() {
      try {
        const result = await apiClient.get('/api/data');
        setData(result);
      } finally {
        setLoading(false);
      }
    }
    fetchData();
  }, []);

  if (loading) return <div>Loading...</div>;
  return <div>{JSON.stringify(data)}</div>;
}

Use Custom Hook

import { useMobile } from '@/src/hooks/use-mobile';

export function ResponsiveComponent() {
  const isMobile = useMobile();

  return (
    <div className={isMobile ? 'text-sm' : 'text-lg'}>
      Content
    </div>
  );
}

Create Form with Validation

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
});

export function MyForm() {
  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema),
  });

  return (
    <form onSubmit={handleSubmit(async (data) => {
      console.log(data);
    })}>
      <input {...register('email')} placeholder="Email" />
      {errors.email && <span>{errors.email.message}</span>}

      <input {...register('name')} placeholder="Name" />
      {errors.name && <span>{errors.name.message}</span>}

      <button type="submit">Submit</button>
    </form>
  );
}

Use i18n (Multi-language)

import { useTranslation } from '@/src/i18n/i18n';

export function GreetingComponent() {
  const t = useTranslation();

  return <h1>{t('greeting')}</h1>;
}

---

Useful Commands Reference

Command	Purpose
bun dev	Start dev server
bun build	Build for production
bun test	Run tests (watch mode)
bun test:run	Run tests once
bun test:ui	Interactive test UI
bun lint	Check code style
bun lint --fix	Auto-fix code style

---

Next Steps

1. 📖 SETUP_GUIDE.md - Full environment setup
2. 🏗️ ARCHITECTURE.md - Understand project structure
3. 📚 COMPONENTS.md - Component library reference
4. 🎨 STYLING.md - Tailwind CSS guide
5. 🧪 TESTING.md - Testing strategies

---

Troubleshooting

Dev server won't start? → Check .env.local has correct backend URLs, then restart

Tests failing? → Run bun install to ensure all dependencies are installed

Linter errors? → Run bun lint --fix to auto-fix most issues

---

What You've Learned

✅ Created a React component
✅ Added it to a page
✅ Wrote a test for it
✅ Fixed linting issues
✅ Ran the development server

Congratulations! You're ready to develop Constellation! 🚀

---

Next: Read the full ARCHITECTURE.md to understand the bigger picture.