Cursor rules (MDC) file for Turborepo

[dvzrd]

Goals

1. Example that outlines best practices and community standards
2. Provides core architecture context and common config patterns
3. Automate setup of turbo tasks and scripts based on project dependencies and rules

Non-goals

1. A universal solution for every turborepo usecase

Background

Cursor rules provide context about your specific project for AI to better assist devs: https://docs.cursor.com/context/rules
I couldn't find a turborepo rule yet and was hoping the community can help develop one based on their experiences.

Proposal

An example turborepo.mdc file or an example repo with a turborepo cursor rule, outlining key factors from the docs. This file can be be used as a starting point to fit your specific project's needs (i.e. adding additional workspaces or adding context for templates used to generate boilerplate code).

Here's an example to get started. Please let me know how you think this can be improved to just the basic rules that should always be followed (i.e. leaving globalEnv array empty and handling environments for each app separately).

# Turborepo Configuration & Best Practices

## Project Structure
- Maintain a clear separation between apps and packages
- Keep shared configurations in the root configs/ directory
- Use consistent naming conventions for workspaces
- Follow the standard Turborepo workspaces directory structure:
  `apps/              # Application workspaces`
  `packages/      # Shared package workspaces`

## Turborepo Configuration

### Root turbo.json
- Define clear pipeline tasks with proper dependencies
- Use proper caching strategies for each task
- Keep globalEnv empty to prevent environment variable leaks
- Use proper task dependencies to optimize build times
- Define proper outputs for caching

### App turbo.json
- Extend root configuration for apps when needed
- Keep workspace-specific configurations minimal
- Use proper task overrides
- Follow consistent naming conventions

## Package Management
- Use pnpm as the package manager
- Maintain consistent versions across workspaces
- Use `workspace:* | repo:*` protocol for internal dependencies
- Keep package.json files minimal
- Use proper peer dependencies

## Workspace Generation
- Use `@turbo/gen` for creating new apps and packages
- Follow consistent template structure
- Use proper naming conventions
- Include necessary configuration files
- Set up proper dependencies

## Development Workflow
- Use turbo run for executing commands
- Implement proper task dependencies
- Use proper caching for faster builds
- Follow consistent naming conventions for scripts
- Use proper workspace filtering

## Build & Deployment
- Use proper caching for CI/CD
- Implement proper artifact handling
- Use proper environment variable management
- Follow consistent deployment patterns
- Use proper workspace filtering

## Performance Optimization
- Implement proper task dependencies
- Use proper caching strategies
- Optimize build times
- Use proper parallel execution
- Use proper workspace filtering

## Environment Variables
- Keep globalEnv empty in turbo.json
- Use proper workspace-specific environment variables
- Follow proper naming conventions
- Implement proper validation
- Use proper documentation

## Caching Best Practices
- Define proper outputs for each task
- Use proper cache keys
- Implement proper cache invalidation
- Use proper cache dependencies
- Follow proper cache naming conventions

## Task Dependencies
- Define clear task dependencies
- Use proper task ordering
- Implement proper task filtering
- Use proper task caching
- Follow proper task naming conventions

## Workspace Dependencies
- Use proper workspace references
- Implement proper versioning
- Use proper peer dependencies
- Follow proper dependency naming conventions
- Use proper dependency filtering

## CI/CD Integration
- Use proper caching in CI/CD
- Implement proper artifact handling
- Use proper environment variable management
- Follow proper deployment patterns
- Use proper workspace filtering

## Best Practices
- Keep workspace dependencies up to date
- Use proper versioning strategy
- Implement proper error handling
- Follow consistent naming conventions
- Use proper documentation
- Implement proper testing strategy
- Use proper logging
- Follow proper security practices

I set the rule type for this to Always

Formatting was an issue here so I removed some code blocks, but more context should be provided using code blocks (i.e. project workspace structure, commands, templates, etc).

I think this can be narrowed down to just the essential rules, anyone have ideas on how to better organize these sections?

---

Found a turbopack rules file which can serve as an example to help develop the turborepo rules: https://github.com/sanjeed5/awesome-cursor-rules-mdc/blob/main/rules-mdc/turbopack.mdc