{"slug": "code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint", "title": "Code review shouldn't catch import rules: a React Native architecture ESLint enforces", "summary": "A developer building the React Native app Bareship encoded its five-layer architecture as ESLint and dependency-cruiser rules rather than documentation, so that imports flow only app → features → entities → data → shared and features never import each other. Additional rules, each traced to a real bug, flag hard-coded strings, non-mirroring left/right styles that break right-to-left layouts, and calls the React Compiler caches; every error message explains the fix and links the underlying decision record. In a deliberately broken settings screen, the setup surfaced three lint errors plus a dependency-cruiser violation that no test would have caught.", "body_md": "**Short answer:** Bareship writes its architecture down as lint errors instead of a wiki page. ESLint checks that imports go one way through five layers and that features never import each other, and dependency-cruiser checks the whole graph again in CI. Other rules each came from a real bug: hard-coded text, `left`/` right` styles that don't mirror in right-to-left languages, and calls the React Compiler caches. Every error message says how to fix it and links the decision behind it, so a teammate or an AI agent can fix the code without asking anyone.\n\nThis is Part 3 of Building Bareship. [Part 2](https://www.praveensingh.co.in/blog/bareship-offline-write-queue) covered the offline queue and\n\nended with a promise: an architecture the linter enforces.\n\nEvery React Native project starts with folders and good intentions. Someone draws the layers on a whiteboard,\n\neveryone agrees, and it holds for a few weeks. Then a settings screen borrows a hook from the feed because it's\n\nquicker, a string skips translation because it's \"temporary\", and the person who knew the rules is on leave. Code\n\nreview is supposed to catch this, but reviewers are looking at whether the feature works, not at import paths.\n\nSo in Bareship the rules are errors. They show up in the editor while you type, block the commit, and fail CI.\n\nHere's a small screen I wrote to break the rules on purpose. It sits in the settings feature, shows how many\n\npages of posts the feed has loaded, and adds a little margin:\n\n`src/features/settings/screens/ProfileCard.tsx`\n\n``` js\nimport { View } from 'react-native';\nimport { StyleSheet } from 'react-native-unistyles';\n\nimport { useFeed } from '@/features/feed/api';\nimport { Text } from '@/shared/ui/primitives/Text';\n\nexport function ProfileCard() {\n  const feed = useFeed();\n  return (\n    <View style={styles.card}>\n      <Text>Your posts: {feed.data?.pages.length}</Text>\n    </View>\n  );\n}\n\nconst styles = StyleSheet.create({ card: { marginLeft: 16 } });\n```\n\nIt type-checks and it runs. ESLint says no, three times:\n\n```\nsrc/features/settings/screens/ProfileCard.tsx\n   4:25  error  Layer rule broken. Imports go app → features → entities → data → shared,\n                and features never import each other (docs/decisions/0005)   boundaries/dependencies\n  11:13  error  disallow literal string: <Text>Your posts: {feed.data?.pages.length}</Text>\n                                                                              i18next/no-literal-string\n  16:44  error  Use start/end (marginStart, paddingEnd, start, borderStartWidth…) so the layout\n                mirrors in right-to-left languages (ADR 0017)                  no-restricted-syntax\n\n✖ 3 problems (3 errors, 0 warnings)\n```\n\nAnd dependency-cruiser, which CI runs over the whole import graph, catches the first one again:\n\n```\n  error features-are-isolated: src/features/settings/screens/ProfileCard.tsx → src/features/feed/api.ts\n\nx 1 dependency violations (1 errors, 0 warnings). 226 modules, 722 dependencies cruised.\n```\n\nNone of these would have broken a test. Each one costs real time later: the settings feature now breaks when the\n\nfeed changes, the text can't be translated, and the margin is on the wrong side in Arabic or Urdu.\n\nThe code in `src/` is split into five layers, and imports only go down:\n\n| Layer | Holds | May import | \n|---|---|---|\n| `app` | Navigation, boot, providers | everything below | \n| `features` | One folder per feature: screens, hooks, API calls | `entities` ,`data` ,`shared` , and only itself | \n| `entities` | Domain models more than one feature needs, such as the session and the user | `data` ,`shared` | \n| `data` | The query client, the offline queue, storage | `shared` | \n| `shared` | UI primitives, the HTTP client, i18n, config | `shared` | \n\nThe rule that matters most is the one in the middle row: **a feature never imports another feature**. If the\n\nsettings screen needs the feed's data, that's a sign the shared part belongs lower down, in `entities` or `shared`.\n\nThen you can delete or rewrite the feed without touching settings, which is also how `pnpm strip-examples` can\n\nremove the whole demo with one command.\n\n[eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries) enforces this in the editor.\n\nThe whole policy is generated from one list, so the order of the layers is written down exactly once:\n\n`eslint.config.mjs`\n\n``` js\nconst LAYERS = ['app', 'features', 'entities', 'data', 'shared'];\n\n'boundaries/dependencies': ['error', {\n  default: 'disallow',\n  message:\n    'Layer rule broken. Imports go app → features → entities → data → shared, and features never import each other (docs/decisions/0005).',\n  policies: LAYERS.map((layer, i) => ({\n    from: { element: { type: layer } },\n    allow: [\n      // Every layer below this one.\n      ...LAYERS.slice(i + 1).map(type => ({ to: { element: { type } } })),\n      // Within the same layer: a feature only into itself; other layers freely.\n      layer === 'features'\n        ? { to: { element: { type: 'features', captured: { feature: '{{ from.element.captured.feature }}' } } } }\n        : { to: { element: { type: layer } } },\n    ],\n  })),\n}],\n```\n\nTwo more import rules sit on top. `app` may use a feature only through its `index.ts`, its public API, and never\n\nreach into its files. And nobody imports a folder's `index.ts` barrel inside the layers: barrels caused require\n\ncycles and loaded more than a screen needed. Removing them touched 29 files, and the Android release bundle went\n\nfrom 3,831 to 3,824 KB.\n\n[dependency-cruiser](https://github.com/sverweij/dependency-cruiser) checks the same layer rules a second time, over\n\nthe whole graph at once. It also catches what a per-file linter can't see: import cycles across many files, and app\n\ncode that imports a dev dependency, such as a test or mock tool that should never ship in the app.\n\nThe layer rules came from a plan. Most of the others came from something that went wrong, and I added the rule so\n\nit couldn't happen twice:\n\n| Rule | The bug behind it | \n|---|---|\n| No `formatRelative(date)` or`formatDate(…)` directly in JSX | After switching to Hindi, \"2 days ago\" stayed in English. The React Compiler had cached the call, which didn't know the language changed. Components use `useFormat()` instead. | \n| No `left` /`right` ,`marginLeft` ,`paddingRight` and friends in styles | Physical sides don't flip in right-to-left languages; `start` /`end` do. | \n| No `textAlign: 'left'` or`'right'` | On iOS, text in a mirrored row stayed on the left ( [#21](https://github.com/psingh2907/bareship/pull/21) ). | \n| No `useVariants` from Unistyles | The React Compiler memoized the style array without knowing the variant changed, so the old one stayed on screen: a focus border that never cleared. A style function, `styles.field(state)` , stays correct. | \n| No icons from the `lucide-react-native` root | Metro can't tree-shake, so a root import bundles every icon. Icons come from one module each. | \n| ARIA props only ( `role` ,`aria-label` …), not`accessibilityRole` and friends | One way to write it, which is also what agents that read the screen as text understand. | \n| No hard-coded text in JSX | Every word goes through `t('…')` , so a new language is a new file, not a hunt through screens. | \n\nOn top of these, the 15 React Compiler rules from `eslint-plugin-react-hooks` are all errors, not warnings.\n\nMost of the table needs no plugin. ESLint's built-in `no-restricted-syntax` takes an AST selector and a message,\n\nwhich is enough for a lot of house rules:\n\n```\n// Physical sides don't flip in right-to-left languages; start/end do (ADR 0017).\n{\n  selector:\n    'Property[key.name=/^(left|right|(margin|padding)(Left|Right)|border(Top|Bottom)?(Left|Right)(Width|Color|Radius)?)$/]',\n  message:\n    'Use start/end (marginStart, paddingEnd, start, borderStartWidth…) so the layout mirrors in right-to-left languages (ADR 0017).',\n},\n```\n\nIf you only take one idea from this post, take this one: when a bug comes from a pattern, a ten-line lint rule\n\nstops the whole class of bug, in every file, for every future developer.\n\nLook at the messages again. None of them just says \"not allowed\". Each one says what to do instead, and most\n\nname the decision record that explains why: `docs/decisions/0005`, `ADR 0017`, `AGENTS.md › Styling`.\n\nThat matters for people: a new teammate fixes the code from the message, without asking anyone or opening a wiki.\n\nIt matters even more for AI coding agents. I built much of Bareship with Claude Code, and an agent reads a lint\n\nerror far more reliably than it remembers a paragraph of guidelines. `AGENTS.md` has one line about these rules:\n\n\"Fix the import, never disable the rule.\" When the agent broke a rule, the fix went into the linter or its\n\nmessage, not into a comment on a pull request. The next agent, or the next person, then gets the right answer from\n\nthe tool.\n\nThe same rules run in four places, from fastest to last line of defence:\n\n`eslint --fix --max-warnings=0` on the staged files.`pnpm check`` main`.\nThe first week with rules like these feels strict. A quick fix you'd normally push needs a moment's thought about\n\nwhere the code belongs. After that, nobody has to remember the rules, and review is about the feature again.\n\nThe rules also have to cover your own tools. The `formatRelative` rule arrived in 0.2, but the feature generator\n\nkept writing a list screen that called it. So in 0.4.0, `pnpm gen feature` produced code its own linter rejected.\n\nNothing ran the generators end to end, so nobody noticed until I tried one while writing a post. 0.4.1 fixed the\n\ntemplate and added `scripts/ci/check-generators.sh`, which runs every generator on a scratch copy and checks the\n\nresult for types, lint, formatting, boundaries and tests.\n\nAnd sometimes a rule is wrong for your app. Then you change it in one place, in `eslint.config.mjs`, and write\n\ndown why in a decision record next to the others. That's the point: a rule you disagree with is a conversation\n\nabout one line of config, not about whose turn it is to be strict in review.\n\n```\nnpx create-bareship Acme\ncd Acme\npnpm lint\n```\n\nPaste the `ProfileCard` above into `src/features/settings/screens/` and run `pnpm lint` again to see the three\n\nerrors. `pnpm depcruise` shows the graph check.\n\n`.dependency-cruiser.cjs`\n**Next in the series:** a package manager that refuses packages younger than three days, and the rest of\n\nBareship's supply-chain rules.\n\nIf one of these rules would get in your way, or you have one I should add, leave a comment on dev.to or open an\n\nissue.\n\nUse `eslint-plugin-boundaries` to define each folder as a layer and allow imports only to the layers below it,\n\nand run `dependency-cruiser` in CI to check the whole import graph, including cycles.\n\nGive each feature its own element in `eslint-plugin-boundaries`, captured by folder name, and allow imports within\n\nthe same feature only. Code two features need moves down to a shared layer.\n\nYes. `no-restricted-syntax` with a selector on style keys can reject `left`, `right`, `marginLeft` and similar,\n\nand suggest `start` and `end`, which mirror in right-to-left languages.\n\n*I write about React Native in practice, measured and with public code, at [praveensingh.co.in/blog](https://www.praveensingh.co.in/blog).*", "url": "https://wpnews.pro/news/code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint", "canonical_source": "https://dev.to/praveensingh/code-review-shouldnt-catch-import-rules-a-react-native-architecture-eslint-enforces-827", "published_at": "2026-11-16 04:38:53+00:00", "updated_at": "2026-11-16 04:51:26.485535+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Bareship", "ESLint", "dependency-cruiser", "React Native", "React Compiler", "react-native-unistyles", "i18next"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint", "markdown": "https://wpnews.pro/news/code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint.md", "text": "https://wpnews.pro/news/code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint.txt", "jsonld": "https://wpnews.pro/news/code-review-shouldn-t-catch-import-rules-a-react-native-architecture-eslint.jsonld"}}