filename-case

Type-unaware

Enforce filename case conventions for consistency across your codebase. This rule is part of eslint-plugin-conventions and provides LLM-optimized error messages with fix suggestions.

Quick Summary

Aspect	Details
Severity	Warning (code quality)
Auto-Fix	💡 Suggests fixes (requires manual file rename)
Category	Quality
ESLint MCP	✅ Optimized for ESLint MCP integration
Best For	Teams wanting consistent filename conventions across the codebase

Rule Details

Why This Matters

Issue	Impact	Solution
🎨 Consistency	Mixed naming styles in codebase	Enforce single convention
📁 Discoverability	Hard to find files	Predictable naming
🔄 Cross-platform	Case sensitivity issues	Use lowercase conventions
🤝 Team Alignment	Disagreements on style	Automated enforcement

Configuration

Option	Type	Default	Description
`case`	`string`	`'kebabCase'`	Case convention: `camelCase`, `kebabCase`, `pascalCase`, `snakeCase`
`ignore`	`array`	`[]`	Basenames (exact strings) or RegExps to ignore completely
`allowedUppercaseFiles`	`string[]`	`['README', 'LICENSE', 'CHANGELOG', ...]`	Uppercase filenames allowed without extension
`allowedKebabCase`	`string[]`	`[]`	Specific files allowed to use kebab-case
`allowedSnakeCase`	`string[]`	`[]`	Specific files allowed to use snake_case
`allowedCamelCase`	`string[]`	`[]`	Specific files allowed to use camelCase
`allowedPascalCase`	`string[]`	`[]`	Specific files allowed to use PascalCase

Case Style Reference

Case Style	Pattern	Example
`kebabCase`	`lowercase-words`	`user-service.ts`
`camelCase`	`camelCaseWords`	`userService.ts`
`PascalCase`	`PascalCaseWords`	`UserService.ts`
`snake_case`	`lowercase_words`	`user_service.ts`

Examples

❌ Incorrect (with `kebabCase`)

src/
  UserService.ts        ❌ Should be user-service.ts
  myComponent.tsx       ❌ Should be my-component.tsx
  API_Handler.ts        ❌ Should be api-handler.ts

✅ Correct (with `kebabCase`)

src/
  user-service.ts       ✅ kebab-case
  user.ts               ✅ a single lowercase word conforms to kebab, camel and snake
  user-service.test.ts  ✅ .test / .spec / .stories / .story / .e2e / .d suffixes are not part of the name
  README.md             ✅ conventional uppercase file (allowedUppercaseFiles)
  .eslintrc.js          ✅ dotfiles are not checked

Configuration Examples

Basic Usage (Default kebab-case)

{
  rules: {
    'conventions/filename-case': 'error'
  }
}

PascalCase for React Components

{
  rules: {
    'conventions/filename-case': ['error', {
      case: 'pascalCase',
      allowedKebabCase: ['index', 'main']
    }]
  }
}

Mixed Convention with Overrides

{
  rules: {
    'conventions/filename-case': ['error', {
      case: 'kebabCase',
      allowedPascalCase: ['App', 'Button', 'Modal'],  // React components
      allowedSnakeCase: ['db_migrations'],            // Legacy
      ignore: [/\.config\./]                          // Config files
    }]
  }
}

Disable Default Uppercase Files

{
  rules: {
    'conventions/filename-case': ['error', {
      case: 'kebabCase',
      allowedUppercaseFiles: []  // Disable all uppercase exceptions
    }]
  }
}

When Not To Use

Scenario	Recommendation
🏛️ Legacy codebase	Use `ignore` for existing files
⚛️ React components	Consider `pascalCase` or add to `allowedPascalCase`
🧪 Test files	Usually follows source file convention
📦 Generated files	Add to `ignore` patterns

Comparison with Alternatives

Feature	filename-case	eslint-plugin-unicorn	Manual enforcement
Multiple cases	✅ 4 options	✅ Yes	❌ No
Per-file override	✅ Flexible	⚠️ Limited	❌ No
LLM-Optimized	✅ Yes	❌ No	❌ No
ESLint MCP	✅ Optimized	❌ No	❌ No

enforce-naming - Enforces domain-specific naming conventions
no-internal-modules - Enforces module boundaries

Known Limitations

A name with several dot-separated parts (user.controller.ts, vitest.config.ts) is checked as one name, dots included, so it conforms to no case; add such names to ignore.
An allowed<Case>Case entry exempts a name only when the name is written in that case.

Use this rule

npm install -D oxlint-plugin-conventions

npm install -D oxlint-plugin-conventions

.oxlintrc.json

{
  "jsPlugins": ["oxlint-plugin-conventions"],
  "rules": {
    "conventions/filename-case": "error"
  }
}

.oxlintrc.json

{  "jsPlugins": ["oxlint-plugin-conventions"],  "rules": {    "conventions/filename-case": "error"  }}

vite.config.ts

import { defineConfig } from 'vite-plus';

export default defineConfig({
  lint: {
    jsPlugins: ['oxlint-plugin-conventions'],
    rules: {
      'conventions/filename-case': 'error',
    },
  },
});

vite.config.ts

import { defineConfig } from 'vite-plus';export default defineConfig({  lint: {    jsPlugins: ['oxlint-plugin-conventions'],    rules: {      'conventions/filename-case': 'error',    },  },});

oxlint-plugin-conventions re-exports eslint-plugin-conventions/oxlint: the same rules under the same IDs, and no ESLint install. Why oxlint.

Did this rule catch something? Star the repo to get new CWE coverage as we ship it — or follow the AI-code-security benchmarks behind these rules.

Follow the benchmarks Star on GitHub

filename-case

Quick SummaryCopy Anchor Link

Rule DetailsCopy Anchor Link

Why This MattersCopy Anchor Link

ConfigurationCopy Anchor Link

Case Style ReferenceCopy Anchor Link

ExamplesCopy Anchor Link

❌ Incorrect (with kebabCase)Copy Anchor Link

✅ Correct (with kebabCase)Copy Anchor Link

Configuration ExamplesCopy Anchor Link

Basic Usage (Default kebab-case)Copy Anchor Link

PascalCase for React ComponentsCopy Anchor Link

Mixed Convention with OverridesCopy Anchor Link

Disable Default Uppercase FilesCopy Anchor Link

When Not To UseCopy Anchor Link

Comparison with AlternativesCopy Anchor Link

Related RulesCopy Anchor Link

Further ReadingCopy Anchor Link

Known LimitationsCopy Anchor Link