Skip to main content

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 install --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:

eslint.config.mjs
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:

package.json
{
"scripts": {
"lint": "eslint ."
}
}
npm run lint

The module also exports ruleCoverage, which records each upstream rule's inclusion or exclusion and its Core contract.

Enabled checks​

RuleChecks
rules-of-hooksFixed hook order, loops, early returns, async functions and calls outside components or custom hooks
exhaustive-depsCaptured render values in explicit useEffect dependency arrays
component-hook-factoriesComponents, contexts and custom hooks constructed during rendering
static-componentsComponent definitions recreated during rendering
globalsAssignments and known mutations to shared values during rendering
immutabilityMutations to props and state, including known collection methods
purityKnown impure operations during rendering
set-state-in-renderUnconditional state setters or reducer dispatch during rendering
set-state-in-effectSynchronous state updates or reducer dispatch inside effects
error-boundariestry/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 ruleCore contract
refsCore supports render-time ref reads and latest-value writes
configCore uses its own compiler configuration
gatingReact Compiler gating does not control Core execution
incompatible-libraryReact's memoization compatibility list does not govern Core
preserve-manual-memoizationCore has no useMemo, useCallback or React memo pass
unsupported-syntaxReact Compiler syntax restrictions do not describe Core's compiler
use-memoCore 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.

Next steps​

  • Hooks — state, effects and runtime handles
  • State — ownership and render lifetimes
  • CLI — generate a project with the preset configured