monorepo: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

🚀 Commands

# Build/Test
pnpm build
pnpm test
pnpm tdd                    # Watch mode
pnpm test:only              # Run marked tests (it.only)
pnpm test:coverage

# Workflow
pnpm new                    # Create package
pnpm watch                  # Dev mode
pnpm build:docs
pnpm release               # Changesets

# Individual tests (from tests/)
pnpm test filepart         # Run test whose filename contains "filepart"
pnpm tdd                   # Watch specific tests

📦 Release Cycle

We use Changesets, publishing straight from master.

Publishing is triggered by a package version change on master — merging the "Version Packages" PR is the signal. No separate release branch.

Quick Reference

```bash
# 1. Create changeset for your changes
pnpm changeset

# 2. Commit and push to master
git add . && git commit -m "feat: description" && git push

# 3. CI creates "Version Packages" PR - review and merge to master

# 4. Merging the PR bumps versions on master, which triggers CI to
#    automatically: Publish → Update docs
```

Detailed Flow

1. Create Changeset: pnpm changeset - describes changes and version bump
2. Push to Master: CI runs tests and creates "Version Packages" PR
3. Review PR: Verify versions and changelogs are correct
4. Merge PR: version bump on master triggers the publish workflow
5. Automated CI: publishes to npm, updates documentation

See CONTRIBUTING.md for complete release documentation.

🏗️ Architecture

Structure: pnpm monorepo, packages build independently, test together

Repository Structure Overview

monorepo/
├── packages/                    # 9 @logosdx packages in layered architecture
│   ├── utils/                  # Foundation layer (all packages depend on this)
│   ├── dom/                    # Browser utilities (depends on utils)
│   ├── fetch/                  # HTTP client (depends on utils)
│   ├── observer/               # Event system (depends on utils)
│   ├── localize/               # i18n system (depends on utils)
│   ├── state-machine/          # State management (depends on utils)
│   ├── storage/                # Persistence layer (depends on utils)
│   └── react/                  # React bindings (optional peer deps on above)
│
├── tests/                       # Comprehensive test suite
│   ├── src/                    # Test files mirroring package structure
│   ├── benchmark/              # Performance tests (250k ops, memory monitoring)
│   └── package.json            # Test dependencies (vitest, sinon, jsdom, fast-check)
│
├── docs/                       # VitePress documentation + TypeDoc integration
│   ├── packages/               # Individual package documentation
│   ├── public/images/          # Brand assets and static files
│   └── *.md                    # Getting started, philosophy, cheat sheets
│
├── skills/logosdx/             # Claude Code skill with package reference guides
│   ├── SKILL.md               # Skill definition and routing
│   └── references/            # Per-package API reference files
├── scripts/                    # Build, documentation, and workflow scripts
├── internals/                  # Internal utilities and templates
├── typedoc/                    # Generated API documentation
└── CLAUDE.md                   # This file - development guidance