{
  "name": "resources/wrapping-the-library",
  "title": "Wrapping the Library",
  "description": "How to build your own wrapper library on top of eurodata-ui without registration conflicts.",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/resources/wrapping-the-library/",
  "sections": [
    {
      "heading": "Wrapping the Library",
      "markdown": "If you publish an internal library that re-exports eurodata-ui components — typically a thin React/Vue wrapper that adds in-house defaults or extra props — there are a few packaging steps that matter for downstream apps. They prevent the same `ed-*` custom element from being registered twice in the consuming app."
    },
    {
      "heading": "Mark eurodata-ui as a peer dependency",
      "markdown": "In your wrapper library's `package.json`, list `@eurodata/eurodata-ui` under `peerDependencies` instead of `dependencies`. The app that installs your wrapper is expected to bring its own copy.\n\n```json\n{\n  \"peerDependencies\": {\n    \"@eurodata/eurodata-ui\": \"^0.30.1\"\n  }\n}\n```\n\nThis signals package managers to hoist a single shared copy when the app installs both you and eurodata-ui directly."
    },
    {
      "heading": "Externalize eurodata-ui from your bundle",
      "markdown": "Whatever bundler you use to publish your wrapper library, exclude `@eurodata/eurodata-ui` from the output. If you don't, every consumer pulls in a copy that's inlined into your bundle in addition to their own — two physical copies in their app, one registration conflict per shared tag.\n\n**Vite / Rollup:**\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { resolve } from 'node:path';\n\nexport default defineConfig({\n  build: {\n    lib: {\n      entry: resolve(__dirname, 'src/index.ts'),\n      formats: ['es']\n    },\n    rollupOptions: {\n      external: [/^@eurodata\\/eurodata-ui($|\\/)/, 'react', 'react-dom']\n    }\n  }\n});\n```\n\n**tsup:**\n\n```ts\n// tsup.config.ts\nimport { defineConfig } from 'tsup';\n\nexport default defineConfig({\n  entry: ['src/index.ts'],\n  format: 'esm',\n  external: ['@eurodata/eurodata-ui']\n});\n```\n\n**webpack:** add `@eurodata/eurodata-ui` (and any `@eurodata/eurodata-ui/*` deep imports your wrapper uses) to `externals`."
    },
    {
      "heading": "Dedupe in the consuming app",
      "markdown": "Even with the steps above, an app's bundler can still resolve two physical copies of eurodata-ui when version ranges don't deduplicate cleanly — for example, your wrapper pins `^0.10` and the app pins `^0.11`. Force deduplication in the app:\n\n**Vite:**\n\n```ts\n// vite.config.ts\nexport default {\n  resolve: {\n    dedupe: ['@eurodata/eurodata-ui']\n  },\n  optimizeDeps: {\n    include: ['@eurodata/eurodata-ui']\n  }\n};\n```\n\n**webpack:** use `resolve.alias` to pin `@eurodata/eurodata-ui` to a single path, or rely on the package-manager hoist.\n\n**pnpm:** the workspace's `.npmrc` can pin a single version with `public-hoist-pattern[]=@eurodata/eurodata-ui` or `dedupe-peer-dependents=true`."
    },
    {
      "heading": "What if a duplicate slips through anyway",
      "markdown": "eurodata-ui guards its `customElements.define` calls against being run twice in the same realm. A duplicate registration is safe — the first registration wins, the second is skipped without throwing. You will see a console warning when the duplicate carries a different version stamp:\n\n> `[eurodata-ui] Custom element \"ed-badge\" is already defined by another @eurodata/eurodata-ui copy at version 0.10.4 (this build is 0.11.0). Skipping duplicate registration.`\n\nTreat that warning as a packaging bug — same custom element name from two different library versions can drift in behavior, props, and styles. Walk back through the steps above.\n\nA warning that names a `non-eurodata-ui registration` instead means something outside eurodata-UI registered the tag first (a manual `customElements.define`, a copy of an older eurodata-UI release that predates the guard, or a third-party component using the same tag name)."
    }
  ]
}