Getting Started

Prerequisites

• Node.js 20+
• pnpm 9+
• Git

Setup

1. Clone the repository:

git clone https://github.com/lakea-project/lakea.git
cd lakea

2. Install dependencies:

pnpm install

3. Verify setup:

pnpm nx run-many -t build

Project Structure

lakea/
├── packages/              # Shared libraries
│   ├── core/             # Types, data fetchers, transforms
│   ├── design-system/    # UI components and tokens (Tailwind)
│   ├── ui/               # Visualization components
│   └── viz/              # D3 + Three.js helpers (planned)
├── apps/                 # Deployable applications
│   ├── handbook/         # This documentation site (Astro)
│   ├── portal/           # Home page (React + Vite)
│   ├── exoplanet-catalog/ # Planet explorer (React + Vite)
│   └── ...               # Future apps
└── tools/                # Build scripts, data pipelines

Common Commands

Development

# Start all apps
pnpm dev

# Or individual apps
pnpm nx dev @lakea/handbook             # localhost:4322
pnpm nx dev @lakea/portal               # localhost:4320
pnpm nx dev @lakea/exoplanet-catalog    # localhost:4321

# Run tests for a package
pnpm nx test @lakea/core

# Run all affected tests
pnpm nx affected -t test

See Deployment for production setup.

Building

# Build a specific package
pnpm nx build @lakea/core

# Build all affected projects
pnpm nx affected -t build

Linting

# Lint a specific project
pnpm nx lint @lakea/core

# Fix lint issues
pnpm nx lint @lakea/core --fix

NX Workflow

Lakea uses NX for monorepo task orchestration. Understanding these commands helps you work efficiently.

Affected Commands

Run tasks only for packages changed since main:

pnpm nx affected -t test    # Test changed packages
pnpm nx affected -t build   # Build changed packages
pnpm nx affected -t lint    # Lint changed packages

Cache

NX caches task results. If nothing changed, tasks complete instantly.

• Cache location: .nx/cache
• Clear cache: pnpm nx reset

Dependency Graph

Visualize how packages depend on each other:

pnpm nx graph

This opens a browser showing the package dependency graph.

Running Multiple Targets

Run multiple tasks in one command:

pnpm nx run-many -t build,test    # Build and test all
pnpm nx affected -t test,lint     # Test and lint affected

First Contribution

1. Pick an issue labeled good first issue
2. Create a branch: git checkout -b feat/your-feature
3. Make changes following our Git Workflow
4. Run tests and lint: pnpm nx affected -t test,lint
5. Submit a PR

Getting Help

• Check the handbook first
• Open a GitHub issue for bugs or feature requests
• Discussions for questions and ideas