Embeds
Purpose and Scope
Dub provides two public embed packages for teams that want to surface Dub referral-dashboard experiences inside third-party websites. The core package is the framework-neutral layer, described as the library that contains the core logic for embedding Dub's referral dashboard. The React package is the React-facing layer, described as a library of React components used to embed that same referral dashboard experience. Together, they let integration builders choose between a vanilla JavaScript foundation and a React component interface while staying aligned with Dub's broader product focus on partner programs, attribution, and link-driven growth.
Sources: packages/embeds/core/README.md, packages/embeds/react/README.md
The embed packages should be understood as integration packages rather than the main Dub application. They do not replace the REST API, analytics endpoints, or dashboard workflows; instead, they package client-side embed behavior so another site can host a Dub referral-dashboard surface. That distinction matters for architecture decisions. Server-side operations such as creating API keys, managing links, or retrieving analytics still belong to the API and dashboard surfaces, while the embed packages are the client integration layer that helps place a Dub-powered partner experience where end users already work.
Sources: packages/embeds/core/README.md, packages/embeds/react/README.md
Relevant Source Files
- packages/embeds/core/README.md — Introduces
@dub/embed-coreand states that it contains the core logic for embedding Dub's referral dashboard on third-party websites. - packages/embeds/core/package.json — Defines the core package name, description, published entry points, dependency on
@floating-ui/dom, package scripts, and public publish configuration. - packages/embeds/core/src/index.ts — Shows the core package public barrel exports for constants, core behavior, and types.
- packages/embeds/react/README.md — Introduces
@dub/embed-reactand states that it provides React components for embedding Dub's referral dashboard on third-party websites. - packages/embeds/react/package.json — Defines the React package name, description, entry points, React peer dependencies, dependency on
@dub/embed-core, package scripts, preview workflow, and public publish configuration.
Package Roles and Integration Model
The split between core and React packages is intentional. The core package has the package name @dub/embed-core and a description identifying it as a vanilla JavaScript core script for embedding Dub dashboards. Its public entry point re-exports constants, core behavior, and types, which indicates that consumers are expected to import a stable package-level API rather than reach into internal files. For non-React applications, custom wrappers, or future framework adapters, this package is the lowest-level integration surface shown in the repository evidence.
Sources: packages/embeds/core/package.json, packages/embeds/core/src/index.ts
The React package builds on that foundation rather than duplicating it. Its package metadata declares @dub/embed-core as a dependency and identifies the package as embed React components for Dub. That dependency relationship makes the React package the framework-specific interface over shared embed behavior. In practical terms, a React application should usually start with @dub/embed-react, while a framework-agnostic integration, a design-system wrapper, or a non-React site should evaluate @dub/embed-core first. This keeps shared logic centralized and leaves React-specific concerns in the React package.
Sources: packages/embeds/react/package.json, packages/embeds/core/package.json
The package metadata also shows how the published artifacts are intended to be consumed. Both packages expose main, module, and types entries under dist, and both publish only dist/** files. That means consumers should rely on the compiled package interface after publication, with type declarations available for TypeScript projects. Both packages set sideEffects to false, which is useful for bundlers that perform tree shaking, although integration builders should still verify behavior in their own build pipelines because embed code often interacts with the browser document and layout.
Sources: packages/embeds/core/package.json, packages/embeds/react/package.json
Installation and Consumption
The package READMEs present the installation flow in the same concise shape. Install the core package when you need the vanilla JavaScript embedding layer, and install the React package when your host application is React-based. Because the React package depends on the core package, React consumers normally do not need to import both directly unless they are building a custom abstraction that combines React components with lower-level core exports. The version shown for both packages is aligned at 0.0.18, which helps keep the wrapper and its underlying logic compatible.
Sources: packages/embeds/core/README.md, packages/embeds/react/README.md, packages/embeds/core/package.json, packages/embeds/react/package.json
pnpm i @dub/embed-core
pnpm i @dub/embed-reactThe React package declares react and react-dom as peer dependencies using the React 19 range. That is an important integration constraint: the host application supplies React, while the embed package supplies the Dub-specific components. This avoids bundling an extra React runtime into the embed package and follows common library packaging practice. If a site is not yet on a compatible React version, the core package may be the better starting point for a custom integration, or the site owner should validate compatibility before adopting the React components in production.
Sources: packages/embeds/react/package.json
API Surface and Build Contract
The most concrete source-level API contract available in the supplied evidence is the core barrel export. The package root exports from constants, core, and types. This is a useful signal for maintainers and consumers: public imports should come from the package boundary, not from private build output or internal source paths. Constants likely hold shared configuration values, types provide TypeScript contracts, and the core module represents the behavior layer. The page does not infer individual function names because the supplied evidence only exposes the barrel structure, but the package boundary itself is source-backed.
Sources: packages/embeds/core/src/index.ts
Both packages use tsup for builds, eslint for linting, and TypeScript's no-emit mode for type checking. The core package has build, lint, dev, and check-types scripts. The React package has the same basic lifecycle plus a Vite preview command and a prepublishOnly hook. That gives contributors a clear maintenance loop: run the development watcher while editing, lint the source, check types before publishing, and use the React preview workflow when validating component behavior in a browser-like application context.
Sources: packages/embeds/core/package.json, packages/embeds/react/package.json
The dependency lists also clarify implementation boundaries. The core package depends on @floating-ui/dom, which suggests that positioning or floating UI behavior is handled at the vanilla DOM layer. The React package depends on class-variance-authority, indicating component styling variants or class composition at the React layer, while also depending on @dub/embed-core for shared embed behavior. This division keeps DOM positioning concerns close to the browser integration layer and keeps React presentation concerns in the component package.
Sources: packages/embeds/core/package.json, packages/embeds/react/package.json
Developer Workflow and Publishing Signals
For contributors, the embed packages behave like first-class workspace packages. Each package has scripts for building, linting, watching during development, and checking types. The React package adds a preview command that runs Vite on port 3101 and opens the preview, which is the most direct source-backed signal for manually validating the React embed experience. Before changing the public interface, contributors should update the relevant README, confirm the package exports remain coherent, and make sure the compiled distribution still provides CommonJS, ESM, and type entry points.
Sources: packages/embeds/core/package.json, packages/embeds/react/package.json
The package metadata marks both embed packages with public publish configuration. That matters because these packages are meant to be consumed outside the monorepo, not only by Dub's own application code. Published package users will install from the registry, import through the declared package entry points, and rely on the bundled files under dist. Contributors should therefore treat package version alignment, peer dependency ranges, and generated type declarations as part of the user-facing contract, even when the implementation change appears small inside the source tree.
Sources: packages/embeds/core/package.json, packages/embeds/react/package.json
Choosing the Right Embed Package
Choose @dub/embed-react when the host site is a React application and the team wants a component-level integration. The React package is designed for that use case, declares React and React DOM as peers, and depends on the core package for shared logic. Choose @dub/embed-core when the host site is not React, when you are building an adapter for another framework, or when you need direct access to the lower-level constants, core behavior, and types exported by the package root. In both cases, keep privileged API keys on the server and treat frontend embed code as client-side integration code.
Sources: packages/embeds/core/README.md, packages/embeds/react/README.md, packages/embeds/core/src/index.ts, packages/embeds/react/package.json
Next, read the broader integration and API pages when the embed needs data beyond the embedded referral dashboard surface. Use the API authentication material for server-side API keys and publishable client-side tracking keys, the analytics pages for reporting concepts, and the partner-program pages for the business objects that a referral dashboard represents. Within this repository documentation set, the most relevant follow-ups are the API reference introduction, authentication, track API, analytics overview, and partner-program pages, because those explain the resources and events that surround an embedded Dub partner experience.