Project Structure

Project Structure

Monorepo layout and package organization for modern-cmdk.

---

Top-Level Layout

modern-cmdk/
  packages/
    command/                  # Core engine (pure TypeScript)
    command-react/            # React 19 adapter
    command-search-wasm/      # WASM fuzzy search (Rust)
    command-codemod/          # Migration codemods
  apps/
    docs/                     # VitePress documentation site
    playground/               # Interactive React demo
  benchmarks/                 # Vitest benchmarks
  tests/
    unit/                     # Unit + stress tests
    e2e/                      # Playwright E2E tests
  biome.json                  # Biome linter/formatter config
  pnpm-workspace.yaml         # pnpm workspace definition
  tsconfig.base.json          # Shared TypeScript config
  vitest.config.ts            # Test configuration
  playwright.config.ts        # E2E test configuration

---

packages/command/ — Core Engine

The framework-agnostic state machine. Zero DOM dependencies. Pure TypeScript.

packages/command/
  src/
    machine.ts                # State machine implementation
    types.ts                  # CommandState, CommandEvent, CommandItem, branded IDs
    search/
      index.ts                # Search engine factory + interface
      default-scorer.ts       # TypeScript fuzzy scorer
    frecency/
      engine.ts               # FrecencyEngine class
      storage.ts              # MemoryFrecencyStorage, IdbFrecencyStorage
      compute.ts              # computeFrecencyBonus pure function
    keyboard/
      registry.ts             # Shortcut registry
      parser.ts               # RegExp.escape-based key parser
    utils/
      event-emitter.ts        # WeakRef-based event emitter
      scheduler.ts            # isInputPending() + scheduler.yield()
    index.ts                  # Public API barrel export
  tsconfig.json
  tsdown.config.ts            # Build config (ESM, ES2026, isolatedDeclarations)
  package.json

Key exports: createCommandMachine, createSearchEngine, FrecencyEngine, MemoryFrecencyStorage, IdbFrecencyStorage, computeFrecencyBonus, createKeyboardShortcutRegistry, itemId, groupId

---

packages/command-react/ — React Adapter

Compound component API that bridges the core engine to React 19.

packages/command-react/
  src/
    command.tsx               # <Command> root component
    input.tsx                 # <Command.Input> combobox
    list.tsx                  # <Command.List> listbox + virtualizer
    item.tsx                  # <Command.Item> option
    group.tsx                 # <Command.Group>
    separator.tsx             # <Command.Separator>
    empty.tsx                 # <Command.Empty>
    loading.tsx               # <Command.Loading>
    shortcut.tsx              # <Command.Shortcut>
    badge.tsx                 # <Command.Badge>
    dialog.tsx                # <Command.Dialog> (Radix UI)
    page.tsx                  # <Command.Page>
    hooks.ts                  # useCommandState, useCommandMachine
    context.ts                # React context for machine
    virtualizer.ts            # Tanstack-inspired virtual scroll
    styles.css                # GPU-composited animations, OKLCH tokens
    index.ts                  # Public API barrel export
  tsconfig.json
  tsdown.config.ts
  package.json

Key exports: Command (with all sub-components as properties), useCommandState, useCommandMachine

---

packages/command-search-wasm/ — WASM Search

Rust trigram index compiled to WebAssembly.

packages/command-search-wasm/
  crate/
    src/
      lib.rs                  # Rust trigram search implementation
      trigram.rs               # Trigram index builder
    Cargo.toml
  src/
    index.ts                  # Main thread WASM engine
    worker.ts                 # Web Worker engine
    worker-script.ts          # Worker script (runs in worker context)
    types.ts                  # Message protocol types
  wasm/                       # Built WASM output (wasm-pack)
  tsconfig.json
  tsdown.config.ts
  package.json

Key exports: createWasmSearchEngine, createWorkerWasmSearchEngine

---

packages/command-codemod/ — Migration Codemods

jscodeshift transforms for migrating from cmdk.

packages/command-codemod/
  src/
    cli.ts                    # CLI entry point
    transforms/
      import-rewrite.ts       # cmdk -> modern-cmdk/react
      data-attrs.ts           # [cmdk-*] -> [data-command-*]
      forward-ref.ts          # Remove forwardRef wrappers
      should-filter.ts        # shouldFilter -> filter
  tsconfig.json
  tsdown.config.ts
  package.json

---

apps/docs/ — Documentation

VitePress 2.0.0-alpha.16 site with Twoslash code examples.

apps/docs/
  .vitepress/
    config.ts                 # VitePress config (Twoslash, SEO, sidebar)
  guide/
    getting-started.md
    installation.md
    basic-usage.md
    async-items.md
    virtualization.md
    wasm-search.md
    frecency.md
    shortcuts.md
    theming.md
    accessibility.md
    migration-from-cmdk.md
  api/
    command.md
    command-react.md
    command-search-wasm.md
  examples/
    basic.md
    dialog.md
    async-search.md
    virtualized.md
    frecency.md
    shortcuts.md
    theming.md
  architecture/
    overview.md               # Three-layer architecture + Mermaid diagrams
  index.md                    # Landing page
  package.json

---

apps/playground/ — Interactive Demo

React 19 app showcasing all features.

apps/playground/
  src/
    App.tsx                   # Router (pathname-based)
    main.tsx                  # Entry point
    styles.css                # OKLCH theme, forced-colors, reduced-motion
    demos/
      BasicDemo.tsx           # 15 items, 3 groups, shortcuts
      DialogDemo.tsx          # Ctrl+K trigger, dialog mode
      VirtualizedDemo.tsx     # 10K items with estimateSize/overscan
  index.html
  vite.config.ts
  package.json

---

Shared Configuration

File	Purpose
tsconfig.base.json	Shared TS config: ES2026, strictest settings
biome.json	Biome 2.4.6 linting + formatting rules
vitest.config.ts	Vitest with happy-dom, workspace paths
playwright.config.ts	Playwright E2E, Chromium-only
pnpm-workspace.yaml	packages/* + apps/* globs

---

Dependency Graph

modern-cmdk (core)
  <- modern-cmdk/react (depends on core)
  <- modern-cmdk-search-wasm (implements SearchEngine)
  <- modern-cmdk (standalone, no runtime deps)

apps/docs (depends on nothing at runtime)
apps/playground (depends on command + command-react)

The core package has zero runtime dependencies. The React adapter depends only on the core + React + Radix UI.