OceanBase Lint Standards

English | 中文

- Quick Start
- ESLint Configuration
- Stylelint Configuration
- Design Token Plugin

Quick Start

$3

Use the interactive command to configure ESLint or Oxlint:

``bash
npx @oceanbase/lint-config setup-lint
`

This will guide you to:
1. Choose ESLint, Oxlint, or both
2. Select project type (TypeScript, React)
3. Select features (Prettier, Import rules, etc.)
4. Generate config files
5. Install dependencies
6. Add npm scripts

See bin/README.md for details.

$3

#### Install

`bash
npm i --save-dev eslint prettier stylelint @oceanbase/lint-config stylelint-config-recommended-less stylelint-config-standard stylelint-less
`

#### Requirements

- ESLint v9.5.0+
- Node.js (^18.18.0, ^20.9.0, or >=21.1.0)

ESLint

$3

- eslint-plugin-import
- eslint-plugin-react
- eslint-plugin-react-hooks
- eslint-plugin-prettier

$3

Create an eslint.config.mjs file in your project root:

`js
// eslint.config.mjs
import { OBEslintCfg } from '@oceanbase/lint-config'

export default OBEslintCfg()
`

$3

`json
{
"scripts": {
"lint": "eslint .",
"lint:fix": "eslint . --fix"
}
}
`

$3

Add the following to package.json to run lint and auto-fix on each commit:

`bash
npm i --save-dev lint-staged husky
`

`json
{
"scripts": {
"prepare": "husky install"
},
"lint-staged": {
"./src/*/.{js,jsx,ts,tsx}": [
"npx prettier --write",
"npm run lint:fix"
]
}
}
`

$3

`js
// eslint.config.js
import OBEslintCfg from '@oceanbase/lint-config'

export default OBEslintCfg({
// Default plugins; set to false to disable
typescript: true,
prettier: true,
import: true,
react: true,
// .eslintignore is not used in flat config; configure ignores here
ignores: [
'**/fixtures'
// ...globs
]
})
`

OBEslintCfg also accepts any number of custom config overrides:

`js
// eslint.config.js
import OBEslintCfg from '@oceanbase/lint-config'

export default OBEslintCfg(
{
// OBEslintCfg options
},
// From the second argument onward, use ESLint Flat Configs
{
ignores: ['**/test'],
files: ['*/.ts'],
rules: {
'no-unused-vars': ['error', { varsIgnorePattern: '^_' }]
}
},
{
rules: {}
}
)
`

$3

Rules are scoped per module and can be overridden in the first argument or in later config objects:

`js
// eslint.config.js
import OBEslintCfg from '@oceanbase/lint-config'

export default OBEslintCfg(
{
typescript: {
overrides: {
'@typescript-eslint/no-unused-vars': 'off'
}
}
},
{
files: ['*/.vue'],
rules: {
'vue/operator-linebreak': ['error', 'before']
}
}
)
`

$3

You can enable type-aware rules by setting tsconfigPath:

> [!NOTE]
> Type-aware rules are stricter; enable based on your project needs. They may also affect performance depending on repository size.

`js
import OBEslintCfg from '@oceanbase/lint-config'

export default OBEslintCfg({
typescript: {
tsconfigPath: 'tsconfig.json'
}
})
`

$3

1. Add rules under src/rules
2. Add them to a config under src/configs
3. Expose options in src/factory.ts if needed

$3

From the project root:

`bash
npx @eslint/config-inspector
`

$3

Stylelint

$3

- stylelint-config-recommended-less
- stylelint-config-standard

$3

Create a .stylelintrc.mjs file in your project root:

`js
// .stylelintrc.mjs
import { OBStylelintCfg } from '@oceanbase/lint-config'

export default OBStylelintCfg()
`

$3

`json
{
"scripts": {
"lint:css": "stylelint '*/.{less,css}'",
"lint:fix:css": "stylelint '*/.{less,css}' --fix"
}
}
`

$3

Add to package.json to run stylelint on commit:

`json
{
"scripts": {
"prepare": "husky install"
},
"lint-staged": {
"./src/*/.{less,css}": [
"npx stylelint --fix"
]
}
}
`

$3

You can add custom plugins via extends and override rules via overrides:

`js
// .stylelintrc.mjs
import { OBStylelintCfg } from '@oceanbase/lint-config'

export default OBStylelintCfg({
extends: ['some-plugin'],
overrides: {
'selector-class-pattern': null
}
})
`

$3

The built-in Design Token plugin (rule: ob/use-design-tokens) checks style files for hardcoded colors, dimensions, etc., and can replace them with design tokens (e.g. CSS variables) so styles stay aligned with your design system.

#### Overview

| Feature | Description |
|--------|-------------|
| Detect & replace | Finds hardcoded colors (hex/rgb/rgba), dimensions, radius, shadow, etc., and replaces with configured tokens |
| Default tokens | OceanBase UI design tokens are included; you can enable them or use only your own |
| Auto-fix | stylelint --fix rewrites replaceable values to tokens |
| Warnings | Optional warnings for values that don’t match any token |

#### Enabling

Turn on designTokens.enabled in OBStylelintCfg and configure as needed:

`js
// .stylelintrc.mjs
import { OBStylelintCfg } from '@oceanbase/lint-config/stylelint'

export default OBStylelintCfg({
designTokens: {
enabled: true,
// Merge built-in OceanBase UI tokens, default true
useDefaultOBUIToken: true,
// Custom token map (merged with defaults, same key overrides)
tokens: {
'--my-border': '#cdd5e4',
'--my-primary': '#0d6cf2'
},
// Output as CSS variables, default true
useCSSVariable: true,
// CSS variable prefix, e.g. 'ob' → var(--ob-xxx)
cssVariablePrefix: 'ob',
ignoreProperties: [],
ignoreValues: [],
disableFix: false,
enableWarningForNonTokenValues: true
}
})
`

To use only your own tokens (no built-in OceanBase UI set):

`js
export default OBStylelintCfg({
designTokens: {
enabled: true,
useDefaultOBUIToken: false,
tokens: {
colorBorder: '#cdd5e4',
colorPrimary: '#0d6cf2'
},
useCSSVariable: true,
cssVariablePrefix: 'my'
}
})
`

#### Using the Plugin Standalone

If you only use Stylelint and want to use the Design Token plugin on its own, import the rule and example tokens from @oceanbase/lint-config/stylelint:

`js
// .stylelintrc.mjs
import { useDesignTokens, exampleDesignTokens } from '@oceanbase/lint-config/stylelint'

export default {
plugins: [useDesignTokens],
rules: {
'ob/use-design-tokens': [
true,
{
tokens: exampleDesignTokens, // or your own token object
useCSSVariable: true,
cssVariablePrefix: 'ob'
}
]
}
}
``

For more details, see Design Token Plugin (Monorepo).