// Results:
// ✅ src/components/Button/Button.tsx
// ✅ src/components/Header/Header.tsx
// ✅ src/components/Button/Button.module.css
// ❌ src/components/Button/index.tsx (must be Button.tsx)
// ❌ src/components/Header/header.tsx (must match folder: Header.tsx)
// ❌ src/components/Button/styles.module.css (must be Button.module.css)
`

#### Positional Capture Groups
Additionally, the plugin supports positional capture group aliases starting from index 0. For example, if your match pattern is src//.tsx and the file path is src/components/Button.tsx, then <0> resolves to components and <1> resolves to Button. Read more about glob capture groups in the [micromatch][micromatch-capture] documentation.

$3

Define reusable patterns in your ESLint settings:

`ts
export default [
{
settings: {
"naming-conventions": {
aliases: {
"component": "{Component,Container,Provider}",
}
}
}
},
{
rules: {
"naming-conventions/enforce": [
"error",
{
rules: [
{
match: "src/components/*/.tsx",
enforce: { files: "" }
},
]
}
]
}
}
];

// Results:
// ✅ src/components/UserComponent.tsx
// ✅ src/components/AuthContainer.tsx
// ✅ src/components/ThemeProvider.tsx
// ❌ src/components/UserManager.tsx (doesn't end with Component/Container/Provider)
// ❌ src/components/useAuthComponent.tsx (doesn't start with PascalCase)
`

$3

The plugin uses [micromatch][micromatch] for powerful glob pattern matching. Here are common patterns you can use:

| Pattern | Description | Example Match |
|---------|-------------|---------------|
| | Matches any characters (except path separators) | .js → file.js |
| | Matches any characters including path separators | /*.js → src/utils/file.js |
| ? | Matches exactly one character | file?.js → file1.js |
| [abc] | Matches any character in brackets | file[12].js → file1.js, file2.js |
| {a,b} | Matches any of the comma-separated patterns | *.{js,ts} → file.js, file.ts |
| !(pattern) | Matches anything except the pattern | !(*.test).js → file.js (not file.test.js) |
| +(pattern) | Matches one or more occurrences | +(foo).js → foo.js, foofoo.js |
| (pattern) | Matches zero or more occurrences | (foo).js → .js, foo.js |
| ?(pattern) | Matches zero or one occurrence | ?(foo).js → .js, foo.js |
| @(pattern) | Matches exactly one of the patterns | @(foo|bar).js → foo.js, bar.js |

Complex examples:

`ts
{
rules: [
{
// Match TypeScript files but exclude test files
match: "*/!(.test).ts",
enforce: { files: "" }
},
{
// Match component files with optional test/story suffix
match: "src/components/*/.tsx",
enforce: { files: "?(.test|.stories)" }
},
{
// Match API routes with version numbers
match: "api/v[0-9]/*/.ts",
enforce: { files: "" }
}
]
}

// Results:
// ✅ user-service.ts
// ✅ src/components/Button.tsx
// ✅ src/components/Button.test.tsx
// ✅ src/components/Header.stories.tsx
// ✅ api/v1/user-profile.ts
// ✅ api/v2/shopping-cart.ts
// ❌ userService.ts (non-test files must be kebab-case)
// ❌ userService.test.ts (test files not allowed for *.ts)
// ❌ src/components/button.tsx (must be PascalCase)
// ❌ src/components/Button.spec.tsx (only .test or .stories allowed)
// ❌ api/v1/userProfile.ts (must be kebab-case, 2 rules match this file)
`

You can test your patterns with online tools like the [Digital Ocean Glob Tool][glob-tester].

Note: If you find yourself writing complex glob patterns, consider using Boolean Logic in Matchers and Multiple Rule Sets for better readability.

$3

Use matcher objects for complex matching logic with boolean operators:

`ts
{
rules: [
{
// Match TypeScript files NOT in test or mock folders
match: {
type: "all", // all patterns must match
patterns: [
"*/.ts",
"!/__tests__/",
"!/__mocks__/",
"!*/.test.ts",
"!*/.spec.ts",
"!*/.mock.ts"
]
},
enforce: { files: "" }
},
{
// Match files in EITHER components OR containers
match: {
type: "any", // any pattern can match
patterns: [
"src/components/*/.tsx",
"src/containers/*/.tsx"
]
},
enforce: { files: "" }
},
]
}

// Results:
// ✅ src/services/userService.ts
// ✅ src/api/dataProcessor.ts
// ✅ src/components/Button.tsx
// ✅ src/containers/UserDashboard.tsx
// ❌ src/services/UserService.ts (must be camelCase)
// ❌ src/components/button.tsx (must be PascalCase)
// ❌ src/__tests__/userService.ts (excluded from rule)
// ❌ userService.test.ts (excluded from rule)
`

#### Matcher Types

- any (default): Match if ANY pattern matches
- all: Match only if ALL patterns match

The default matcher type is any, so you can also provide an array of patterns directly for simple OR logic:

`ts
{
match: ["src/components//.tsx", "src/containers//.tsx"],
enforce: { files: "" }
}
`

$3

Just like match, the enforce.files and enforce.folder properties support the same flexible pattern matching:

`ts
{
rules: [
{
// Simple array - allows any of these patterns (OR logic)
match: "*/.config.{js,ts}",
enforce: {
files: [
".config",
".config",
".config"
]
}
},
{
// Using matcher object for complex logic
match: "src/components/*/.tsx",
enforce: {
files: {
type: "all", // File must satisfy ALL patterns
patterns: [
"*", // Must start with PascalCase
"*{Component,Container,Provider}" // Must end with specific suffix
]
}
}
},
{
// Different patterns for files and folders
match: "src/features///.{ts,tsx}",
enforce: {
// default type is "any"
files: ["", ""],
folder: {
type: "any",
patterns: ["", ""]
}
}
}
]
}

// Results:
// ✅ webpack.config.js (matches camel-case pattern)
// ✅ WebPack.config.ts (matches pascal-case pattern)
// ✅ webpack-config.config.ts (matches kebab-case pattern)
// ✅ src/components/UserComponent.tsx (PascalCase + Component suffix)
// ✅ src/components/AuthContainer.tsx (PascalCase + Container suffix)
// ✅ src/features/user-auth/userService.ts (kebab folder, camel file)
// ✅ src/features/data_processor/DataProcessor.tsx (snake folder, pascal file)
// ❌ WEBPACK.config.ts (doesn't match any allowed pattern)
// ❌ src/components/UserManager.tsx (doesn't end with required suffix)
// ❌ src/components/authComponent.tsx (doesn't start with PascalCase)
// ❌ src/features/UserAuth/service.ts (folder must be kebab or snake case)
`

The enforce properties support the same matcher types as match - see Matcher Types for detailed explanations of any and all types.

$3

You can make use of Multiple Rule Sets and
apply-and-continue Chaining Control to create a configuration that prohibits certain patterns in your file or folder names across your codebase.

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},

{
rules: {
"naming-conventions/enforce": [
"error",
{
// Must use "apply-and-continue" to continue to next rule set
chaining: "apply-and-continue",
rules: [
{
// Prohibit index files in component folders
match: "src/components/*/index.{js,jsx,ts,tsx}",
enforce: { files: "error" }
},
{
// Prohibit uppercase folder names
match: "src//[A-Z]/",
enforce: { folder: "error" }
},
{
// Prohibit files with "Helper" or "Util" in name
match: "src/utils/*/{Helper,Util}*.ts",
enforce: { files: "error" }
}
]
},
{
rules: [
// Rest of your naming conventions
]
}
]
}
},
];

// Results:
// ✅ src/components/button/Button.tsx
// ✅ src/utils/date-formatter.ts
// ✅ src/utils/arrayProcessor.ts
// ❌ src/components/button/index.tsx (index files prohibited)
// ❌ src/components/Button/Button.tsx (uppercase folder prohibited)
// ❌ src/utils/DateHelper.ts (Helper prohibited)
`

$3

For more complex projects like monorepos, you can pass multiple configuration objects as an array to a single Eslint rule. This is useful when you need different rules for different parts of your codebase - such as different packages with different conventions, legacy code gradually migrating to new naming conventions, or different teams with different preferences:

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},

{
rules: {
"naming-conventions/enforce": [
"error",
{
id: "core-package",
scope: "packages/core/**",
rules: {
match: "*/.ts",
enforce: { files: "" }
}
},
{
id: "ui-package",
scope: "packages/ui/**",
rules: [
{ match: "*/.tsx", enforce: { files: "" } },
{ match: "*/hooks/.ts", enforce: { files: "use" } }
]
},
{
id: "other-files",
rules: [
{ match: "*/.{js,ts}", enforce: { files: "" } },
{ match: "*/.{jsx,tsx}", enforce: { files: "" } }
]
}
]
}
}
];

// Results:
// ✅ packages/core/database_client.ts (snake_case)
// ✅ packages/core/utils/index.ts
// ✅ packages/ui/Button.tsx (PascalCase)
// ✅ packages/ui/hooks/useAuth.ts (use + PascalCase)
// ✅ src/utils/helpers.js (camelCase - general rule)
// ✅ src/components/Header.jsx (PascalCase - general rule)
// ❌ packages/core/databaseClient.ts (must be snake_case)
// ❌ packages/core/utils/Index.ts (must be 'index')
// ❌ packages/ui/button.tsx (must be PascalCase)
// ❌ packages/ui/hooks/authHook.ts (must start with 'use')
`

#### Scope

The scope property acts as a matcher to limit which files a rule set applies to. When specified, the rule set only processes files that match the scope pattern.

Important Behavior: If a file falls within a rule set's scope, processing stops after that rule set (even if no rules matched) due to the default apply-and-stop chaining behavior.

`ts
{
id: "test-files",
scope: {
type: "all",
patterns: [
"*/.test.{js,ts,jsx,tsx}",
"!/examples/"
]
},
rules: {
match: "*/",
enforce: { files: ".test" }
}
}
`

#### Rule Sets Chaining

When using multiple rule sets, you can control the processing flow with the chaining option. This determines whether processing continues to subsequent rule sets or stops after the current one.

Chaining Options:

- apply-and-stop (default) - Stop processing after the current rule set
- If a file matches the rule set's scope, processing stops immediately
- This happens even if no rules within the set matched the file
- Use this for exclusive rule sets where you want clear boundaries

- apply-and-continue - Continue to the next rule set
- Processing continues regardless of matches in the current set
- Useful for layered rules (e.g., global validations + specific requirements)
- Allows multiple rule sets to apply to the same files

When to use each option:
- Use apply-and-continue for cross-cutting concerns like test organization, prohibited patterns, or global validations
- Use apply-and-stop for mutually exclusive scopes like different apps in a monorepo or different coding standards


`ts
{
rules: {
"naming-conventions/enforce": [
"error",
[
{
id: "test-organization",
chaining: "apply-and-continue", // Continue to app-specific rules
rules: {
// Ensure test files are in __tests__ folders
match: "*/.{test,spec}.{js,ts,jsx,tsx}",
enforce: {
files: "*.{test,spec}",
folder: "__tests__"
}
}
},
{
id: "legacy-app",
scope: "apps/legacy/**",
rules: {
match: "*/.{js,ts}",
enforce: { files: "" }
}
},
{
id: "modern-app",
scope: "apps/dashboard/**",
rules: {
match: "*/.{js,ts}",
enforce: { files: "" }
}
}
]
]
}
}

// Results:
// ✅ apps/legacy/user_service.js (snake_case - legacy-app rule set)
// ✅ apps/dashboard/user-service.js (kebab-case - modern-app rule set)
// ✅ apps/legacy/__tests__/user_service.test.js (test organization + snake_case)
// ✅ apps/dashboard/__tests__/user-service.test.js (test organization + kebab-case)
// ❌ apps/legacy/userService.js (must be snake_case - legacy-app rule set)
// ❌ apps/dashboard/user_service.js (must be kebab-case - modern-app rule set)
// ❌ apps/legacy/tests/user_service.test.js (test files must be in __tests__ folder)
// ❌ apps/dashboard/user-service.spec.js (test files must be in __tests__ folder)
// Note: Test organization rule runs first, then app-specific rules apply based on scope
`


##### Scope and apply-and-stop Behavior Matrix

The table below shows how scope and rule matching interact with the default apply-and-stop behavior:

`ts
{
id: "test-files",
scope: {
type: "all",
patterns: [
"*/.test.{js,ts,jsx,tsx}",
"!/examples/"
]
},
rules: {
match: "*/",
enforce: { files: ".test" }
}
}
`

| File Path | Within Scope? | Rule Matches? | Continue to Next Rule Set? |
|-----------|---------------|---------------|---------------------------|
| src/auth.test.ts | ✅ Yes | ✅ Yes | ❌ No |
| src/auth.test.js | ✅ Yes | ✅ Yes | ❌ No |
| src/AUTH.TEST.ts | ✅ Yes | ❌ No (wrong case) | ❌ No |
| examples/demo.test.ts | ❌ No (out of scope) | N/A | ✅ Yes |
| src/utils.ts | ❌ No (out of scope) | N/A | ✅ Yes |

$3

The processor enables ESLint to check file types that don't have built-in processors. This is useful when you want to apply naming conventions to configuration files, documentation, images, and other non-code assets that aren't typically processed by other ESLint plugins.

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},

// Add processor for file types that need naming convention checks
{
files: ["*/.{yaml,yml,json,md,css,svg,png,jpg,webp}"],
processor: "naming-conventions/processor"
},

{
rules: {
"naming-conventions/enforce": [
"error",
{
rules: [
// Configuration files should be kebab-case
{
match: "*/.{json,yaml,yml}",
enforce: { files: "" }
},
// Documentation files should be kebab-case
{
match: "*/.md",
enforce: { files: "" }
},
// Images and assets should be kebab-case
{
match: "*/.{svg,png,jpg,jpeg,webp}",
enforce: { files: "" }
},
// CSS files should be kebab-case
{
match: "*/.css",
enforce: { files: "" }
}
]
}
]
}
}
];

// Results:
// ✅ package.json
// ✅ docker-compose.yml
// ✅ api-documentation.md
// ✅ user-avatar.png
// ✅ main-styles.css
// ❌ packageLock.json (must be kebab-case)
// ❌ Docker_Compose.yml (must be kebab-case)
// ❌ API_Documentation.md (must be kebab-case)
// ❌ UserAvatar.png (must be kebab-case)
`

Recipes

Specific configuration examples for common use cases.

$3

Configure naming conventions for Next.js 13+ App Router projects. The plugin provides built-in support for App Router's special folder conventions including dynamic routes ([slug]), route groups ((group)), parallel routes (@parallel), and intercepting routes ((..)folder).

Use the alias to validate these special folder naming patterns alongside your custom naming requirements.

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},
{
rules: {
"naming-conventions/enforce": [
"error",
{
id: "Next.js App Router",
scope: "src/app/*/",
rules: {
match: "*/",
enforce: {
files: "",
folder: ""
}
}
},
{
rules: [
// Rest of your naming conventions
]
}
]
}
}
];

// Results:
// ✅ app/dashboard/page.tsx
// ✅ app/users/[id]/page.tsx (folder: [id])
// ✅ app/(auth)/login/page.tsx (folder: (auth))
// ✅ app/api/users/route.ts
// ❌ app/dashboard/Page.tsx (must be lowercase 'page')
// ❌ app/UserDashboard/page.tsx (folder must be kebab-case or Next.js pattern)
`

$3

Configure naming conventions for traditional Next.js Pages Router projects. The plugin recognizes Pages Router's special files (_app, _document, _error) and dynamic routing patterns ([id], [...slug], [[...optional]]).

Use the alias to accommodate these framework-specific naming requirements while enforcing consistent naming for your application pages.

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},
{
rules: {
"naming-conventions/enforce": [
"error",
{
id: "Next.js Pages Router",
rules: {
match: "pages/*/.{js,jsx,ts,tsx}",
enforce: {
files: ""
}
}
},
{
rules: [
// Rest of your naming conventions
]
}
]
}
}
];

// Results:
// ✅ pages/_app.tsx
// ✅ pages/_document.tsx
// ✅ pages/blog/[slug].tsx
// ✅ pages/api/auth-handler.ts
// ❌ pages/AboutUs.tsx (must be kebab-case)
// ❌ pages/api/authHandler.ts (must be kebab-case)
`

$3

Configure naming conventions for Astro projects with built-in support for Astro's file-based routing system. The plugin understands Astro's route patterns including static routes, dynamic routes ([slug]), rest parameters ([...path]), and special files like 404.astro.

The alias matches these framework-specific routing patterns.

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},
{
rules: {
"naming-conventions/enforce": [
"error",
{
id: "Astro Routes",
rules: {
match: "src/pages/*/.astro",
enforce: { files: "", folder: "" }
}
},
{
rules: [
// Rest of your naming conventions
]
}
]
}
}
];

// Results:
// ✅ src/pages/index.astro
// ✅ src/pages/blog/[slug].astro
// ✅ src/pages/docs/[...path].astro
// ✅ src/pages/api/webhook.ts
// ❌ src/pages/Index.astro (must be lowercase)
// ❌ src/pages/blog/Slug.astro (dynamic routes use brackets)
`

$3

Improve code clarity by prohibiting index files and enforcing explicit naming. This approach makes imports more descriptive and prevents "barrel export" patterns that can hurt bundle size and tree-shaking.

Benefits:
- More explicit imports: import Button from './Button/Button' instead of import Button from './Button'
- Better IDE navigation and search functionality
- Clearer file structure and purpose
- Improved bundle analysis and tree-shaking

Use Multiple Rule Sets with apply-and-continue chaining to first check for prohibited index files, then apply your standard naming conventions:

`ts
export default [
{
plugins: {
"naming-conventions": namingConventions,
},
},
{
rules: {
"naming-conventions/enforce": [
"error",
{
id: "prohibit-index",
chaining: "apply-and-continue",
rules: [
{
match: "src/**/index.{js,jsx,ts,tsx}",
enforce: { files: "error" }
}
]
},
// Second rule set: Enforce standard naming conventions
{
id: "standard-naming",
rules: [
{
match: "src/components/*/",
enforce: {
files: "",
folder: ""
}
},
{
match: "src/{utils,services,hooks}/*/",
enforce: {
files: "",
folder: ""
}
}
]
}
]
}
}
];

// Results:
// ✅ src/components/Button/Button.tsx
// ✅ src/components/Modal/Modal.jsx
// ✅ src/utils/validation/emailValidator.ts
// ✅ src/services/auth/authService.js
// ❌ src/components/Button/index.tsx (prohibited by prohibit-index rule set)
// ❌ src/utils/helpers/index.ts (prohibited by prohibit-index rule set)
// ❌ src/services/api/index.js (prohibited by prohibit-index rule set)
// ❌ src/components/modal/modal.jsx (violates pascal-case rule from standard-naming)
`

The apply-and-continue chaining ensures both rule sets are evaluated: first checking for prohibited index files, then applying standard naming conventions to all files (including those that pass the index check).

$3

Ensure React components are organized with matching file and folder names:

`ts
{
rules: [
{
// Component file must match its folder name
match: "src/components//.{jsx,tsx}",
enforce: { files: "