useNamingConvention (since v1.0.0)

Diagnostic Category: lint/style/useNamingConvention

Sources:

Inspired from: @typescript-eslint/naming-convention

Enforce naming conventions for everything across a codebase.

Enforcing naming conventions helps to keep the codebase consistent, and reduces overhead when thinking about the name case of a variable.

The following section describes the default conventions enforced by the rule. You can also enforce custom conventions with the rule options.

Naming conventions

All names can be prefixed and suffixed by underscores _ and dollar signs $.

Variable and parameter names

All variables and function parameters are in camelCase or PascalCase. Catch parameters are in camelCase.

Additionally, global variables declared as const or var may be in CONSTANT_CASE. Global variables are declared at module or script level. Variables declared in a TypeScript namespace are also considered global.

function f(param, _unusedParam) {
    let localValue = 0;
    try {
        /* ... */
    } catch (customError) {
        /* ... */
    }
}

export const A_CONSTANT = 5;

let aVariable = 0;

export namespace ns {
    export const ANOTHER_CONSTANT = "";
}

Examples of incorrect names:

let a_value = 0;

style/useNamingConvention.js:1:5 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This let name should be in camelCase or PascalCase.
  
  > 1 │ let a_value = 0;
      │     ^^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - let·a_value·=·0;
      1 │ + let·aValue·=·0;
    2 2 │

const fooYPosition = 0;

style/useNamingConvention.js:1:7 lint/style/useNamingConvention ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Two consecutive uppercase characters are not allowed in camelCase because strictCase is set to `true`.
  
  > 1 │ const fooYPosition = 0;
      │       ^^^^^^^^^^^^
    2 │ 
  
  ℹ If you want to use consecutive uppercase characters in camelCase, then set the strictCase option to `false`.
    See the rule options for more details.

function f(FIRST_PARAM) {}

style/useNamingConvention.js:1:12 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This function parameter name should be in camelCase or PascalCase.
  
  > 1 │ function f(FIRST_PARAM) {}
      │            ^^^^^^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - function·f(FIRST_PARAM)·{}
      1 │ + function·f(firstParam)·{}
    2 2 │

Function names

A function name is in camelCase or PascalCase.
A global function can also be in UPPERCASE. This allows supporting the frameworks that require some function to use valid HTTP method names.

function trimString(s) { /*...*/ }

function Component() {
    return <div></div>;
}

export function GET() { /*...*/ }

TypeScript `enum` names

A TypeScript enum name is in PascalCase.

enum members are by default in PascalCase. However, you can configure the case of enum members. See options for more details.

enum Status {
    Open,
    Close,
}

Classes

A class name is in PascalCase.
Static property and static getter names are in camelCase or CONSTANT_CASE.
Class property and method names are in camelCase.

class Person {
    static MAX_FRIEND_COUNT = 256;

    static get SPECIAL_PERSON_INSTANCE() { /*...*/ }

    initializedProperty = 0;

    specialMethod() {}
}

TypeScript `type` aliases and `interface`

A type alias or an interface name are in PascalCase.
Member names of a type are in camelCase.
readonly property and getter names can also be in CONSTANT_CASE.

type Named = {
    readonly fullName: string;

    specialMethod(): void;
};

interface Named {
    readonly fullName: string;

    specialMethod(): void;
}

interface PersonConstructor {
    readonly MAX_FRIEND_COUNT: number;

    get SPECIAL_PERSON_INSTANCE(): Person;

    new(): Person;
}

Examples of an incorrect type alias:

type person = { fullName: string };

style/useNamingConvention.js:1:6 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This type alias name should be in PascalCase.
  
  > 1 │ type person = { fullName: string };
      │      ^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in PascalCase.
  
    1   │ - type·person·=·{·fullName:·string·};
      1 │ + type·Person·=·{·fullName:·string·};
    2 2 │

Literal object member names

Literal object members are in camelCase.

const alice = {
    fullName: "Alice",
}

Example of an incorrect name:

const alice = {
    full_name: "Alice",
}

style/useNamingConvention.js:2:5 lint/style/useNamingConvention ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This object property name should be in camelCase.
  
    1 │ const alice = {
  > 2 │     full_name: "Alice",
      │     ^^^^^^^^^
    3 │ }
    4 │

Import and export aliases and namespaces

Import and export namespaces are in camelCase or PascalCase.

import * as myLib from "my-lib";
import * as Framework from "framework";

export * as myLib from "my-lib";
export * as Framework from "framework";

import and export aliases are in camelCase, PascalCase, or CONSTANT_CASE:

import assert, {
    deepStrictEqual as deepEqual,
    AssertionError as AssertError
} from "node:assert";

Examples of an incorrect name:

import * as MY_LIB from "my-lib";

style/useNamingConvention.js:1:13 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ This import namespace name should be in camelCase or PascalCase.
  
  > 1 │ import * as MY_LIB from "my-lib";
      │             ^^^^^^
    2 │ 
  
  ℹ Safe fix: Rename this symbol in camelCase.
  
    1   │ - import·*·as·MY_LIB·from·"my-lib";
      1 │ + import·*·as·myLib·from·"my-lib";
    2 2 │

TypeScript type parameter names

A TypeScript type parameter name is in PascalCase.

function id<Val>(value: Val): Val { /* ... */}

TypeScript `namespace` names

A TypeScript namespace names are in camelCase or in PascalCase.

namespace mathExtra {
    /*...*/
}

namespace MathExtra {
    /*...*/
}

Options

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

{
    "//": "...",
    "options": {
        "strictCase": false,
        "requireAscii": true,
        "enumMemberCase": "CONSTANT_CASE",
        "conventions": [
            {
                "selector": {
                    "kind": "memberLike",
                    "modifiers": ["private"]
                },
                "match": "_(.+)",
                "formats": ["camelCase"]
            }
        ]
    }
}

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, HTTPServer or aHTTPServer will throw an error. These names should be renamed to HttpServer and aHttpServer

When the option is set to false, consecutive uppercase characters are allowed. HTTPServer and aHTTPServer are 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, names may include non-ASCII characters. café and 안녕하세요 are so valid.

Default: false

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

enumMemberCase

By default, the rule enforces the naming convention followed by the TypeScript Compiler team: an enum member is in PascalCase.

You can enforce another convention by setting enumMemberCase option. The supported cases are: PascalCase, CONSTANT_CASE, and camelCase.

This option will be deprecated in the future. Use the conventions option instead.

conventions

The conventions option allows applying custom conventions. The option takes an array of conventions. Every convention is an object that includes a selector and some requirements (match and formats).

For example, you can enforce the use of CONSTANT_CASE for global const declarations:

{
    "//": "...",
    "options": {
        "conventions": [
            {
                "selector": {
                    "kind": "const",
                    "scope": "global"
                },
                "formats": ["CONSTANT_CASE"]
            }
        ]
    }
}

A selector describes which declarations the convention applies to. You can select a declaration based on several criteria:

kind: the kind of the declaration among:
- any (default kind if the kind is unset)
- typeLike: classes, enums, type aliases, and interfaces
- class
- enum
- interface
- typeAlias
- function: named function declarations and expressions
- namespaceLike: TypeScript namespaces, import and export namespaces (import * as namespace from)
- namespace: TypeScript namespaces
- importNamespace
- exportNamespace
- importAlias: default imports and aliases of named imports
- exportAlias: aliases of re-exported names
- variable: const, let, using, and var declarations
- const
- let
- var
- using
- functionParameter
- catchParameter
- indexParameter: parameters of index signatures
- typeParameter: generic type parameter
- classMember: class properties, parameter properties, methods, getters, and setters
- classProperty: class properties, including parameter properties
- classMethod
- classGetter
- classSetter
- objectLiteralMember: literal object properties, methods, getters, and setters
- objectLiteralProperty
- objectLiteralMethod
- objectLiteralGetter
- objectLiteralSetter
- typeMember: properties, methods, getters, and setters declared in type aliases and interfaces
- typeProperty
- typeMethod
- typeGetter
- typeSetter
modifiers: an array of modifiers among:
- abstract: applies to class members and classes
- private: applies to class members
- protected: applies to class members
- readonly: applies to class members and type members
- static: applies to class members
scope: where the declaration appears. Allowed values:
- any: anywhere (default value if the scope is unset)
- global: the global scope (also includes the namespace scopes)

For each declaration, the conventions array is traversed until a selector selects the declaration. The requirements of the convention are so verified on the declaration.

A convention must set at least one requirement among:

match: a regular expression that the name of the declaration must match. If the regular expression captures a part of the name, then this part is checked against formats. Only the first capture is tested. Other captures are ignored.
formats: the string case that the name must follow. The supported cases are: PascalCase, CONSTANT_CASE, camelCase, and snake_case.

If match is set and formats is unset, then the part of the name captured by the regular expression is forwarded to the next convention of the array.

If a declaration is not selected or if a capture is forwarded while there is no more custom conventions, Then the declaration is verified against the default convention. If a forwarded capture is a part of the original name, then underscore and dollar signs are not trimmed.

In the following example:

We require static readonly class members to be in CONSTANT_CASE.
We require private class members to start with an underscore _ and to be in camelCase.
We require global constants to be in CONSTANT_CASE and we allow these constants to be enclosed by double underscores or to be named _SPECIAL_.
We require interfaces to start with I, except for interfaces ending with Error, and to be in PascalCase.
All other names follow the default conventions

 {
     "//": "...",
     "options": {
         "conventions": [
             {
                 "selector": {
                     "kind": "classMember",
                     "modifiers": ["static", "readonly"]
                 },
                 "formats": ["CONSTANT_CASE"]
             },
             {
                 "selector": {
                     "kind": "classMember",
                     "modifiers": ["private"]
                 },
                 "match": "_(.+)",
                 "formats": ["camelCase"]
             }, {
                 "selector": {
                     "kind": "const",
                     "scope": "global"
                 },
                 "match": "__(.+)__|_SPECIAL_|(.+)",
                 "formats": ["CONSTANT_CASE"]
             }, {
                 "selector": {
                     "kind": "interface"
                 },
                 "match": "I(.*)|(.*)Error",
                 "formats": ["PascalCase"]
             }
             // default conventions
         ]
     }
 }

Regular expression syntax

The match option takes a regular expression that 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 (?:)
A limited set of escaped characters including all special characters and regular string escape characters \f, \n, \r, \t, \v