Monorepo copilot-instructions.md Template

Description

## copilot-instructions.md for Monorepo Projects

This is a Turborepo monorepo. Follow these conventions for all packages:

### Structure
```
/
├── apps/
│   ├── web/          # Next.js frontend
│   ├── api/          # Node.js/Express API
│   └── mobile/       # React Native app
├── packages/
│   ├── ui/           # Shared UI components
│   ├── config/       # Shared ESLint, TypeScript, Tailwind configs
│   ├── types/        # Shared TypeScript types and interfaces
│   └── utils/        # Shared utility functions
└── turbo.json
```

### Package Management
- pnpm workspaces for dependency management
- Shared dependencies hoisted to root `node_modules`
- Package-specific deps in individual `package.json` files
- Internal packages referenced via workspace protocol: `"@repo/ui": "workspace:*"`
- Never install the same external dependency at different versions across packages

### Shared Packages
- `@repo/ui`: Reusable React components with Tailwind styling
- `@repo/types`: TypeScript interfaces shared between frontend and backend
- `@repo/utils`: Pure utility functions with no framework dependencies
- `@repo/config`: Shared ESLint, TypeScript, and Prettier configurations
- Export from package `index.ts` barrel files only

### Build & Task Pipeline
- `turbo.json` defines task dependencies and caching
- `build` depends on `^build` (build dependencies first)
- `test` and `lint` run in parallel across all packages
- Use `--filter` for targeted builds: `turbo build --filter=@repo/web`
- Remote caching enabled for CI: Vercel Remote Cache or custom

### Code Conventions (Cross-Package)
- TypeScript strict mode in all packages
- Shared ESLint config extended in each package
- Consistent import aliases: `@/` for app-local, `@repo/` for shared
- All shared types defined in `@repo/types`, never duplicated
- API response types used by both backend and frontend from shared package

### Testing
- Each package has its own test configuration and scripts
- Shared test utilities in `packages/test-utils/`
- Integration tests in `apps/` test the full stack
- Run all tests: `turbo test`; run single package: `turbo test --filter=@repo/api`

### CI/CD
- Turborepo detects changed packages and runs only affected tasks
- Deploy apps independently based on change detection
- Shared package changes trigger downstream app rebuilds
- Cache turbo outputs in CI for faster subsequent runs

### Environment Variables
- Root `.env.example` documents all required variables
- App-specific `.env.local` files are gitignored
- Use `@t3-oss/env-nextjs` or similar for typed env validation
- Shared env schema in `packages/config/env.ts`

Free to copy and use. Compatible with GitHub Copilot, GPT-5.

Usage Instructions

Tags

Compatible AI Models

Version History

Related Prompts