Skip to content

Latest commit

 

History

History
78 lines (59 loc) · 3.94 KB

AGENTS.md

File metadata and controls

78 lines (59 loc) · 3.94 KB

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

Code style guidelines

  • Replace em-dashes (—) with en-dashes (–) in text or comments
    • Use em-dashes only as an explicit empty placeholder value
  • Replace en-dashes (–) with hyphens (-) in numerical or temporal ranges

JS

  • Use tabs for indentation
  • Prefer double quotes over single quotes for strings
  • Prefer string interpolation over concatenation
  • Omit semicolons for separating statements
    • If required, for example where a statement starts with a parenthesis, see if it can be split up with a constant declaration
    • If a IIFE is needed, use void instead of a semicolon
  • Blocks or conditionals with 1 statement should omit braces
    • This includes nested blocks, like if (x) for (const y of z) ...
  • Arrow functions with only a single return expression should omit braces and the return keyword
  • Function declarations should use arrow functions if they have only a single return expression, and standard function declarations otherwise, except if they're UI components
    • This also applies for top-level functions
    • Use const to declare arrow function variables
    • UI components should always be standard function declarations, even when they only return JSX
  • Use guard statements to reduce nesting everywhere possible
    • Do this in functions with return, and in loops with continue
  • Prefer for (const x of y) ... over y.forEach(x => ...)
  • Prefer const over let
    • Avoid var
  • Use === and !== over == and !=
  • Use Object.freeze() to make objects immutable where possible
  • Use void before function calls that return promises to be discarded, or before IIFEs rather than semicolons
  • Declare only 1 variable per declaration statement, avoid const x = 1, y = 2, z = 3
  • When making large functions that return objects with many functions, consider if this would be more natural as a class with methods instead

None of this should conflict with the formatting or linting rules of Biome or oxlint.

TS

  • Use return types on functions
  • Avoid any types
  • Prefer union types over enums
  • Prefer interface over type for object types
  • Always use object types with indexers over Record types, for example prefer { [_: string]: string } over Record<string, string>

CSS

  • Avoid !important where possible
    • Avoid the equivalent ! suffix in Tailwind classes
  • Avoid margins where possible
    • Replace with padding or gaps where spacing is needed
    • Replace with flex or grid for centreing
    • If needing negative margins for funky tricks, OK
  • Use canonical Tailwind classes like w-36 instead of w-[9rem]
  • In the rare case where something is more concise in standard CSS than in Tailwind, write it in standard CSS

Markdown

  • Single * for italics, double ** for bold
  • Use # for headings, not = or - underlines
  • Use fenced code blocks with language identifiers instead of indented code blocks
  • Do not hard-wrap. Never split a sentence or a paragraph over multiple lines

Comments

  • Do not hard-wrap. Never split a sentence over multiple lines
    • If the new line is after a semicolon or is a new sentence, OK

Product copy

  • Parts money is only for parts. Never write, or imply, that unspent grant-card money becomes coins: a card's leftover balance goes back to Half Life when it is closed, and coins come only from approved hours past a tier's funded block.