Lint components and hooks
Use @bedrock-core/ui/eslint to check hook ordering, effect dependencies and render behavior in addon sources.
Install the tooling
Install the UI package and the development tools:
- npm
- yarn
- pnpm
npm install --save-dev eslint@^10.3.0 typescript-eslint@^8.59.2 eslint-plugin-react-hooks@7.1.1
yarn add --dev eslint@^10.3.0 typescript-eslint@^8.59.2 eslint-plugin-react-hooks@7.1.1
pnpm add --save-dev eslint@^10.3.0 typescript-eslint@^8.59.2 eslint-plugin-react-hooks@7.1.1
The UI meta package exposes the plugin as a separate Node.js entry point. Import it from eslint.config.mjs; component files import from @bedrock-core/ui. ESLint and eslint-plugin-react-hooks are optional tooling peers, so a runtime-only install does not require them. Keep the upstream plugin pinned to 7.1.1, whose diagnostics the Core adapter supports.
The CLI's full starter includes the dependencies and configuration. Its script and resource presets use the shared lint configuration without UI tooling.
Configure ESLint
The recommended preset registers the core-hooks plugin and enables its ten applicable rules as errors. Combine it with TypeScript's parser and recommended checks:
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';
import coreHooks from '@bedrock-core/ui/eslint';
export default defineConfig([
{
ignores: ['node_modules/**', 'build/**', '.bedrock-core/**', '**/*.generated.*'],
},
...tseslint.configs.recommended,
coreHooks.configs.recommended,
]);
The preset applies to JavaScript and TypeScript files. Add it to the existing flat configuration alongside JSON, Minecraft and formatting checks. The full starter includes it directly in eslint.config.mjs.
Add a project command:
{
"scripts": {
"lint": "eslint ."
}
}
- npm
- yarn
- pnpm
npm run lint
yarn lint
pnpm lint
The module also exports ruleCoverage, which records each upstream rule's inclusion or exclusion and its Core contract.
Enabled checks
| Rule | Checks |
|---|---|
rules-of-hooks | Fixed hook order, loops, early returns, async functions and calls outside components or custom hooks |
exhaustive-deps | Captured render values in explicit useEffect dependency arrays |
component-hook-factories | Components, contexts and custom hooks constructed during rendering |
static-components | Component definitions recreated during rendering |
globals | Assignments and known mutations to shared values during rendering |
immutability | Mutations to props and state, including known collection methods |
purity | Known impure operations during rendering |
set-state-in-render | Unconditional state setters or reducer dispatch during rendering |
set-state-in-effect | Synchronous state updates or reducer dispatch inside effects |
error-boundaries | try/catch around child JSX construction, which does not execute the child |
Names use the core-hooks/ prefix in ESLint configuration and diagnostics. Named hook imports, import aliases and namespace imports from Core packages are recognized.
Write stable hook calls
Components use PascalCase names. Custom hooks start with use followed by a capital letter. Call hooks at the top level of the component or hook, before conditional returns:
import { Button, Text, useState } from '@bedrock-core/ui';
export function Counter(): JSX.Element {
const [count, setCount] = useState(0);
return (
<Button onPress={() => setCount(previous => previous + 1)}>
<Text>{String(count)}</Text>
</Button>
);
}
Prepare components, contexts and navigation factories outside render. A module-level createContext() or createStaticNavigation() is valid. Core compilation metadata uses function identity, so define a child component once and pass changing values through props.
Declare effect dependencies
Explicit dependency arrays must be literal arrays of identifiers or static property paths. Include captured render values. An effect without an array runs after every render and does not need a capture list.
import { useEffect } from '@bedrock-core/ui';
export function useConnection(source: { connect(): () => void }): void {
useEffect(() => source.connect(), [source]);
}
useRef and useRenderOwner return stable handles. State setters and reducer dispatch functions keep the same identity for each mounted component instance. The dependency rule requires captured setters and dispatch functions in explicit dependency arrays. Create a fresh state value rather than mutating a state object or collection.
useEvent includes its signal, callback and options in subscription dependencies. Its optional array supplies additional triggers. useFocusEffect tracks callback identity and has no authored dependency array. Neither is treated as an effect with an empty dependency list.
Run impure work and updates from event handlers, subscriptions or effects where appropriate. Derive values during render when they can be computed directly. Catch child rendering failures around the render transaction or host operation; constructing JSX inside try/catch does not catch a later child render.
Core-specific coverage
These decisions account for the remaining checks in the upstream recommended rules:
| Excluded rule | Core contract |
|---|---|
refs | Core supports render-time ref reads and latest-value writes |
config | Core uses its own compiler configuration |
gating | React Compiler gating does not control Core execution |
incompatible-library | React's memoization compatibility list does not govern Core |
preserve-manual-memoization | Core has no useMemo, useCallback or React memo pass |
unsupported-syntax | React Compiler syntax restrictions do not describe Core's compiler |
use-memo | Core does not export useMemo |
For a framework invariant that the analyzer cannot prove, suppress only the relevant statement and explain why the rule's contract is still satisfied. Avoid file-wide suppressions.
Limits
Static analysis does not establish native-client behavior. Dynamic property access, hook re-exports through unregistered modules, arbitrary factory indirection and helper-mediated side effects can escape analysis. Compiler-backed checks retain upstream analysis limits and bailouts. The adapter reports source locations without automatic edits.