Packages

The packages/ directory contains shared workspace packages. Some are private workspace-only packages (@workspace/*), others are published to npm under the @celestia-project org.

@celestia-project/ui

A shadcn-style React component library built on Base UI and Tailwind CSS v4, with 150+ components.

Exports:

Usage:

import { Button } from "@celestia-project/ui"import { Button } from "@celestia-project/ui/primitive/button"import { cn } from "@celestia-project/ui/lib/utils"

Key dependencies: @base-ui/react, class-variance-authority, tailwind-merge, next-themes, @phosphor-icons/react

Using it outside this monorepo

The package is published to npm and can be installed in any React 19 + Tailwind CSS v4 project:

pnpm add @celestia-project/ui

Integration Option A: Quickstart (All-in-one)

Import the global stylesheet in your app entry point (app/layout.tsx or globals.css):

import "@celestia-project/ui/globals.css";

Integration Option B: Existing Tailwind v4 App (@source directive)

If your app already has an existing Tailwind v4 setup and custom theme variables, add the @source directive in your main CSS file so Tailwind scans the package without double-importing or overriding styles:

@import "tailwindcss";@source "../../node_modules/@celestia-project/ui";@source "../**";
@custom-variant dark (&:is(.dark *));

See the Components docs and the npm package for details.

@celestia-project/mobile

Native iOS and Android UI components built on @expo/ui — real SwiftUI on iOS and Jetpack Compose on Android, with no web-shim layer in between. The package reuses the same primitive / composite / layout taxonomy and the same design tokens as @celestia-project/ui, but it is not a port: mobile-only affordances (haptics, safe areas) have no web counterpart. For slide-up panels, use MobileBottomSheet on native and BottomSheet on web.

Exports:

Usage:

import { MobileButton, MobileScreen } from "@celestia-project/mobile"import { MobileButton } from "@celestia-project/mobile/primitive/button"import { useMobileTheme } from "@celestia-project/mobile/tokens"

Key dependencies: @expo/ui, expo-haptics, react-native-safe-area-context

The package is consumed from source — its exports map points straight at .ts / .tsx, so there is no build step and no dist/. The consuming app's bundler (Metro, via Expo) compiles it. Every colour comes from useMobileTheme(); nothing is hardcoded, which is what lets MobileHost switch themes at runtime.

See the Mobile (Expo) docs for setup, the full component inventory, and the design rules.

@celestia-project/create

The interactive CLI that scaffolds a new Celestia Starter project. Lives in packages/cli.

Usage:

npx @celestia-project/create my-appnpx @celestia-project/create my-app --template web --features auth,dashboardnpx @celestia-project/create my-desktop --template desktop

Bin registered: create-celestia

Publishing:

# From the monorepo root — publishes both @celestia-project/ui and @celestia-project/createpnpm publish:packages
# Dry run first (previews tarball contents without uploading)pnpm publish:dry-run

See the CLI docs for the full feature flag reference and local testing guide.

@workspace/eslint-config

Shared ESLint flat-config presets for consistent linting across the monorepo.

Exports:

Usage in a consumer eslint.config.js:

import { config } from "@workspace/eslint-config/next-js"
export default config

@workspace/typescript-config

Reusable tsconfig profiles that all workspace projects extend.

Usage in a consumer tsconfig.json:

{  "extends": "@workspace/typescript-config/nextjs.json"}

@workspace/feature-manager

A CLI and runtime registry that discovers, installs, and tracks features defined by feature.json manifests under the project's packages/feature-manager/features/ directory.

CLI commands (via root scripts):

pnpm add-feature <name>       # Install (or --force reinstall/upgrade) a featurepnpm remove-feature <name>    # Uninstall a feature, restoring shared filespnpm list-features            # List available and installed featurespnpm verify-features [name]   # Check installed features for drift or breakagepnpm prompt-feature <name>    # Generate the AI verification prompt

Common flags: --dry-run (plan only, writes nothing), --force (reinstall/upgrade, or override removal safety checks), --strict (treat warnings as errors), --json (machine-readable report), --quiet.

How add works:

1. Reads packages/feature-manager/features/<name>/feature.json (legacy v1 manifests using files are normalized)
2. Validates it — malformed fields and paths that escape the repository are rejected before anything is written
3. Verifies requires against the tracker (root features.json)
4. Plans every action, then snapshots each path it will touch
5. Copies copies entries into the workspace — apps/api, apps/web, packages/*, root files
6. Inserts insertions snippets into managed marker regions
7. Applies jsonAppends to JSON arrays (e.g. the docs sidebar meta.json)
8. Merges dependencies / devDependencies into each target package's package.json, reporting any version conflict instead of silently replacing it
9. Records the feature, its files (with content hashes), backups and dependency changes in the tracker, then prints next steps (pnpm install, env vars, postInstall commands)

If any step fails, every touched path is rolled back — a failed install can never leave a half-applied repository behind.

Shared files: when two features provide the same path (for example the CMS media dialog, provided by cms, media-r2 and unsplash), the newest install wins and the previous content is backed up under .feature-manager/backups/. Removing a feature restores the previous owner's version rather than deleting the file. Files you edited after installing are kept unless --force is given.

Feature manifest schema (feature.json):

{  "name": "blog",  "version": "1.0.0",  "description": "Full CRUD blog over the typed RPC client",  "requires": ["auth", "dashboard"],  "copies": [    { "from": "api/src/features/blog/routes.ts", "to": "apps/api/src/features/blog/routes.ts" }  ],  "insertions": [    { "file": "apps/api/src/app.ts", "marker": "routes", "snippet": "snippets/api-routes.ts" }  ],  "jsonAppends": [    { "file": "apps/web/content/docs/meta.json", "path": "pages", "value": "blog" }  ],  "dependencies": { "apps/api": { "drizzle-orm": "^0.45.2" } },  "env": { "apps/api": ["DATABASE_URL=postgresql://postgres:postgres@localhost:5432/celestia"] },  "postInstall": ["pnpm --filter @workspace/db db:push"],  "notes": "Optional post-install instructions"}

Managed marker regions

Insertions target empty sentinel regions that already exist in shared files. Installing wraps the snippet in a per-feature block so it can later be replaced (idempotent reinstall) or removed cleanly:

// feature-manager:<marker>:begin// feature-manager:<marker>:<feature>:begin...snippet...// feature-manager:<marker>:<feature>:end// feature-manager:<marker>:end

Available regions:

Marker ids are scoped per file, so imports in app.ts and imports in sidebar.tsx don't collide. Comment syntax follows the file type (// for TS/TSX, <!-- --> for .md, {/* */} for .mdx). Files that cannot carry comments (e.g. meta.json) use jsonAppends instead.

Authoring snippets:

• Snippets are inserted verbatim — include their leading indentation in the snippet file itself (only the sentinel comments are auto-indented)
• A single trailing newline is stripped before insertion

Programmatic exports:

All of these take an explicit repo root, so they can be driven from scripts and tests rather than only from the CLI.