{"record":{"id":"641799a6d644a365","repo":"tailwindlabs/heroicons","slug":"importing-from-heroicons-react-directly-is-not","errorCode":null,"errorMessage":"Importing from `@heroicons/react` directly is not supported. Please import from either `@heroicons/react/16/solid`, `@heroicons/react/20/solid`, `@heroicons/react/24/solid`, or `@heroicons/react/24/outline` instead.","messagePattern":"Importing from `@heroicons/react` directly is not supported\\. Please import from either `@heroicons/react/16/solid`, `@heroicons/react/20/solid`, `@heroicons/react/24/solid`, or `@heroicons/react/24/outline` instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"react/index.esm.js","lineNumber":11,"sourceCode":"// The only reason this file exists is to appease Vite's optimizeDeps feature which requires a root-level import.\n\nexport default new Proxy(\n  {},\n  {\n    get: (_, property) => {\n      if (property === '__esModule') {\n        return {}\n      }\n\n      throw new Error(\n        `Importing from \\`@heroicons/react\\` directly is not supported. Please import from either \\`@heroicons/react/16/solid\\`, \\`@heroicons/react/20/solid\\`, \\`@heroicons/react/24/solid\\`, or \\`@heroicons/react/24/outline\\` instead.`\n      )\n    },\n  }\n)\n","sourceCodeStart":1,"sourceCodeEnd":17,"githubUrl":"https://github.com/tailwindlabs/heroicons/blob/616b7a4dbbf3d011760af8066262cd5c6b3868f3/react/index.esm.js#L1-L17","documentation":"Heroicons v2 no longer allows importing icons from the package root `@heroicons/react`. The root entry (both ESM and CJS builds) is a Proxy whose `get` trap throws for every property access except `__esModule`. Icons must be imported from one of the versioned/style subpaths: `@heroicons/react/16/solid`, `@heroicons/react/20/solid`, `@heroicons/react/24/solid`, or `@heroicons/react/24/outline`.","triggerScenarios":"Any statement like `import { BeakerIcon } from '@heroicons/react'` or `require('@heroicons/react')` followed by property access on the module. The throw happens the moment the bundler/runtime resolves a named export from the root entry, because the Proxy get trap throws for every property except `__esModule`.","commonSituations":"Upgrading from Heroicons v1 (where root imports like `@heroicons/react/solid` patterns or auto-import suggestions resolved from the root) to v2; IDE/editor auto-import snippets that still target the bare package name; copy-pasted tutorials written for v1; bundler alias or path-mapping configuration that rewrites subpath imports back to the package root.","solutions":["Rewrite imports to a versioned subpath, e.g. `import { BeakerIcon } from '@heroicons/react/24/outline'` (choose 16/20/24 size and solid/outline style).","Run a codemod or global find/replace: change `from '@heroicons/react'` to the appropriate subpath based on the icon size/style you want.","Check bundler/TS path aliases (tsconfig paths, webpack/vite aliases, jest moduleNameMapper) so `@heroicons/react/...` subpaths are not collapsed to the root entry.","Clear the bundler cache and reinstall node_modules if stale v1-style resolution persists."],"exampleFix":"// before\nimport { BeakerIcon } from '@heroicons/react'\n\n// after\nimport { BeakerIcon } from '@heroicons/react/24/outline'","handlingStrategy":"validation","validationCode":"// fail fast at build/boot time instead of at render\nimport * as heroicons from '@heroicons/react'\nif (heroicons && typeof heroicons === 'object' && !('BeakerIcon' in heroicons)) {\n  throw new Error(\"Do not import from '@heroicons/react'; use '@heroicons/react/24/outline' etc.\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use ESLint import/no-restricted-paths or no-restricted-imports to ban '@heroicons/react' root imports.","Configure editor auto-imports / snippets to suggest '@heroicons/react/<size>/<style>'.","Verify tsconfig/bundler aliases never collapse heroicons subpaths to the root.","When upgrading majors, run a codemod over all icon imports before merging."],"tags":["import","module-resolution","breaking-change","react"],"backgroundTag":"unsupported-root-import","analyzedSha":"616b7a4dbbf3d011760af8066262cd5c6b3868f3","analyzedAt":"2026-08-31T21:42:00.885Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}