Skip to content
TheChatArchiveThe Chat Archive
o3-2025-04-16· OpenAIHugging Face LMArena Human Preference 140K

Can you provide some tips on incrementally adopting JSDoc/TSDoc in my Next.js project?

From a Chatbot Arena battleThe same person sent this prompt to two anonymous models at once. Compare it with Metallama-4-scout-17b-16e-instruct’s answer.
  1. User

    Can you provide some tips on incrementally adopting JSDoc/TSDoc in my Next.js project?

  2. 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

    1. 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"]
      }
      
    2. In each JS file you want checked, drop the pragma:
      // @ts-check
      
      ➡️ You instantly get type-checking in VS Code/tsc without converting to .ts(x).

    2. Start Writing “High-Value” JSDoc Blocks Only

    Focus on code that crosses module boundaries:

    PriorityWhat to DocumentWhyExample
    ⭐⭐⭐Public utilities in /libUsed in many places; avoids ripple bugs/** @param {string} slug */
    ⭐⭐API route handlersReduces backend/frontend mismatch/** @typedef {import("next").NextApiRequest} Req */
    ⭐Complex React hooksThey hide non-trivial state machinessee 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-jsdoc
    

    Then 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 TypeDoc

    Example:

    /**
     * ### 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:

    1. tsc errors (checkJs catches mismatches)
    2. eslint finds category "error" (after you promoted rules)

    7. Gradual Full TS Migration (Optional)

    If you ever decide to rename files to .ts/.tsx:

    1. npx @ovyerload/unjs js-to-ts src/**/*.js (or use the VS Code refactor)
    2. Delete // @ts-check lines
    3. Switch "allowJs": false in tsconfig when the last .js is gone

    Frequently Asked Questions 🤔

    Q: Will this slow down builds?
    Using ts-node --transpile-only in dev means your prod next build time is unaffected; only CI tsc adds 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 runs swc not tsc, but editor/CI checks are separate and fully compatible.


    TL;DR Checklist ✅

    1. checkJs: true in config + // @ts-check pragmas
    2. Document public functions/modules first
    3. Add eslint-plugin-jsdoc (warn → error)
    4. Use built-in React/Next types via import docs
    5. Optional: generate docs with TypeDoc if you need publishable pages
    6. 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! 🎉

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.