[Due for payment 2026-09-22] Add ESLint rule to disallow OnyxUtils.get() / react-native-onyx/dist/OnyxUtils runtime imports

[tgolen]

Problem

OnyxUtils.get() — imported from the internal deep path react-native-onyx/dist/OnyxUtils — is not a sanctioned way to read Onyx data. The only two supported read APIs are useOnyx() (render path) and Onyx.connectWithoutView() (non-render logic). Reaching into react-native-onyx/dist/* bypasses the public API and couples us to Onyx internals.

Once the existing runtime usages are removed (see the linked issues below), we should add an ESLint rule so it can't be reintroduced in /App.

Scope of the ban

The rule should disallow the runtime import/use of react-native-onyx/dist/OnyxUtils.

Important: there is a legitimate type-only usage that must keep working — src/types/onyx/Request.ts does import type OnyxUtils from 'react-native-onyx/dist/OnyxUtils' and references OnyxUtils.METHOD as a type. The rule must therefore allow type imports.

Suggested implementation

The project uses flat config (eslint.config.mjs) and has a local-rules plugin (eslint-plugin-local-rules). The simplest approach is a no-restricted-imports entry with allowTypeImports: true:

'no-restricted-imports': ['error', {
    paths: [{
        name: 'react-native-onyx/dist/OnyxUtils',
        message: 'OnyxUtils is not a sanctioned way to read Onyx data. Use useOnyx() in render paths, or a short-lived Onyx.connectWithoutView() for non-render logic.',
        allowTypeImports: true,
    }],
}],

Notes for the implementer:

• If no-restricted-imports is already configured, merge this path into the existing entry rather than overriding it.
• If a member-level ban is preferred (e.g. allow other OnyxUtils members but ban .get), a custom rule in eslint-plugin-local-rules using no-restricted-syntax-style selectors is an alternative — but the import-path ban above is sufficient given .get is the only runtime member used today.

Dependency / ordering

This rule should land after the four removal issues, otherwise it will immediately error on existing code. The four call sites to remove first:

• [Due for payment 2026-08-25] Remove OnyxUtils.get() from backgroundLocationTrackingTask (use connectWithoutView) #98606 — backgroundLocationTrackingTask (connectWithoutView)
• [Due for payment 2026-09-10] Remove OnyxUtils.get() from OnyxDerived init (use connectWithoutView) #98607 — OnyxDerived init (connectWithoutView)
• [Due for payment 2026-09-03] Remove OnyxUtils.get() from useUpdateGpsTripOnReconnect (use useOnyx) #98608 — useUpdateGpsTripOnReconnect (useOnyx)
• [Due for payment 2026-08-27] Remove OnyxUtils.get() from GPSTripStateChecker (use useOnyx) #98609 — GPSTripStateChecker (useOnyx)

(Alternatively, if we want the rule in sooner, it could be added with an eslint-seatbelt baseline and the baseline entries removed as each file is fixed.)

Acceptance criteria

• Importing/using react-native-onyx/dist/OnyxUtils at runtime fails lint with a helpful message pointing to useOnyx / connectWithoutView.
• import type of OnyxUtils still passes (so src/types/onyx/Request.ts is unaffected).
• npm run lint passes on main once the four removal issues are merged.

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022087946426700653888
• Upwork Job ID: 2087946426700653888
• Last Price Increase: 2026-08-13

Issue Owner

Current Issue Owner: @mallenexpensify

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @linhvovan29546 (External)

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022087946426700653888

[tgolen]

Blocked by the four removal issues (all must merge before this rule can pass on main):

• [Due for payment 2026-08-25] Remove OnyxUtils.get() from backgroundLocationTrackingTask (use connectWithoutView) #98606 — backgroundLocationTrackingTask (connectWithoutView)
• [Due for payment 2026-09-10] Remove OnyxUtils.get() from OnyxDerived init (use connectWithoutView) #98607 — OnyxDerived init (connectWithoutView)
• [Due for payment 2026-09-03] Remove OnyxUtils.get() from useUpdateGpsTripOnReconnect (use useOnyx) #98608 — useUpdateGpsTripOnReconnect (useOnyx)
• [Due for payment 2026-08-27] Remove OnyxUtils.get() from GPSTripStateChecker (use useOnyx) #98609 — GPSTripStateChecker (useOnyx)

[skrohan5016-coder]

Proposal

Please re-state the problem that we are trying to solve in this issue.

After the four runtime OnyxUtils.get() call sites are removed, App should prevent any new runtime dependency on the internal react-native-onyx/dist/OnyxUtils module while preserving the one legitimate type-only import in src/types/onyx/Request.ts.

What is the root cause of that problem?

The codebase currently has no lint boundary around this deep import. The root flat config only re-exports config/eslint/eslint.config.mjs, and the real config already centralizes restricted module paths in restrictedImportPaths.

There is one important flat-config detail: no-restricted-imports is configured more than once. The TS/TSX block re-applies restrictedImportPaths because flat-config rules are last-wins, and the headless Victory renderer derives its own path list from the same array. Adding a standalone no-restricted-imports block or editing only the first rule occurrence would therefore be incomplete and could be silently overridden for TypeScript files.

The remaining valid usage is explicitly type-only:

import type OnyxUtils from 'react-native-onyx/dist/OnyxUtils';

Request.ts uses typeof OnyxUtils.METHOD.* only in type space. A blanket path ban without allowTypeImports would break that contract even though no runtime module is loaded.

What changes do you think we should make in order to solve the problem?

1. Add the restriction once to the shared restrictedImportPaths array in config/eslint/eslint.config.mjs:

{
    name: 'react-native-onyx/dist/OnyxUtils',
    message:
        'OnyxUtils is not a sanctioned way to read Onyx data. Use @hooks/useOnyx in render paths, or a short-lived Onyx.connectWithoutView() for non-render logic.',
    allowTypeImports: true,
},

Putting it in the shared array automatically carries it into:

• the main JS/TS lint config;
• the later TS/TSX no-restricted-imports override;
• the Victory renderer restriction list (which only filters the direct theme restriction).

Do not add a second independent no-restricted-imports rule object, because that risks replacing rather than extending existing paths/patterns.

2. Keep the restriction at the module-path level, not just on .get. The supported public API is exported from react-native-onyx; any runtime import from dist/OnyxUtils couples App to package internals even if a different member is used later.

3. Land this after [Due for payment 2026-08-25] Remove OnyxUtils.get() from backgroundLocationTrackingTask (use connectWithoutView) #98606, [Due for payment 2026-09-10] Remove OnyxUtils.get() from OnyxDerived init (use connectWithoutView) #98607, [Due for payment 2026-09-03] Remove OnyxUtils.get() from useUpdateGpsTripOnReconnect (use useOnyx) #98608, and [Due for payment 2026-08-27] Remove OnyxUtils.get() from GPSTripStateChecker (use useOnyx) #98609 are merged, as already noted by the issue owner. Before claiming the dependency is cleared, search both source and tests for executable imports/requires. Test mocks containing the path as a string do not necessarily violate the runtime-import rule, but any actual value import must be removed or migrated.

4. No seatbelt baseline should be needed when this lands in the intended order. Adding a baseline would weaken a new invariant and create cleanup work. Use a temporary seatbelt entry only if maintainers explicitly choose to merge the rule before all four removal PRs.

What specific scenarios should we cover in automated tests to prevent reintroducing this issue in the future?

Add a small config-level test using ESLint's lintText() against the real flat config (or the repository's preferred lint-config test harness) with three snippets:

1. Runtime default import fails:

import OnyxUtils from 'react-native-onyx/dist/OnyxUtils';

2. Runtime namespace/named access from the same path fails with the custom guidance message.
3. Type-only import passes:

import type OnyxUtils from 'react-native-onyx/dist/OnyxUtils';
type Method = typeof OnyxUtils.METHOD.SET;

Also run normal npm run lint after the four dependencies land to prove there are no grandfathered runtime imports.

The config test is valuable because this repository has multiple last-wins no-restricted-imports blocks; merely inspecting the shared array would not prove the final resolved TS configuration still enforces the rule.

What alternative solutions did you explore? (Optional)

• Ban only OnyxUtils.get with a custom AST rule: unnecessary and weaker; another runtime member from the same private module would still be allowed.
• Add a separate no-restricted-imports block: rejected because flat config replaces rule configuration rather than merging it and could discard existing restrictions.
• Ban the path without allowTypeImports: rejected because it breaks Request.ts's legitimate type contract.
• Merge immediately with seatbelt entries: possible, but inferior to landing after the four removal issues because it establishes the invariant with known debt from day one.

[tgolen]

Update

• I'm putting this on HOLD until the dependent issues are finished.

Next Steps

• @tgolen Remove the HOLD after all dependent issues are finished.

ETA

• It will probably take a week or two for those issues to be resolved.

[linhvovan29546]

Not overdue. The issue is still on hold.