Marketing website for Celestia — the modular blockchain network. Built with Next.js 16 (App Router), React 19, TypeScript, and Tailwind CSS.

New here? Read ONBOARDING.md for the guided tour (routing model, where things live, the new-page recipe, and the git workflow). This README is the technical reference.

• Node.js 22 (the repo pins v22.11.0 in .nvmrc; Next 16 requires ≥ 20.9). Use a version manager so you get the right one automatically:

  nvm use      # or: fnm use   — reads .nvmrc
  # first time: nvm install 22.11.0   (or fnm install 22.11.0)

• npm (lockfile is package-lock.json — don't introduce yarn/pnpm).

git clone https://github.com/celestiaorg/celestia.org.git
cd celestia.org
nvm use                 # Node 22 from .nvmrc (or: fnm use)
npm install
cp sample.env .env.local   # then fill in values (see Environment variables)
npm run dev             # → http://localhost:3000

The git history is large (video assets). For a faster clone: git clone --depth 1 <url>.

Copy sample.env → .env.local and fill in what you need. Most pages render without any of these; they only gate specific features (newsletter, contact form, blog, analytics).

NEXT_PUBLIC_* vars are inlined into the client bundle — never put secrets behind that prefix. .env.local is gitignored; never commit real secrets.

Why --webpack? Next 16 defaults build/dev to Turbopack, which ignores the custom webpack() block in next.config.js that wires up the lumina-node WASM. The flag keeps that pipeline working.

src/
├── app/              Routes (App Router). A folder with page.tsx = a URL.
│   ├── (default)/     Route group sharing the Header/Footer chrome
│   ├── api/           Route handlers (contact, newsletter, health)
│   └── dev/           Dev-only pages (page.dev.tsx — excluded from prod builds)
├── components/        Feature components (one folder each)
├── macros/            Small reusable primitives (Buttons, Copy, Grids, SVGs)
├── data/              Page copy + SEO as typed objects   ←★ edit copy here
├── content/           Markdown (glossary, learn) with YAML front-matter
├── context/           React context providers
├── lib/ · utils/      Content processing & helpers
└── vendor.d.ts        Ambient types for untyped deps (react-slick, react-stickynode)

public/                Static assets (images, videos, fonts) served from /

• TypeScript everywhere — components/pages are .tsx, logic/data are .ts. The build is a hard type gate (next build fails on type errors).
• Routing: folders under src/app/ with a page.tsx are URLs. (group) folders don't appear in the URL; [slug] is dynamic; _private folders aren't routed. URLs end in a trailing slash (/about/) — include it on internal links.
• Imports: use the @/* alias → src/* (e.g. @/components/Meta/Meta).
• Styling: Tailwind utilities first; design tokens live in tailwind.config.js; reach for SCSS only for complex animations. New work uses the font-nuberNext* / font-robotoMono families.
• Copy lives in src/data/<page>/, not inside components.
• Dev-only pages: name a file page.dev.tsx — it's a route in next dev but excluded from production builds. Example: visit /dev locally for a live site map of all routes.

A Husky pre-push hook runs lint + typecheck + build before every push. The build runs in an isolated .next-verify dir (cleaned up on exit) so it never clobbers a running next dev. Fix failures rather than bypassing with --no-verify.

Self-hosted via Docker (not Vercel). On push to main, GitHub Actions (.github/workflows/docker-build-publish.yml):

1. builds the image (node:22-alpine → npm install → npm run build),
2. pushes it to ghcr.io/celestiaorg/celestia.org:latest,
3. purges the Cloudflare cache.

The build contract is simply: npm install → npm run build → next start. Verify deploy-affecting changes locally with docker build .. A second workflow (link-checker.yml) crawls links on PRs.

• ONBOARDING.md — contributor guide: routing model, where things live, the new-page recipe, styling, and the git workflow (branching, Conventional Commits).
• AGENTS.md — rules for AI coding agents (Claude Code, Cursor, Codex).
• FONT-LICENSE.md — font licensing (NuberNext is per-domain licensed).
• CLAUDE.md — architecture notes for AI coding assistants.

Branch from main (feature/…, fix/…, chore/…), write Conventional Commits, and open a PR into main. Make sure npm run verify passes. Full details in ONBOARDING.md.

Who reviews your PR depends on what it changes. .github/CODEOWNERS auto-requests the right people:

• DevOps (Cris, @pippokr) reviews infrastructure, tooling, and dependency changes.
• Marketing (Damilico, @damilico, or Sandy) reviews content changes.