OdysseyUI

OdysseyUI is a pnpm + Turborepo monorepo for building and publishing an animated React component system and its documentation site.

Built on the foundation of .

Tech Stack

  • Next.js (App Router)
  • React 19 + TypeScript
  • Tailwind CSS v4
  • Turborepo
  • Fumadocs

Monorepo Structure

text
.├─ apps/│  └─ www/                  # Next.js docs site + component registry tooling├─ packages/│  ├─ ui/                   # Shared UI package│  ├─ eslint-config/        # Shared ESLint presets│  └─ typescript-config/    # Shared TypeScript presets├─ turbo.json               # Turborepo pipeline└─ pnpm-workspace.yaml      # Workspace package mapping

Prerequisites

  • Node.js 20+
  • pnpm 10+

Getting Started

bash
pnpm installpnpm dev

This starts the Turborepo dev pipeline (including the docs app in apps/www).

Common Commands

Run from the repository root:

bash
# Build all packages/apps via Turbopnpm build
# Lint all packages/apps via Turbopnpm lint
# Format all TS/TSX/MDX filespnpm format:write
# Check formattingpnpm format:check
# Build the component registry for apps/wwwpnpm registry:build

App-Level Commands

If you only want to run the web app:

bash
pnpm --filter ./apps/www devpnpm --filter ./apps/www buildpnpm --filter ./apps/www start

Registry Workflow

The docs app includes a registry build script:

  • Script: apps/www/scripts/build-registry.mts
  • Output source folders: apps/www/registry/*
  • Command: pnpm registry:build

Use this when adding or updating publishable components/demos/hooks/icons.

Linting, Formatting, and Commits

  • ESLint config is shared from packages/eslint-config
  • TypeScript config is shared from packages/typescript-config
  • Commit messages follow Conventional Commits via commitlint

Deployment Notes

  • Production build output for the docs app is generated by Next.js (apps/www/.next)
  • turbo.json defines cache-aware build, lint, and persistent dev tasks

Release Process

  1. Ensure the main branch is clean and up to date.
  2. Run quality checks:
bash
pnpm lintpnpm build
  1. Bump versions as needed (for example in root package.json and apps/www/package.json).
  2. Commit changes and create a release tag:
bash
git add .git commit -m "chore(release): vX.Y.Z"git tag vX.Y.Zgit push origin main --tags
  1. Publish/deploy using your CI/CD workflow.

Troubleshooting

  • If dependencies are out of sync, run:
bash
pnpm install --frozen-lockfile
  • If build artifacts become stale, clean and rebuild:
bash
pnpm --filter ./apps/www exec rimraf .nextpnpm build