useFilenamingConvention

Diagnostic Category: lint/style/useFilenamingConvention

JavaScript (and super languages)

Since: v1.5.0 Sources:

Inspired from: unicorn/filename-case

Enforce naming conventions for JavaScript and TypeScript filenames.

Enforcing naming conventions helps to keep the codebase consistent.

A filename consists of two parts: a name and a set of consecutive extensions. For instance, my-filename.test.js has my-filename as name, and two consecutive extensions: .test and .js.

By default, the rule ensures that the name is either in camelCase, kebab-case, snake_case, or equal to the name of one export in the file. By default, the rule ensures that the extensions are either in camelCase, kebab-case, or snake_case.

The rule supports the following exceptions:

The name of the file can start with a dot or a plus sign, be prefixed and suffixed by underscores _. For example, .filename.js, +filename.js, __filename__.js, or even .__filename__.js.

The convention of prefixing a filename with a plus sign is used by Sveltekit and Vike.

Also, the rule supports dynamic route syntaxes of Next.js, SolidStart, Nuxt, and Astro. For example [...slug].js and [[...slug]].js are valid filenames.

Note that if you specify the `match’ option, the previous exceptions will no longer be handled.

Ignoring some files

Sometimes you want to completely ignore some files. Biome ignore comments cannot be used because the rule applies on filenames not file contents. To ignore files, you can use overrides. If you want to ignore all files in the test directory, then you can disable the rule for those files only:

{
  "overrides": [
    {
       "include": ["test/**/*"],
       "linter": {
         "rules": {
           "style": {
             "useFilenamingConvention": "off"
           }
         }
       }
    }
  ]
}

Options

The rule provides several options that are detailed in the following subsections.

{
    "options": {
        "strictCase": false,
        "requireAscii": true,
        "match": "%?(.+?)[.](.+)", // Since v2.0.0
        "filenameCases": ["camelCase", "export"]
    }
}

strictCase

When this option is set to true, it forbids consecutive uppercase characters in camelCase and PascalCase. For instance, when the option is set to true, agentID will throw an error. This name should be renamed to agentId.

When the option is set to false, consecutive uppercase characters are allowed. agentID is so valid.

Default: true

requireAscii

When this option is set to true, it forbids names that include non-ASCII characters. For instance, when the option is set to true, café or 안녕하세요 will throw an error.

When the option is set to false, a name may include non-ASCII characters. café and 안녕하세요 are so valid.

Default: false

This option will be turned on by default in Biome 2.0.

match (Since v2.0.0)

match defines a regular expression that the filename must match. If the regex has capturing groups, then the first capture is considered as the filename and the second one as file extensions separated by dots.

For example, given the regular expression %?(.+?)\.(.+) and the filename %index.d.ts, the filename matches the regular expression with two captures: index and d.ts. The captures are checked against filenameCases. Note that we use the non-greedy quantifier +? to stop capturing as soon as we met the next character (.). If we use the greedy quantifier + instead, then the captures could be index.d and ts.

The regular expression supports the following syntaxes:

Greedy quantifiers *, ?, +, {n}, {n,m}, {n,}, {m}
Non-greedy quantifiers *?, ??, +?, {n}?, {n,m}?, {n,}?, {m}?
Any character matcher .
Character classes [a-z], [xyz], [^a-z]
Alternations |
Capturing groups ()
Non-capturing groups (?:)
Case-insensitive groups (?i:) and case-sensitive groups (?-i:)
A limited set of escaped characters including all special characters and regular string escape characters \f, \n, \r, \t, \v

filenameCases

By default, the rule enforces that the filename is either in camelCase, kebab-case, snake_case, or equal to the name of one export in the file.

You can enforce a stricter convention by setting filenameCases option. filenameCases accepts an array of cases among the following cases: camelCase, kebab-case, PascalCase, snake_case, and export.

This option also applies to the file extensions. Extensions in lowercase are always allowed regardless of how filenameCases is set.