tpmjs/README.md

TPMJS Monorepo

Tool Package Manager for AI Agents - A Turborepo monorepo with strict TypeScript, Next.js 16, and best practices.

Structure

apps/
  web/          - Next.js 16 App Router application
packages/
  config/       - Shared configurations (Biome, ESLint, Tailwind, TypeScript)
  ui/           - React component library (.ts-only, no barrels)
  utils/        - Utility functions
  types/        - Shared TypeScript types
  env/          - Zod environment schema loader
  test/         - Vitest shared configuration
  mocks/        - MSW mock server
  storybook/    - Storybook documentation

Getting Started

Prerequisites

• Node.js >= 22 (LTS)
• pnpm >= 8
• nvm (recommended for Node version management)

Installation

pnpm install

Development

# Run all apps in development mode
pnpm dev

# Run specific app
pnpm --filter @tpmjs/web dev
pnpm --filter @tpmjs/storybook dev

Building

# Build all packages and apps
pnpm build

# Build specific package
pnpm --filter @tpmjs/ui build

Testing

# Run all tests
pnpm test

# Run tests in watch mode with UI
pnpm test:ui

Linting & Formatting

# Lint all packages
pnpm lint

# Format all files
pnpm format

# Check formatting
pnpm format:check

Quality Gates

# Check architecture/dependency rules
pnpm check-architecture

# Find unused code and dependencies
pnpm find-deadcode

# Check type coverage
pnpm type-coverage

See QUALITY-GATES.md for details.

Component Usage

Components are imported directly without barrel exports:

import { Button } from '@tpmjs/ui/Button/Button';
import { Card, CardHeader } from '@tpmjs/ui/Card/Card';

Important: All UI components use .ts extension (not .tsx) and use createElement instead of JSX.

Publishing Workflow

1. Create Changesets

After making changes to publishable packages:

pnpm changeset

Follow the prompts to describe your changes and select which packages are affected.

2. Version Packages

When ready to release:

pnpm changeset:version

This updates package versions and generates CHANGELOGs.

3. Publish to npm

pnpm changeset:publish

This builds and publishes all packages with changesets to npm.

4. Push to GitHub

git push --follow-tags

Published Packages

• @tpmjs/ui - React component library
• @tpmjs/utils - Utility functions
• @tpmjs/types - TypeScript types
• @tpmjs/env - Environment schema loader

Deployment

The project is configured to only deploy to Vercel when all CI checks pass. This ensures production always has high-quality, tested code.

CI Checks:

• Linting & formatting
• Type checking
• Tests
• Production build
• Architecture validation
• Dead code detection

See DEPLOYMENT.md for full configuration details.

Module Boundaries

ESLint enforces module boundaries:

• Apps can import from published packages only
• Packages cannot import from apps
• No barrel exports (index.ts) allowed
• Direct imports required: @tpmjs/ui/Button/Button

Architecture Decisions

Why .ts-only Components?

Using .ts instead of .tsx for React components:

• Enforces explicit createElement calls
• Makes React's runtime nature more visible
• Prevents JSX spreading anti-patterns
• Better for code generation and tooling

Why No Barrel Exports?

• Clearer dependency graphs
• Better tree-shaking
• Explicit imports show what's actually used
• Prevents circular dependencies

Why Biome + ESLint?

• Biome: Fast formatting and basic linting
• ESLint: Semantic rules (module boundaries, TypeScript strictness)
• Each tool focuses on what it does best

Scripts Reference

• dev - Start development servers
• build - Build all packages
• test - Run tests
• test:ui - Run tests with UI
• lint - Lint code
• format - Format code with Biome
• format:check - Check formatting
• type-check - TypeScript type checking
• type-coverage - Check type coverage (no implicit any)
• check-architecture - Validate dependency rules
• find-deadcode - Find unused code/dependencies
• clean - Remove build artifacts
• changeset - Create a changeset
• changeset:version - Version packages
• changeset:publish - Publish to npm

License

MIT