antfu

Reference template: antfu/starter-ts. When scaffolding a new TypeScript project, mirror its package.json scripts, eslint.config.js, knip.json, tsdown.config.ts and workflows rather than inventing a new layout.

Coding Practices

Code Organization

• Single responsibility: Each source file should have a clear, focused scope/purpose
• Split large files: Break files when they become large or handle too many concerns
• Type separation: Always separate types and interfaces into types.ts or types/*.ts
• Constants extraction: Move constants to a dedicated constants.ts file

Runtime Environment

• Prefer isomorphic code: Write runtime-agnostic code that works in Node, browser, and workers whenever possible
• Clear runtime indicators: When code is environment-specific, add a comment at the top of the file:

// @env node
// @env browser

TypeScript

• Explicit return types: Declare return types explicitly when possible
• Avoid complex inline types: Extract complex types into dedicated type or interface declarations

Explicitness

Favor explicit, traceable code over implicit "magic". A reader (human or agent) should be able to follow where every name comes from without running tooling.

• Explicit imports: Prefer explicit import statements. Avoid auto-imports — when a framework provides them (e.g. Nuxt/Nitro), turn them off for new projects (see app-development).
• No path aliases by default: Use relative imports (./foo, ../bar). Only use path aliases (@/, ~/, #imports, etc.) when they are already configured in the project; don't introduce new ones for greenfield code.

Comments

• Avoid unnecessary comments: Code should be self-explanatory
• Explain "why" not "how": Comments should describe the reasoning or intent, not what the code does

Testing (Vitest)

• Test files: foo.ts → foo.test.ts (same directory)
• Use describe/it API (not test)
• Use toMatchSnapshot for complex outputs
• Use toMatchFileSnapshot with explicit path for language-specific snapshots

---

Tooling Choices

@antfu/ni Commands