useNamingConvention

TypeScript and TSX

Summary

Rule available since: v1.0.0
Diagnostic Category: lint/style/useNamingConvention
This rule has a safe fix.
The default severity of this rule is information.
Sources:
- Inspired from @typescript-eslint/naming-convention

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": "error"
6
      }
7
    }
8
  }
9
}

Description

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 with underscores _ and dollar signs $. Unused variables with a name prefixed with _ are completely ignored. This avoids conflicts with the noUnusedVariables rule.

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.

1
function f(param, _unusedParam) {
2
    let localValue = 0;
3
    try {
4
        /* ... */
5
    } catch (customError) {
6
        /* ... */
7
    }
8
}
9

10
export const A_CONSTANT = 5;
11

12
let aVariable = 0;
13

14
export namespace ns {
15
    export const ANOTHER_CONSTANT = "";
16
}

Examples of incorrect names:

1
let a_value = 0;

code-block.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 │

1
const fooYPosition = 0;

code-block.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.

1
function f(FIRST_PARAM) {}

code-block.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 PascalCase.
  
    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.

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

3
function Component() {
4
    return <div></div>;
5
}
6

7
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.

1
enum Status {
2
    Open,
3
    Close,
4
}

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.

1
class Person {
2
    static MAX_FRIEND_COUNT = 256;
3

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

6
    initializedProperty = 0;
7

8
    specialMethod() {}
9
}

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.

1
type Named = {
2
    readonly fullName: string;
3

4
    specialMethod(): void;
5
};
6

7
interface Named {
8
    readonly fullName: string;
9

10
    specialMethod(): void;
11
}
12

13
interface PersonConstructor {
14
    readonly MAX_FRIEND_COUNT: number;
15

16
    get SPECIAL_PERSON_INSTANCE(): Person;
17

18
    new(): Person;
19
}

Examples of an incorrect type alias:

1
type person = { fullName: string };

code-block.ts: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.

1
const alice = {
2
    fullName: "Alice",
3
}

Example of an incorrect name:

1
const alice = {
2
    full_name: "Alice",
3
}

code-block.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.

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

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

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

1
import assert, {
2
    deepStrictEqual as deepEqual,
3
    AssertionError as AssertError
4
} from "node:assert";

Examples of an incorrect name:

1
import * as MY_LIB from "my-lib";

code-block.ts: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 PascalCase.
  
    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.

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

TypeScript `namespace` names

A TypeScript namespace name is in camelCase or in PascalCase.

1
namespace mathExtra {
2
    /*...*/
3
}
4

5
namespace MathExtra {
6
    /*...*/
7
}

Ignored declarations

Note that some declarations are always ignored. You cannot apply a convention to them. This is the case for:

Member names that are not identifiers

1
class C {
2
  ["not an identifier"]() {}
3
}

Named imports

1
 import { an_IMPORT } from "mod"

Destructured object properties

1
const { destructed_PROP } = obj;

Class members marked with override:

1
class C extends B {
2
  override overridden_METHOD() {}
3
}

Declarations inside an external TypeScript module

1
declare module "myExternalModule" {
2
  export interface my_INTERFACE {}
3
}

Declarations inside a global declaration

1
declare global {
2
  interface HTMLElement {}
3
}

Options

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

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "strictCase": false,
8
            "requireAscii": false,
9
            "conventions": [
10
              {
11
                "selector": {
12
                  "kind": "classMember",
13
                  "modifiers": [
14
                    "private"
15
                  ]
16
                },
17
                "match": "_(.+)",
18
                "formats": [
19
                  "camelCase"
20
                ]
21
              }
22
            ]
23
          }
24
        }
25
      }
26
    }
27
  }
28
}

strictCase

When this option is set to true, it forbids consecutive uppercase characters in camelCase and PascalCase.

Default: true

For instance, HTTPServer or aHTTPServer are not permitted for strictCase: true. These names should be renamed to HttpServer and aHttpServer:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "strictCase": true
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
class HTTPServer {
2
}

code-block.js:1:7 lint/style/useNamingConvention  FIXABLE  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ Two consecutive uppercase characters are not allowed in PascalCase because strictCase is set to true.
  
  > 1 │ class HTTPServer {
      │       ^^^^^^^^^^
    2 │ }
    3 │ 
  
  ℹ If you want to use consecutive uppercase characters in PascalCase, then set the strictCase option to false.
    See the rule options for more details.
  
  ℹ Safe fix: Rename this symbol in PascalCase.
  
    1   │ - class·HTTPServer·{
      1 │ + class·HttpServer·{
    2 2 │   }
    3 3 │

When strictCase is set to false, consecutive uppercase characters are allowed. For example, HTTPServer and aHTTPServer would be considered valid then:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "strictCase": false
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
class HTTPServer {
2
}

requireAscii

When true, names must only consist of ASCII characters only, forbidding names like café or 안녕하세요 that include non-ASCII characters.

When requireAscii is set to false, names may include non-ASCII characters. For example, café and 안녕하세요 would be considered valid then.

Default: true

conventions

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

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

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "const",
11
                  "scope": "global"
12
                },
13
                "formats": [
14
                  "CONSTANT_CASE"
15
                ]
16
              }
17
            ]
18
          }
19
        }
20
      }
21
    }
22
  }
23
}

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
- enumMember
- 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 in-order 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.
formats: the string case that the name must follow. The supported cases are: PascalCase, CONSTANT_CASE, camelCase, and snake_case.

If only formats is set, it’s checked against the name of the declaration. In the following configuration, we require static readonly class properties to be in CONSTANT_CASE.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classProperty",
11
                  "modifiers": [
12
                    "static",
13
                    "readonly"
14
                  ]
15
                },
16
                "formats": [
17
                  "CONSTANT_CASE"
18
                ]
19
              }
20
            ]
21
          }
22
        }
23
      }
24
    }
25
  }
26
}

The following code is then reported by the rule:

1
class C {
2
    static readonly prop = 0;
3
}

code-block.ts:2:21 lint/style/useNamingConvention ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ This readonly static class property name should be in CONSTANT_CASE.
  
    1 │ class C {
  > 2 │     static readonly prop = 0;
      │                     ^^^^
    3 │ }
    4 │

A convention can make another one useless. In the following configuration, the second convention is useless because the first one always applies to class members, including class properties. You should always place first more specific conventions.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember"
11
                },
12
                "formats": [
13
                  "camelCase"
14
                ]
15
              },
16
              {
17
                "selector": {
18
                  "kind": "classProperty"
19
                },
20
                "formats": [
21
                  "camelCase",
22
                  "CONSTANT_CASE"
23
                ]
24
              }
25
            ]
26
          }
27
        }
28
      }
29
    }
30
  }
31
}

If only match is set and the regular expression has no capturing groups, then match is checked against the name of the declaration directly. In the following configuration, all variable names must have a minimum of 3 characters and a maximum of 20 characters.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "variable"
11
                },
12
                "match": ".{3,20}"
13
              }
14
            ]
15
          }
16
        }
17
      }
18
    }
19
  }
20
}

If both match and formats are set, then formats is checked against the first capture of the regular expression. Only the first capture is tested. Other captures are ignored. If nothing is captured, then formats is ignored.

In the following example, we require that:

A private property starts with _ and consists of at least two characters.
The captured name (the name without the leading _) is in camelCase.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember",
11
                  "modifiers": [
12
                    "private"
13
                  ]
14
                },
15
                "match": "_(.+)",
16
                "formats": [
17
                  "camelCase"
18
                ]
19
              }
20
            ]
21
          }
22
        }
23
      }
24
    }
25
  }
26
}

If match is set and formats is unset, then the part of the name captured by the regular expression is forwarded to the next conventions of the array that selects the declaration. The following configuration has exactly the same effect as the previous one. The first convention applies to any private class member name. It stipulates that the name must have a leading underscore. The regular expression captures the part of the name without the leading underscore. Because formats is not set, the capture is forwarded to the next convention that applies to a private class member name. In our case, the next convention applies. The capture is then checked against formats.

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember",
11
                  "modifiers": [
12
                    "private"
13
                  ]
14
                },
15
                "match": "_(.+)"
16
                // We don't need to specify `formats` because the capture is forwarded to the next conventions.
17
              },
18
              {
19
                "selector": {
20
                  "kind": "classMember",
21
                  "modifiers": [
22
                    "private"
23
                  ]
24
                },
25
                "formats": [
26
                  "camelCase"
27
                ]
28
              }
29
            ]
30
          }
31
        }
32
      }
33
    }
34
  }
35
}

The forwarding has particularly useful to factorize some conventions. For example, the following configuration…

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember",
11
                  "modifiers": [
12
                    "private"
13
                  ]
14
                },
15
                "match": "_(.+)",
16
                "formats": [
17
                  "camelCase"
18
                ]
19
              },
20
              {
21
                "selector": {
22
                  "kind": "classMember"
23
                },
24
                "formats": [
25
                  "camelCase"
26
                ]
27
              }
28
            ]
29
          }
30
        }
31
      }
32
    }
33
  }
34
}

can be factorized to…

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember",
11
                  "modifiers": [
12
                    "private"
13
                  ]
14
                },
15
                "match": "_(.+)"
16
              },
17
              {
18
                "selector": {
19
                  "kind": "classMember"
20
                },
21
                "formats": [
22
                  "camelCase"
23
                ]
24
              }
25
            ]
26
          }
27
        }
28
      }
29
    }
30
  }
31
}

If a declaration is not selected or if a capture is forwarded while there are no more conventions, then the declaration name is verified against the default conventions. Because the default conventions already ensure that class members are in [“camelCase”], the previous example can be simplified to:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "classMember",
11
                  "modifiers": [
12
                    "private"
13
                  ]
14
                },
15
                "match": "_(.+)"
16
                // We don't need to specify `formats` because the capture is forwarded to the next conventions.
17
              }
18
              // default conventions
19
            ]
20
          }
21
        }
22
      }
23
    }
24
  }
25
}

If the capture is identical to the initial name (it is not a part of the initial name), then, leading and trailing underscore and dollar signs are trimmed before being checked against default conventions. In the previous example, the capture is a part of the name because _ is not included in the capture, thus, no trimming is performed.

You can reset all default conventions by adding a convention at the end of the array that accepts anything:

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              // your conventions
9
              // ...
10

11
              // Otherwise, accept anything
12
              {
13
                "match": ".*"
14
              }
15
            ]
16
          }
17
        }
18
      }
19
    }
20
  }
21
}

Let’s take a more complex example with the following conventions:

A variable name is i, j, or follows the next selected convention (convention (2)).
An identifier contains at least two characters and follow the next selected convention (the default convention).
A private class member name starts with an underscore _ and the name without the underscore follows the next selected convention (convention (4) for some of them, and the default convention for others).
A static readonly class property name is in CONSTANT_CASE.
A global constant is in CONSTANT_CASE and can be enclosed by double underscores or to be named _SPECIAL_.
An interface name starts with I, except for interfaces ending with Error, and is in PascalCase.
All other names follow the default conventions

1
{
2
  "linter": {
3
    "rules": {
4
      "style": {
5
        "useNamingConvention": {
6
          "options": {
7
            "conventions": [
8
              {
9
                "selector": {
10
                  "kind": "variable"
11
                },
12
                "match": "[ij]|(.*)"
13
              },
14
              {
15
                "match": "(.{2,})"
16
              },
17
              {
18
                "selector": {
19
                  "kind": "classMember",
20
                  "modifiers": [
21
                    "private"
22
                  ]
23
                },
24
                "match": "_(.*)"
25
              },
26
              {
27
                "selector": {
28
                  "kind": "classProperty",
29
                  "modifiers": [
30
                    "static",
31
                    "readonly"
32
                  ]
33
                },
34
                "formats": [
35
                  "CONSTANT_CASE"
36
                ]
37
              },
38
              {
39
                "selector": {
40
                  "kind": "const",
41
                  "scope": "global"
42
                },
43
                "match": "__(.+)__|_SPECIAL_|(.+)",
44
                "formats": [
45
                  "CONSTANT_CASE"
46
                ]
47
              },
48
              {
49
                "selector": {
50
                  "kind": "interface"
51
                },
52
                "match": "I(.*)|(.*?)Error",
53
                "formats": [
54
                  "PascalCase"
55
                ]
56
              }
57
              // default conventions
58
            ]
59
          }
60
        }
61
      }
62
    }
63
  }
64
}

Hers some examples:

A private class property named _ is reported by the rule because it contains a single character. According to the second convention, the name should contain at least two characters.
A variable a_variable is reported by the rule because it doesn’t respect the default convention that forbid variable names in snake_case. The variable name is first verified against the first convention. It is forwarded to the second convention, which is also respected, because it is neither i nor j. The name is captured and is forwarded to the next convention. In our case, the next convention is the default one.

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 (?:)
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. Note that you can also escape special characters using character classes. For example, \$ and [$] are two valid patterns that escape $.