Can you provide some tips on incrementally adopting JSDoc/TSDoc in my Next.js project?
- User
Can you provide some tips on incrementally adopting JSDoc/TSDoc in my Next.js project?
- Assistant
Gradually Introducing JSDoc / TSDoc to a Next.js Code-base 🚶♂️➡️🏃♀️
The key is zero-friction wins first, mandatory gates last. Below is a battle-tested, “turn one dial at a time” approach that keeps velocity high while making your types & docs richer every sprint.
1. Flip on Type Checking Without Converting to TypeScript
- Add a minimal jsconfig.json (or piggy-back on your existing tsconfig):
{ "compilerOptions": { "checkJs": true, // <-- tells tsc to look at .js files too "baseUrl": ".", // Next.js already respects this "paths": { "@/*": ["src/*"] } }, "exclude": ["node_modules"] } - In each JS file you want checked, drop the pragma:
➡️ You instantly get type-checking in VS Code/tsc without converting to// @ts-check.ts(x).
2. Start Writing “High-Value” JSDoc Blocks Only
Focus on code that crosses module boundaries:
Priority What to Document Why Example ⭐⭐⭐ Public utilities in /libUsed in many places; avoids ripple bugs /** @param {string} slug */⭐⭐ API route handlers Reduces backend/frontend mismatch /** @typedef {import("next").NextApiRequest} Req */⭐ Complex React hooks They hide non-trivial state machines see code below // lib/slugify.js /** * Converts any string into a URL-friendly slug. * * @param {string} text * @returns {string} */ export function slugify(text) { … }
3. Sprinkle Pre-made React Types (No Manual @typedef Needed)
import { ReactNode } from "react"; /** * @typedef Props * @prop {ReactNode} children * @prop {boolean} [bordered] */ /** * Fancy card component * @param {Props} props */ export default function Card({ children, bordered = false }) { … }Because Next.js ships with
@types/react, these are auto-resolved.
4. Upgrade Lint Rules, but Only Warn at First
Install:
pnpm add -D eslint-plugin-jsdocThen update
.eslintrc:{ "plugins": ["jsdoc"], "rules": { "jsdoc/require-jsdoc": ["warn", { "publicOnly": true }], "jsdoc/require-param": "warn", "jsdoc/require-returns": "off" } }Turn the dial from "warn" → "error" once compliance is ~80 %.
5. Add TSDoc (If You Need Richer Formatting)
If you only want types, JSDoc is enough. Switch to TSDoc blocks when:
• You publish an internal component library
• You generate docs with TypeDocExample:
/** * ### Retrieves user by ID * * @param id - User's numeric id * @returns User entity if found, otherwise `null`. * @example * ```ts * const user = await getUser(42); * ``` * @public */ export async function getUser(id: number): Promise<User | null> { … }TypeDoc converts that into a navigable HTML site, if desired.
6. Enforce in CI (After the Team is Comfortable)
Add a lightweight job:
- name: Type-check & lint docs run: npx tsc --noEmit && npx eslint "**/*.{js,ts,tsx}"Let it fail your PR only when:
tscerrors (checkJscatches mismatches)eslintfinds category"error"(after you promoted rules)
7. Gradual Full TS Migration (Optional)
If you ever decide to rename files to
.ts/.tsx:npx @ovyerload/unjs js-to-ts src/**/*.js(or use the VS Code refactor)- Delete
// @ts-checklines - Switch
"allowJs": falsein tsconfig when the last.jsis gone
Frequently Asked Questions 🤔
Q: Will this slow down builds?
Usingts-node --transpile-onlyin dev means your prodnext buildtime is unaffected; only CItscadds a few seconds.Q: Do I need to annotate every prop?
Nope. Infer when possible and annotate only public surfaces.Q: Does Next.js 14 support this out of the box?
Yes—Next internally runsswcnottsc, but editor/CI checks are separate and fully compatible.
TL;DR Checklist ✅
checkJs: truein config +// @ts-checkpragmas- Document public functions/modules first
- Add eslint-plugin-jsdoc (warn → error)
- Use built-in React/Next types via
importdocs - Optional: generate docs with TypeDoc if you need publishable pages
- Gate in CI only after adoption (>80 %)
Adopt in slices, celebrate quick wins, and your Next.js repo will get safer and self-documenting without a ground-up rewrite. Happy typing! 🎉
- Add a minimal jsconfig.json (or piggy-back on your existing tsconfig):
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.