copilot-instructions.md for Next.js
A free .github/copilot-instructions.md for Next.js + TypeScript repos: exact build and validate commands, project layout, App Router conventions and guardrails for GitHub Copilot.
- Install
.github/copilot-instructions.md- Last tested
- GitHub Copilot · 2026-10-22
GitHub Copilot reads repository-wide custom instructions from .github/copilot-instructions.md and adds them to requests made in the context of the repo. GitHub's docs say Copilot Chat lists the file under References when it was used, so you can check it's working. Copilot also supports path-specific .github/instructions/NAME.instructions.md files (with an applyTo glob) and AGENTS.md files, if you want more than one file.
This template follows the structure GitHub recommends for onboarding its cloud agent: what the repo is, how to build and validate a change in order, where things live, and rules to follow. Replace the [bracketed] values with your real versions and commands. Accurate build commands do the most to cut failed agent PRs.
The conventions section covers the Next.js mistakes assistants make most often: fetching in client components, unvalidated input, and treating params and cookies() as synchronous, when they've been async since Next.js 15. Want rules written specifically for Next.js 16? The paid pack has 12 scoped Cursor rules plus AGENTS.md and CLAUDE.md, and Copilot can read the AGENTS.md too.
copilot-instructions.md# Copilot instructions
This repository is a Next.js app. These instructions apply to every Copilot request in this repo. Keep answers and diffs small and specific to this codebase.
## Stack
- Next.js [16.x] App Router, React [19], TypeScript (strict), Tailwind CSS [4], [pnpm].
- Database / auth: [Postgres via Drizzle | Supabase | Prisma | none].
- Hosting: [Vercel | other].
- Check `package.json` for exact versions before using an API. If you're not sure an API exists in the installed version, say so instead of guessing.
## Build and validate
Always run these from the repo root, in this order, and report the result of each:
1. Install: `[pnpm install --frozen-lockfile]`
2. Typecheck: `[pnpm tsc --noEmit]`
3. Lint: `[pnpm lint]`
4. Test: `[pnpm test]`
5. Build: `[pnpm build]`
A change is not done until typecheck, lint and build pass. Never claim a check passed if you didn't run it.
## Layout
- `app/`: routes, layouts and route handlers (`app/api/**/route.ts`).
- `components/`: shared UI. Server Components by default; add `"use client"` only for state, effects or browser APIs.
- `lib/`: data access and shared logic. Files that read secrets or the database start with `import 'server-only'`.
- `[tests/]`: tests, mirroring source paths.
## Conventions
- Fetch data in Server Components or the data layer, not in client components with `useEffect`.
- Mutations use Server Actions or route handlers. Validate every input (form data, params, request bodies, webhooks, env vars) with zod at the boundary.
- In Next.js 15 and later, `params`, `searchParams`, `cookies()` and `headers()` are async. Await them.
- Use `next/image` and `next/link` instead of raw `<img>` and `<a>` for internal links.
- No `any`. Use `unknown` and narrow it.
## Guardrails
- Never commit secrets or edit `.env*` files. Reference env var names only. Only `NEXT_PUBLIC_` values may reach the browser.
- Keep diffs minimal. Don't rename, reformat or refactor unrelated code.
- Don't add a dependency without explaining why in the PR description.
- Don't delete or skip failing tests to get green. Fix the cause or say what's blocking.
- Ask before destructive operations: data deletion, migrations that drop columns, force pushes.
12 scoped Cursor rules, AGENTS.md and CLAUDE.md for Next.js 16.4 with Cache Components. This free entry is one file; the pack is the full multi-file set.
