LLMs

What are Copilot Instructions?

Copilot instructions are configuration files that provide context and coding guidelines to AI assistants like GitHub Copilot, Claude, and other AI coding tools. They help ensure generated code follows your project's specific patterns, conventions, and constraints.

Next-Cloudflare-Turbo includes comprehensive instruction files that teach AI assistants about the unique aspects of developing with Cloudflare Workers, the monorepo structure, and project-specific patterns.

File Structure

The instruction files are organised to provide both global and path-specific guidance:

.github/
├── copilot-instructions.md          # Global instructions for entire repository
└── instructions/
    ├── app.instructions.md          # Next.js app patterns (apps/app/**)
    ├── data.instructions.md         # Data layer patterns (apps/app/src/data/**)
    ├── database.instructions.md     # Database package patterns (packages/db/**)
    └── formatting.instructions.md   # Code quality rules (**/*.{ts,tsx,js,jsx})

Global Instructions

The main copilot-instructions.md file provides repository-wide context including:

• Architecture overview - Cloudflare Workers runtime environment and constraints
• Universal constraints - No Node.js APIs, Web Standards usage, edge runtime considerations
• Import patterns - Correct ways to import from database packages and utilities
• Database connection patterns - When to use getDb() vs getDbAsync()
• Universal rules - British English, TypeScript strict mode, error handling patterns

Path-Specific Instructions

Each instruction file uses the applyTo frontmatter to target specific parts of the codebase:

App Instructions (apps/app/**)

• Next.js App Router patterns optimised for Cloudflare Workers
• Server Component vs Client Component usage
• Form handling with Server Actions
• Error handling and navigation patterns

Data Instructions (apps/app/src/data/**)

• Query vs Action separation patterns
• Connection factory usage (getDb vs getDbAsync)
• Proper use of "use server" directive
• Caching strategies with React's cache()

Database Instructions (packages/db/**)

• Drizzle ORM schema definitions
• Migration workflow and best practices
• Type export patterns
• Package structure conventions

Formatting Instructions (All TypeScript/JavaScript files)

This is a pre-configured Ultracite preset. For more information see Ultracite | Editor Rules

Customising Instructions

You can modify these files to match your specific requirements. The instructions were generated for this project by using Claude. Claude was given the full code of each specific pattern/repository, as well as the documentation.

Creating New Path-Specific Instructions

For new packages or applications:

---
applyTo: "packages/your-package/**"
---

# Your Package Instructions

## Purpose
Brief description of what this package does.

## Patterns
Specific coding patterns for this package.

Best Practices

Writing Effective Instructions

Be specific about constraints:

# Don't be vague
- Use TypeScript

# Be specific about project requirements
- Use TypeScript strict mode (no any types)
- Import types from @nct/db package exclusively
- Use Web APIs instead of Node.js built-ins

Provide context for Cloudflare Workers:

# Always explain why certain patterns exist
- Use getDb() for live user requests (Server Actions, dynamic Server Components)
- Use getDbAsync() for build-time operations (ISR, SSG, static queries)

Include both DO and DON'T examples:

## DO
- Use "use server" directive for all data access functions
- Handle errors gracefully with try/catch blocks

## DON'T
- Use Node.js built-ins (not available in Cloudflare Workers)
- Skip error handling in data operations

Maintaining Instructions

As your project evolves:

• Update patterns when you establish new conventions
• Remove outdated guidance that no longer applies
• Test with AI assistants to ensure instructions produce expected results
• Keep examples current with your actual codebase

FAQ