ESLint Plugin for React Server Components

1.2.0 · active · verified Sun Apr 19

eslint-plugin-react-server-components is an ESLint plugin providing rules specifically designed to manage and enforce the correct usage of React Server Components (RSCs) and Client Components. As of version 1.2.0, this plugin helps developers identify components that incorrectly mix server-side and client-side logic, primarily by ensuring that components using client-only features (like `useState`, `useEffect`, or browser APIs) are correctly prefixed with the `"use client"` directive. It also helps detect instances where `"use client"` might be unnecessarily applied. The plugin features a `recommended` configuration for easy setup and offers options like `allowedServerHooks` (introduced in v1.2.0) to whitelist specific hooks that should not trigger errors in server components. With regular patch and minor releases, the project appears to be actively maintained, adapting to the evolving best practices for RSCs, particularly relevant for frameworks like Next.js that heavily utilize this paradigm. Its key differentiation lies in its focused approach to linting the specific contract between server and client components.

Common errors

```
Parsing error: The keyword 'await' is reserved
```
cause ESLint parser not configured for modern JavaScript/JSX features or module syntax used in React Server Components or client components.

fix Ensure your ESLint configuration includes a parser like `@babel/eslint-parser` or `@typescript-eslint/parser` and appropriate `ecmaVersion` (`'latest'`) and `sourceType` (`'module'`) settings to support JSX and ES modules.
```
eslint-plugin-react-server-components/use-client: Components must be prefixed with 'use client' or be a server component.
```
cause A component intended for client-side use (e.g., using `useState`, `useEffect`, or browser APIs) lacks the `"use client"` directive at the top of its file.

fix Add `"use client"` as the very first line of the file for components that utilize client-only features. Alternatively, if it's meant to be a server component, remove any client-only hooks or APIs from it.
```
Configuration for rule 'react-server-components/use-client' is invalid
```
cause Misspelling `allowedServerHooks` or providing it with an incorrect data type or structure within the rule's options.

fix Double-check the `allowedServerHooks` option name for correct capitalization and ensure it is provided as an array within an object, which is then nested as the second element in the rule's configuration array (e.g., `['error', { 'allowedServerHooks': ['myCustomHook'] }]`).

Warnings

breaking Class components are now disallowed by the plugin, likely due to their incompatibility with the React Server Components paradigm unless explicitly marked 'use client'.
Fix: Refactor existing class components to functional components, or ensure they are explicitly marked with `"use client"` if intended for the client bundle and interact with client-only features.
gotcha Incorrect placement of the `"use client"` directive (e.g., after comments or other statements) can lead to the rule failing to detect it, causing unexpected errors or silent misinterpretations of component types.
Fix: Always place the `"use client"` directive at the very top of the file, before any imports or other code, as the first non-comment statement. Refer to the official React documentation for exact placement rules.
gotcha Failing to extend the `recommended` configuration or incorrectly naming the plugin in your `.eslintrc` can lead to rules not being applied, resulting in silently unlinted code.
Fix: Always ensure your `.eslintrc` configuration includes `"extends": ["plugin:react-server-components/recommended"]` and that `eslint-plugin-react-server-components` is correctly installed as a dev dependency.

Install

npm install eslint-plugin-react-server-components npm
yarn add eslint-plugin-react-server-components yarn
pnpm add eslint-plugin-react-server-components pnpm

Imports

Configuration via `extends`
wrong:
```
{
  "extends": ["react-server-components/recommended"]
}
```
correct:
```
{
  "extends": ["plugin:react-server-components/recommended"]
}
```
ESLint plugins are configured in `.eslintrc` files, not imported directly into application code. The `plugin:` prefix is crucial for ESLint to resolve the package.
Individual Rule `use-client`
wrong:
```
{
  "rules": {
    "use-client": "error"
  }
}
```
correct:
```
{
  "rules": {
    "react-server-components/use-client": "error"
  }
}
```
Rules within a plugin must be prefixed with the plugin's name (e.g., `react-server-components/`) when defined in the `rules` section.

Configuring `allowedServerHooks` option

wrong:

{
  "allowedServerHooks": ["useTranslation"], 
  "rules": {
    "react-server-components/use-client": "error"
  }
}

correct:

{
  "rules": {
    "react-server-components/use-client": [
      "error",
      { "allowedServerHooks": ["useTranslation"] }
    ]
  }
}

Rule options are passed as an array after the severity level. Ensure the option name `allowedServerHooks` is correctly capitalized and nested within the specific rule configuration.

Quickstart

Demonstrates a React component that uses client-side hooks (`useState`) without the necessary `"use client"` directive. This code, when linted with the plugin's recommended configuration, will trigger an error from the `react-server-components/use-client` rule, enforcing proper component type declaration for React Server Components.

import React from 'react';

// This component uses client-side state without the 'use client' directive.
// This ESLint plugin would flag this as an error under its recommended ruleset.
function MyClientComponent() {
  const [count, setCount] = React.useState(0);
  
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}

export default MyClientComponent;

// To lint this file, you would run:
// npm install --save-dev eslint eslint-plugin-react-server-components
// Create an .eslintrc.json file:
// {
//   "parserOptions": { "ecmaVersion": "latest", "sourceType": "module" },
//   "extends": ["plugin:react-server-components/recommended"]
// }
// Then run: npx eslint myClientComponent.jsx

view raw JSON →