Skip to content

getting-started.md

Latest commit

 

History

History
201 lines (145 loc) · 4.06 KB

getting-started.md

File metadata and controls

201 lines (145 loc) · 4.06 KB
Raw

Getting Started Guide

Prerequisites

  • Node.js >= 22.0.0
  • pnpm (recommended package manager)
  • Git for version control

Installation

1. Clone the project

git clone <repository-url>
cd ocobo-website

2. Install dependencies

pnpm install

3. Generate style system

pnpm prepare

Environment Configuration

Environment Variables

Create a .env.local file:

# Content Source (local for dev, github for prod)
CONTENT_SOURCE=locale

# To use GitHub as source (optional in dev)
GITHUB_ACCOUNT=your-account
GITHUB_REPO=your-content-repo
GITHUB_ACCESS_TOKEN=your-token
GITHUB_BRANCH=main

# AGO Chat widget (optional)
AGO_API_KEY=your-key
AGO_BASEPATH=your-base-path

Content Sources

Local Development (Recommended)

# Uses local files from ~/projects/ocobo-posts/
pnpm dev:local

Development with GitHub

# Uses GitHub API (like production)
pnpm dev:github

Essential Commands

Development

# Start development server
pnpm dev                 # Automatic source based on CONTENT_SOURCE
pnpm dev:local          # Force use of local files
pnpm dev:github         # Force use of GitHub API

# Generate style system (after token changes)
pnpm prepare

# Code verification
pnpm check              # Linting and formatting
pnpm check:fix          # Automatic fix
pnpm typecheck          # Type verification

Tests

pnpm test               # Unit tests
pnpm test:watch        # Tests in watch mode
pnpm test:coverage     # Code coverage

Production

pnpm build             # Production build
pnpm start             # Start production server
pnpm build:analyze     # Bundle analysis

Project Structure

├── app/                 # Application code
│   ├── routes/         # React Router routes
│   ├── components/     # React components
│   ├── modules/        # Business logic
│   └── localization/   # Internationalization
├── preset/             # Panda CSS design system
├── docs/               # Documentation
├── public/             # Static assets
└── locales/            # Translation files

Development Workflow

1. Understand the Architecture

2. Developing New Features

  1. Analyze existing components
  2. Create or modify necessary components
  3. Test with pnpm test
  4. Verify quality with pnpm check
  5. Validate types with pnpm typecheck

3. Styling with Panda CSS

// Using design tokens
import { css } from '@ocobo/styled-system/css';
import { Button } from '@ocobo/styled-system/jsx';

// Dynamic styles
const dynamicStyle = css({
  backgroundColor: 'coral.light',
  padding: 'md',
});

// Components with recipes
<Button variant="primary" size="md">Click me</Button>

4. Content Management

// Fetching content
import { fetchBlogposts } from '~/modules/content';

export const loader = createHybridLoader(async () => {
  const [status, state, data] = await fetchBlogposts();
  return { posts: data || [] };
}, 'blogPost');

Common Troubleshooting

Build Errors

# Clean and regenerate
rm -rf node_modules .react-router build
pnpm install
pnpm prepare
pnpm build

Cache Issues in Development

# Add ?refresh=1 to the URL
http://localhost:3000/blog?refresh=1

Type Errors

# Regenerate React Router types
pnpm typecheck

Useful Resources

Help and Support

  • Documentation: Check files in /docs
  • Issues: Create a ticket to report problems
  • Code Review: Follow standards defined by Biome

Happy coding! 🚀