78e6b9f4b5
This completes the initial monorepo setup with all packages and configuration. Packages added: - @tpmjs/ui - React component library with .ts-only components - @tpmjs/utils - Utility functions (cn, format) - @tpmjs/types - TypeScript types and Zod schemas - @tpmjs/env - Environment variable validation - @tpmjs/test - Shared Vitest configuration - @tpmjs/mocks - MSW mock server - @tpmjs/config - Shared configurations (Biome, ESLint, Tailwind, TypeScript) Applications added: - @tpmjs/web - Next.js 16 App Router Infrastructure: - Turborepo configuration with build pipeline - pnpm workspace setup - GitHub Actions CI/CD - Changesets for versioning - Lefthook pre-commit hooks - VSCode workspace settings - Comprehensive documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
181 lines
3.5 KiB
Markdown
181 lines
3.5 KiB
Markdown
# 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 >= 18
|
|
- pnpm >= 8
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Run all apps in development mode
|
|
pnpm dev
|
|
|
|
# Run specific app
|
|
pnpm --filter @tpmjs/web dev
|
|
pnpm --filter @tpmjs/storybook dev
|
|
```
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build all packages and apps
|
|
pnpm build
|
|
|
|
# Build specific package
|
|
pnpm --filter @tpmjs/ui build
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
pnpm test
|
|
|
|
# Run tests in watch mode with UI
|
|
pnpm test:ui
|
|
```
|
|
|
|
### Linting & Formatting
|
|
|
|
```bash
|
|
# Lint all packages
|
|
pnpm lint
|
|
|
|
# Format all files
|
|
pnpm format
|
|
|
|
# Check formatting
|
|
pnpm format:check
|
|
```
|
|
|
|
## Component Usage
|
|
|
|
Components are imported directly without barrel exports:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```bash
|
|
pnpm changeset
|
|
```
|
|
|
|
Follow the prompts to describe your changes and select which packages are affected.
|
|
|
|
### 2. Version Packages
|
|
|
|
When ready to release:
|
|
|
|
```bash
|
|
pnpm changeset:version
|
|
```
|
|
|
|
This updates package versions and generates CHANGELOGs.
|
|
|
|
### 3. Publish to npm
|
|
|
|
```bash
|
|
pnpm changeset:publish
|
|
```
|
|
|
|
This builds and publishes all packages with changesets to npm.
|
|
|
|
### 4. Push to GitHub
|
|
|
|
```bash
|
|
git push --follow-tags
|
|
```
|
|
|
|
## Published Packages
|
|
|
|
- `@tpmjs/ui` - React component library
|
|
- `@tpmjs/utils` - Utility functions
|
|
- `@tpmjs/types` - TypeScript types
|
|
- `@tpmjs/env` - Environment schema loader
|
|
|
|
## 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
|
|
- `clean` - Remove build artifacts
|
|
- `changeset` - Create a changeset
|
|
- `changeset:version` - Version packages
|
|
- `changeset:publish` - Publish to npm
|
|
|
|
## License
|
|
|
|
MIT
|