horusgoul/react-render-types-setup

React Render Types — Setup

Install and configure eslint-plugin-react-render-types to enforce component composition constraints at lint time.

Prerequisites

• ESLint >= 9 (flat config)
• TypeScript >= 5
• @typescript-eslint/parser >= 8
• A working tsconfig.json

Install

npm install eslint-plugin-react-render-types --save-dev

ESLint Configuration

Typed linting is required — the plugin uses TypeScript's type checker for cross-file component identity.

Recommended (extends preset)

// eslint.config.js
import tseslint from "typescript-eslint";
import reactRenderTypes from "eslint-plugin-react-render-types";

export default [
  ...tseslint.configs.recommended,
  reactRenderTypes.configs.recommended,
  {
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
];

Manual (pick rules individually)

// eslint.config.js
import reactRenderTypes from "eslint-plugin-react-render-types";
import tsParser from "@typescript-eslint/parser";

export default [
  {
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        projectService: true,
        ecmaFeatures: { jsx: true },
      },
    },
    plugins: {
      "react-render-types": reactRenderTypes,
    },
    rules: {
      "react-render-types/valid-render-return": "error",
      "react-render-types/valid-render-prop": "error",
      "react-render-types/valid-renders-jsdoc": "warn",
      "react-render-types/renders-uses-vars": "error",
    },
  },
];

Typed Linting

Two options — pick one:

Option 1: projectService (recommended)

parserOptions: {
  projectService: true,
}

Automatically infers tsconfig for each file.

Option 2: Explicit project path

parserOptions: {
  project: './tsconfig.json',
  // Monorepos: project: ['./tsconfig.json', './packages/*/tsconfig.json'],
}

Rules

| Rule | Default | Purpose | |------|---------|---------| | valid-render-return | error | Component return matches its @renders declaration | | valid-render-prop | error | Props/children receive compatible components | | valid-renders-jsdoc | warn | @renders syntax is well-formed (braces, PascalCase) | | renders-uses-vars | error | Prevents no-unused-vars on @renders references | | require-renders-annotation | off | Requires @renders on all components |

Enabling require-renders-annotation for specific paths

export default [
  reactRenderTypes.configs.recommended,
  {
    files: ["src/design-system/**/*.tsx"],
    rules: {
      "react-render-types/require-renders-annotation": "error",
    },
  },
];

Settings

additionalTransparentComponents

Specify component names to treat as transparent wrappers without @transparent JSDoc. Useful for built-in components like Suspense or third-party components you can't annotate. Note that @transparent annotations are resolved cross-file automatically, so settings are only needed for components without JSDoc.

String entries default to looking through children. Object entries specify which props to look through:

// eslint.config.js
export default [
  reactRenderTypes.configs.recommended,
  {
    languageOptions: {
      parserOptions: { projectService: true },
    },
    settings: {
      "react-render-types": {
        additionalTransparentComponents: [
          "Suspense",
          "ErrorBoundary",
          { name: "Flag", props: ["off", "children"] },
        ],
      },
    },
  },
];

For member expressions like <React.Suspense>, use the dotted form: "React.Suspense".

These merge with @transparent JSDoc annotations — both sources are combined. @transparent annotations work cross-file automatically via TypeScript's type checker.

additionalComponentWrappers

The plugin recognizes forwardRef and memo as component wrappers by default. If you use other wrapper functions (e.g., MobX's observer, styled-components' styled), add them so the plugin can detect @renders annotations on wrapped components:

settings: {
  "react-render-types": {
    additionalComponentWrappers: ["observer", "styled"],
  },
},

This matches both direct calls (observer(...)) and member expressions (mobx.observer(...)).

IDE Integration: Language Service Plugin

The plugin includes a TypeScript Language Service Plugin that enhances the IDE experience for @renders annotations.

Add to tsconfig.json:

{
  "compilerOptions": {
    "plugins": [
      { "name": "eslint-plugin-react-render-types/lsp" }
    ]
  }
}

Then restart the TypeScript server (VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server").

Features:

• Unused import suppression — Imports referenced only in @renders annotations are kept visible and won't be auto-removed by "organize imports"
• Go-to-definition — Cmd+Click on component names inside @renders annotations navigates to the component definition
• Hover info — Hovering component names inside @renders shows the same type information as hovering the import
• Diagnostics — Warns when a component name in @renders doesn't resolve to any import or declaration in the file
• Completions — Autocompletes component names when typing inside @renders { } braces
• Find references — "Find All References" on a component includes @renders annotation usages across the project
• Rename — Renaming a component updates @renders annotations that reference it

Important: This is IDE-only — it runs in the editor's TypeScript language service, not during tsc CLI builds. For CI, use @typescript-eslint/no-unused-vars with the renders-uses-vars rule.

Troubleshooting

| Error | Fix | |-------|-----| | Plugin throws without type info | Add projectService: true to parserOptions | | "Cannot read file tsconfig.json" | Check project path is correct relative to ESLint CWD | | "File is not part of a TypeScript project" | Add file to tsconfig include, or use projectService: { allowDefaultProject: ['*.tsx'] } | | no-unused-vars on @renders imports | Ensure renders-uses-vars rule is enabled (included in recommended) | | IDE shows unused import for @renders reference | Add the language service plugin to tsconfig.json compilerOptions.plugins (see IDE Integration above) | | Performance issues | Run TIMING=1 eslint . — see typescript-eslint perf docs |