@clerk/eslint-plugin weekly downloads statistics

<p align="center"> <a href="https://clerk.com?utm_source=github&utm_medium=clerk_eslint_plugin" target="_blank" rel="noopener noreferrer"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://images.clerk.com/static/logo-dark-mode-400x400.png"> <img src="https://images.clerk.com/static/logo-light-mode-400x400.png" height="64"> </picture> </a> <br /> </p>

@clerk/eslint-plugin

<div align="center">

Changelog · Report a Bug · Request a Feature · Get help

</div>

Overview

[!NOTE] This lint rule is experimental, but should already be working well.

We encourage trying it out and getting in touch with us about your experience.

If you try it out, pin your version as we might do breaking changes in minors before v1.

ESLint rules to help with Clerk patterns across JavaScript frameworks.

Currently includes a Next.js App Router rule to help enforce protecting resources where they are used. Instead of relying on a proxy matcher, you declare which folders are protected and the require-auth-protection rule flags any page, layout, template, default, route, or Server Function under those folders that doesn't guard itself.

Client components are not checked by the rule. These can only get privileged access through other protected resources, or via external API calls which are assumed to be separately protected.

The rule only detects protected or not, which corresponds to signed in/signed out. You are still responsible for making sure the checks are correct and that the user has the correct permissions to access the resource.

The config declares intent for tooling — it does not guard anything at runtime. Protection only happens when each resource calls await auth.protect() (or an equivalent check). This rule verifies that it does.

Installation

npm install --save-dev @clerk/eslint-plugin

Requires ESLint >=9 (flat config), and also works with Oxlint when configured as a jsPlugin.

Usage

Register the plugin and declare your protected/public folder globs in eslint.config.mjs, for example:

import clerkNext from '@clerk/eslint-plugin/next';

export default [
  {
    plugins: { '@clerk/next': clerkNext },
    rules: {
      '@clerk/next/require-auth-protection': [
        'error',
        {
          protected: ['**'],
          public: ['src/app/sign-in/**', 'src/app/sign-up/**'],
        },
      ],
    },
  },
];

You need to adapt the exact paths to your application structure.

This rule also works with Oxlint, you can configure the rules just like above after adding the plugin as a jsPlugin in .oxlintrc.json:

"jsPlugins": [
  {
    "name": "@clerk/next",
    "specifier": "@clerk/eslint-plugin/next"
  }
]

Note that the bulk auto-fixer described further down does require eslint to be installed.

Options

Option	Type	Default	Description
protected	string[] (required)	—	Folder globs relative to the project root whose resources must be guarded.
public	string[]	[]	Folder globs relative to the project root that are exempt.
resources	object	all true	Resource groups to check. Supports routeHandlers, serverFunctions, and serverComponentEntrypoints, each as an optional boolean.
mixedScopeLayouts	'auto' | string[]	'auto'	Layouts/templates that intentionally wrap both protected and public descendants. 'auto' allows them silently; a list requires each such folder to be acknowledged explicitly.
rootDir	string	(auto)	Project root used to resolve project-relative folder globs. Defaults to the nearest ancestor eslint.config.*, then ESLint/Oxlint cwd. Relative paths are resolved against cwd.

Globs use a minimal dialect — only * (single segment) and ** (any depth). When a folder matches both protected and public, the most specific pattern wins, and protected wins ties.

Path matching

protected and public are project-relative folder globs. Use app/** for a root app directory, src/app/** for a src/app directory, and src/**, shared/**, etc. for other project folders.

The project root is normally determined by the nearest eslint.config.* ancestor of the file being checked, and falls back to cwd. You can configure it manually using rootDir; relative rootDir values are resolved against ESLint/Oxlint cwd.…