99998e5186
- Update GitHub Actions CI workflow to use Node 22 - Add architecture and deadcode checks to CI pipeline - Create Vercel deployment guard script - Add comprehensive deployment documentation - Update README with CI badge and quality gates info - Configure vercel.json for deployment settings Vercel will now only deploy to production after all CI checks pass: - Linting & formatting - Type checking - Tests - Build verification - Architecture validation - Dead code detection See DEPLOYMENT.md for configuration instructions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
216 lines
4.4 KiB
Markdown
216 lines
4.4 KiB
Markdown
# TPMJS Monorepo
|
|
|
|
[](https://github.com/YOUR_ORG/tpmjs/actions/workflows/ci.yml)
|
|
|
|
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
|
|
|
|
```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
|
|
```
|
|
|
|
### Quality Gates
|
|
|
|
```bash
|
|
# 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](./QUALITY-GATES.md) for details.
|
|
|
|
## 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
|
|
|
|
## 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](./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
|