src/content/docs/linter/rules/use-naming-convention.mdx
import { Tabs, TabItem } from '@astrojs/starlight/components';
<Tabs> <TabItem label="TypeScript and TSX" icon="seti:typescript"> ## Summary - Rule available since: `v1.0.0` - Diagnostic Category: [`lint/style/useNamingConvention`](/reference/diagnostics#diagnostic-category) - This rule isn't recommended, so you need to enable it. - This rule has a [**safe**](/linter/#safe-fixes) fix. - The default severity of this rule is [**information**](/reference/diagnostics#information). - Sources: - Inspired from [`@typescript-eslint/naming-convention`](https://typescript-eslint.io/rules/naming-convention){
"linter": {
"rules": {
"style": {
"useNamingConvention": "error"
}
}
}
}
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.
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.
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;
const fooYPosition = 0;
function f(FIRST_PARAM) {}
function name is in camelCase or PascalCase.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() { /*...*/ }
enum namesA 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,
}
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() {}
}
type aliases and interfaceA 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 };
camelCase.const alice = {
fullName: "Alice",
}
Example of an incorrect name:
const alice = {
full_name: "Alice",
}
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";
A TypeScript type parameter name is in PascalCase.
function id<Val>(value: Val): Val { /* ... */}
namespace namesA TypeScript namespace name is in camelCase or in PascalCase.
namespace mathExtra {
/*...*/
}
namespace MathExtra {
/*...*/
}
Note that some declarations are always ignored. You cannot apply a convention to them. This is the case for:
class C {
["not an identifier"]() {}
}
import { an_IMPORT } from "mod"
const { destructed_PROP } = obj;
override:class C extends B {
override overridden_METHOD() {}
}
declare module "myExternalModule" {
export interface my_INTERFACE {}
}
declare global {
interface HTMLElement {}
}
The rule provides several options that are detailed in the following subsections.
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"strictCase": false,
"requireAscii": false,
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)",
"formats": [
"camelCase"
]
}
]
}
}
}
}
}
}
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:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"strictCase": true
}
}
}
}
}
}
class HTTPServer {
}
When strictCase is set to false, consecutive uppercase characters are allowed.
For example, HTTPServer and aHTTPServer would be considered valid then:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"strictCase": false
}
}
}
}
}
}
class HTTPServer {
}
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
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:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"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
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
constletvarusingfunctionParameter
catchParameter
indexParameter: parameters of index signatures
typeParameter: generic type parameter
classMember: class properties, parameter properties, methods, getters, and setters
classProperty: class properties, including parameter propertiesclassMethodclassGetterclassSetterobjectLiteralMember: literal object properties, methods, getters, and setters (you might want to duplicate the convention for typeMember)
objectLiteralPropertyobjectLiteralMethodobjectLiteralGetterobjectLiteralSettertypeMember: properties, methods, getters, and setters declared in type aliases and interfaces
typePropertytypeMethodtypeGettertypeSettermodifiers: an array of modifiers among:
abstract: applies to class members and classesprivate: applies to class membersprotected: applies to class membersreadonly: applies to class members and type membersstatic: applies to class membersscope: 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.
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classProperty",
"modifiers": [
"static",
"readonly"
]
},
"formats": [
"CONSTANT_CASE"
]
}
]
}
}
}
}
}
}
The following code is then reported by the rule:
class C {
static readonly prop = 0;
}
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.
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember"
},
"formats": [
"camelCase"
]
},
{
"selector": {
"kind": "classProperty"
},
"formats": [
"camelCase",
"CONSTANT_CASE"
]
}
]
}
}
}
}
}
}
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.
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "variable"
},
"match": ".{3,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:
_ and consists of at least two characters._) is in camelCase.{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)",
"formats": [
"camelCase"
]
}
]
}
}
}
}
}
}
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.
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)"
// We don't need to specify `formats` because the capture is forwarded to the next conventions.
},
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"formats": [
"camelCase"
]
}
]
}
}
}
}
}
}
The forwarding has particularly useful to factorize some conventions. For example, the following configuration...
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)",
"formats": [
"camelCase"
]
},
{
"selector": {
"kind": "classMember"
},
"formats": [
"camelCase"
]
}
]
}
}
}
}
}
}
can be factorized to...
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)"
},
{
"selector": {
"kind": "classMember"
},
"formats": [
"camelCase"
]
}
]
}
}
}
}
}
}
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:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.+)"
// We don't need to specify `formats` because the capture is forwarded to the next conventions.
}
// default conventions
]
}
}
}
}
}
}
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:
{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
// your conventions
// ...
// Otherwise, accept anything
{
"match": ".*"
}
]
}
}
}
}
}
}
Let's take a more complex example with the following conventions:
i, j, or follows the next selected convention (convention (2)).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).static readonly class property name is in CONSTANT_CASE.CONSTANT_CASE and can be enclosed by double underscores or to be named _SPECIAL_.I, except for interfaces ending with Error, and is in PascalCase.{
"linter": {
"rules": {
"style": {
"useNamingConvention": {
"options": {
"conventions": [
{
"selector": {
"kind": "variable"
},
"match": "[ij]|(.*)"
},
{
"match": "(.{2,})"
},
{
"selector": {
"kind": "classMember",
"modifiers": [
"private"
]
},
"match": "_(.*)"
},
{
"selector": {
"kind": "classProperty",
"modifiers": [
"static",
"readonly"
]
},
"formats": [
"CONSTANT_CASE"
]
},
{
"selector": {
"kind": "const",
"scope": "global"
},
"match": "__(.+)__|_SPECIAL_|(.+)",
"formats": [
"CONSTANT_CASE"
]
},
{
"selector": {
"kind": "interface"
},
"match": "I(.*)|(.*?)Error",
"formats": [
"PascalCase"
]
}
// default conventions
]
}
}
}
}
}
}
Hers some examples:
_ 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 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.The match option takes a regular expression that supports the following syntaxes:
*, ?, +, {n}, {n,m}, {n,}, {m}*?, ??, +?, {n}?, {n,m}?, {n,}?, {m}?.[a-z], [xyz], [^a-z]|()(?:)(?i:) and case-sensitive groups (?-i:)\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 $.