{"record":{"id":"5242b9ccc6098532","repo":"expo/expo","slug":"the-expo-ui-package-needs-to-be-installed-in-or","errorCode":null,"errorMessage":"The '@expo/ui' package needs to be installed in order to use this feature.","messagePattern":"The '@expo/ui' package needs to be installed in order to use this feature\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/expo-router/src/optional-libraries/expo-ui.ts","lineNumber":18,"sourceCode":"type ExpoUI = typeof import('@expo/ui/jetpack-compose');\ntype ExpoUIModifiers = typeof import('@expo/ui/jetpack-compose/modifiers');\n\nlet expoUI: ExpoUI | undefined;\nlet modifiers: ExpoUIModifiers | undefined;\n\ntry {\n  const loadedExpoUI: ExpoUI = require('@expo/ui/jetpack-compose');\n  const loadedModifiers: ExpoUIModifiers = require('@expo/ui/jetpack-compose/modifiers');\n  expoUI = loadedExpoUI;\n  modifiers = loadedModifiers;\n} catch {}\n\nexport function requireExpoUI(\n  errorMessage = \"The '@expo/ui' package needs to be installed in order to use this feature.\"\n): { expoUI: ExpoUI; modifiers: ExpoUIModifiers } {\n  if (!expoUI || !modifiers) {\n    throw new Error(errorMessage);\n  }\n  return { expoUI, modifiers };\n}\n","sourceCodeStart":1,"sourceCodeEnd":22,"githubUrl":"https://github.com/expo/expo/blob/7da61120be99bcd9cc2e5dbdba6d803c21b5c68b/packages/expo-router/src/optional-libraries/expo-ui.ts#L1-L22","documentation":"expo-router's `@expo/ui` integration (Compose-style components like Icon, DropdownMenu, Box) is optional. `requireExpoUI` throws when `@expo/ui` (or its modifiers) isn't installed/resolvable, since the feature cannot work without it.","triggerScenarios":"Using expo-router APIs/components that render `@expo/ui` elements (Icon, IconButton, DropdownMenu, Box, RNHostView, etc.) without `@expo/ui` installed in the project.","commonSituations":"Upgrading expo-router to a version whose built-in UI now requires `@expo/ui`; copying sample screens using expo-ui components; dependency missing from a fresh install or monorepo hoisting failure.","solutions":["Install: `npx expo install @expo/ui`","Rebuild the native app / dev client so the new module is linked","If in a monorepo, ensure `@expo/ui` is resolvable from the app package (no nohoist/pruning issue)","Verify imports come from the correct optional-library module and version compatibility between expo-router and @expo/ui"],"exampleFix":"// before\nconst { expoUI: { Icon } } = requireExpoUI(); // throws\n// after\n// terminal: npx expo install @expo/ui, rebuild, then:\nconst { expoUI: { Icon } } = requireExpoUI();","handlingStrategy":"fallback","validationCode":"let expoUI = null; try { expoUI = require('@expo/ui'); } catch {}\nconst expoUIAvailable = !!expoUI;","typeGuard":"function hasExpoUI(): boolean { try { require.resolve('@expo/ui'); return true; } catch { return false; } }","tryCatchPattern":"try { const { expoUI, modifiers } = requireExpoUI(); renderComposeUI(expoUI, modifiers); } catch { renderFallbackRNView(); }","preventionTips":["Install @expo/ui whenever using expo-router UI components that depend on it","Rebuild native apps after adding native-dependent packages","Track expo-router release notes for newly required optional dependencies"],"tags":["expo-router","dependency","expo-ui"],"backgroundTag":"missing-optional-dependency","analyzedSha":"7da61120be99bcd9cc2e5dbdba6d803c21b5c68b","analyzedAt":"2026-09-09T16:01:44.845Z","contentChangedAt":"2026-09-09T16:01:44.845Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}