{"record":{"id":"030d3c1ae808448b","repo":"halo-dev/halo","slug":"unsupported-shared-dependency-subpath-specifier","errorCode":null,"errorMessage":"Unsupported shared dependency subpath ${specifier} imported by ${sourceId}. Import the ${deepRoot} package root or select IIFE output.","messagePattern":"Unsupported shared dependency subpath (.+?) imported by (.+?)\\. Import the (.+?) package root or select IIFE output\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ui/packages/ui-plugin-bundler-kit/src/shared-dependencies.ts","lineNumber":52,"sourceCode":"  >();\n\n  constructor(options: SharedDependencyValidatorOptions) {\n    this.#snapshot = options.snapshot;\n    this.#providerRoot = path.resolve(options.providerRoot);\n  }\n\n  async validateSource(code: string, sourceId: string) {\n    for (const specifier of parseImports(code)) {\n      await this.validateImport(specifier, sourceId);\n    }\n  }\n\n  async validateImport(specifier: string, sourceId: string) {\n    const deepRoot = SHARED_PACKAGE_ROOTS.find((root) =>\n      specifier.startsWith(`${root}/`)\n    );\n    if (deepRoot) {\n      throw new Error(\n        `Unsupported shared dependency subpath ${specifier} imported by ${sourceId}. ` +\n          `Import the ${deepRoot} package root or select IIFE output.`\n      );\n    }\n    if (!isSharedPackageRoot(specifier)) {\n      return false;\n    }\n\n    await this.validateResolvedRoot(specifier, sourceId);\n    return true;\n  }\n\n  getValidatedRoots() {\n    return [...this.#validatedRoots];\n  }\n\n  getBuildReport(): SharedDependencyBuildReport {\n    const roots = SHARED_PACKAGE_ROOTS.filter((root) =>","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/halo-dev/halo/blob/d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8/ui/packages/ui-plugin-bundler-kit/src/shared-dependencies.ts#L34-L70","documentation":"Thrown by SharedDependencyValidator.validateImport when a source module imports a shared dependency via a deep subpath (e.g. 'vue/dist/vue.runtime.esm-bundler.js', '@halo-dev/components/Foo'). ESM provider output externalizes only the package root so the host can supply one shared copy; a subpath import cannot be mapped to the host's externalized global, so the build rejects it to avoid shipping a duplicate or a broken reference.","triggerScenarios":"A plugin source file contains `import x from 'vue/...'`, `import '@halo-dev/components/...'`, or any specifier starting with one of SHARED_PACKAGE_ROOTS followed by '/'. Fires during the transform hook (per-module) of the halo:esm-ui-provider Vite plugin.","commonSituations":"Copying a snippet that imports 'vue/jsx-runtime' or a deep CSS path; a library re-export that resolves to a subpath; using 'axios/' internals; importing a specific subpath for tree-shaking that worked under IIFE but breaks under ESM.","solutions":["Replace the deep import with the package root import: `import { x } from 'vue'` instead of `import { x } from 'vue/dist/...'`.","If you genuinely need the subpath, switch the build to IIFE output (format: 'iife').","Audit the offending sourceId named in the message and grep its import statements for any of the 10 shared roots followed by '/'."],"exampleFix":"// before\nimport { nextTick } from \"vue/dist/vue.runtime.esm-bundler.js\";\n\n// after\nimport { nextTick } from \"vue\";","handlingStrategy":"validation","validationCode":"import { SHARED_PACKAGE_ROOTS } from \"@halo-dev/ui-plugin-bundler-kit/runtime-snapshot\";\nfunction assertNoSharedSubpath(specifier: string, sourceId: string) {\n  const deep = SHARED_PACKAGE_ROOTS.find((r) => specifier.startsWith(`${r}/`));\n  if (deep) {\n    throw new Error(`${sourceId}: import ${specifier} — import the ${deep} root, not a subpath.`);\n  }\n}","typeGuard":"import { SHARED_PACKAGE_ROOTS } from \"@halo-dev/ui-plugin-bundler-kit/runtime-snapshot\";\nfunction isSharedRootImport(specifier: string): boolean {\n  return SHARED_PACKAGE_ROOTS.some((r) => specifier === r) ||\n    !SHARED_PACKAGE_ROOTS.some((r) => specifier.startsWith(`${r}/`));\n}","tryCatchPattern":null,"preventionTips":["Lint plugin source for `from \"(vue|@halo-dev/...)/` patterns and fail the PR.","Always import shared packages by their root entry only.","Use IIFE output if a dependency forces subpath imports you cannot change."],"tags":["build","esm","import","shared-dependency","bundler-kit"],"backgroundTag":null,"analyzedSha":"d2f5165f9c8f055ffcb3fa9c3f4032821a7b68c8","analyzedAt":"2026-08-14T00:18:38.915Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}