AGENTS.md

Contributor Guidelines

This project uses the brand new release of the Solid 2.0 Beta.

Extra Documentation

If you cannot find the answer you're looking for inside of this document, check ./docs/**/*.md for additional documentation.

Technology Overview

• Development runtime: Node.js (v24)
• Package manager: pnpm
• Toolchain manager: Mise
• Task runner: Mise
• Bundler: Vite 8 (with Rolldown)
• JavaScript framework: Solid.js 2.0
• Formatter: Oxfmt
• Linter: Biome

Tooling Setup

This project uses Mise for all tooling. It installs the developer tools, manages command line commands, and handles parallel/dependent tasks.

Common Commands

• Dev server: mise run dev (NEVER run this yourself)
• Build: mise run build
• Format: mise run fmt
• Lint: mise run lint
• Typecheck: mise run typecheck
• Test: mise run test
• Project check: mise run check

Debugging Approach

• Use console.log with clear prefixes during development
• NEVER attempt to run the dev server yourself
• If you need to do some debugging, add some console.log statements, tell me where I need to look for the console.log statements when I run the project myself (client, server, both, somewhere else, etc.), and then I will come back and paste the results of the console.log statements for you

Node.js

• Format code with mise run fmt before committing
• Run mise run typecheck and fix all info, warnings, and errors
• Prefer unknown over any unless absolutely necessary
• Use JSDoc/TSDoc comments for public APIs
• Document important lines of code with a single line comment
• Prefer jsr:@std/* for standard library
  • JSR packages can be installed using pnpm add jsr:package-name
• Use relative imports for local modules
• Prefer import aliases over relative imports for local modules
• Validate variables using @std/assert

General Rules

Correctness

• Remove anything that isn’t used – delete unused imports, function parameters, and private class members.
• Use only real selectors – in CSS, reference valid pseudo-classes, pseudo-elements, and type selectors only.

Suspicious Code

• Skip the “any” shortcut – prefer precise TypeScript types.
• Hands off document.cookie – manipulating cookies directly is forbidden.

Performance

• Compile regexes once – declare regular expressions at module scope, not inside hot functions.

Style & Consistency

• Stick to ES modules – no require or other CommonJS patterns.
• Prefer import type – separate type-only imports.
• Arrays = T[] – use shorthand array syntax consistently.
• Don’t reassign parameters – treat function arguments as read-only.
• Favor const – use const over let for bindings unless the binding truly needs to be reassigned.
• One const per line – declare variables individually.
• Skip non-null assertions – rewrite code so ! isn’t necessary.
• Avoid enum – choose unions, objects, or literal types instead.
• Stick with trimStart/End – don’t use trimLeft/Right.
• Default parameters go last – never precede required params with optional ones.
• Self-close when empty – use <Component /> instead of <Component></Component> when there are no children.
• No unused template literals – convert to quotes if you’re not interpolating.
• Don’t write substr – use slice instead.
• Flatten simple if chains – collapse else { if … } when feasible.
• Keep member access simple – omit public, private, or protected. Use native JavaScript private properties (e.g. #property) when you need to make a property private.
• Leverage as const – assert immutability where appropriate.
• Kill useless else blocks – when the if branch returns or throws, omit the else.