OpenWikidubinc/dub

Link Attribution

Purpose and Scope

Link attribution is the product idea that connects a short-link click to later business outcomes. In Dub terminology, the journey starts when someone clicks a branded short link, continues when that visitor becomes a lead or customer, and can end in a sale, commission, or affiliate-program payout. The official product documentation describes this as a multi-stage flow from click to lead to sale to commission. This page explains that workflow from a repository-facing perspective: which public surfaces expose link operations, which packages support the dashboard and integrations, and how contributors should reason about attribution-related changes.

Attribution is broader than URL shortening. A short link is the entry point, but the platform also needs durable identifiers, conversion tracking, analytics dimensions, partner context, operational emails, and user-facing controls. The source paths for this page are package entry points rather than the full web application implementation, so the most useful view is the system boundary. The CLI exposes link-oriented workflows to developers, the UI package exports the reusable interface pieces used to configure and inspect links, the utilities package centralizes shared constants and functions, and the email package provides notification delivery for operational workflows. Sources: package.json, packages/cli/src/index.ts, packages/cli/package.json, packages/email/src/index.ts, packages/ui/src/index.tsx, packages/utils/src/index.ts

Relevant Source Files

  • package.json — Declares the root monorepo identity, AGPL-3.0-or-later license, Turborepo scripts, package publishing scripts, and pnpm package manager version that shape how attribution-related code is built and released.
  • packages/cli/src/index.ts — Defines the public dub command, describes it as a CLI for shortening links with the Dub API, and registers login, config, domains, shorten, and links commands.
  • packages/cli/package.json — Publishes the CLI as the dub binary, identifies it as dub-cli, and lists dependencies such as commander, configstore, oauth2-client, zod, and the dub SDK.
  • packages/email/src/index.ts — Exports sendEmail and sendBatchEmail, choosing Resend when configured and falling back to SMTP when SMTP_HOST and SMTP_PORT are present.
  • packages/ui/src/index.tsx — Exports the shared UI component surface, including link-oriented and attribution-adjacent components such as link-preview, utm-builder, mini-area-chart, table, filters, badges, and form controls.
  • packages/utils/src/index.ts — Re-exports constants and functions as the shared utility layer used by packages and applications.

Attribution Model

Dub’s attribution model can be read as a sequence of evidence collection steps. First, a visitor clicks a Dub short link. The official attribution documentation says the click is captured server-side before redirect, and that captured click data can include time, location, device, browser, referrer, UTM parameters, and whether the click came from a QR code or a short link. The destination URL receives a dub_id query parameter, and a client-side script can preserve that identifier in a first-party cookie so later conversion events can be tied back to the original click.

The second and third stages are conversion events. A lead event represents a meaningful identity or signup moment, while a sale event represents revenue associated with a previously attributed visitor or customer. Deep-link attribution extends the same idea into app contexts, where a link opens an app experience and a later conversion event still needs to be attached to the link journey. The official docs also note that partner links have conversion tracking enabled by default, which is why attribution and affiliate programs should be treated as connected systems rather than isolated features.

The repository entry points show that attribution is intentionally exposed through multiple surfaces. The root package defines a private monorepo with Turborepo scripts for build, dev, lint, package builds, and tests, which means attribution work usually spans application code and shared packages instead of living in a single library. Publishing scripts for the CLI, UI, utilities, and embed packages show that parts of the attribution platform are distributed independently from the hosted web application. Sources: package.json

System-to-Code Mapping

The CLI is the clearest package-level public surface for link attribution workflows. Its main program is named dub, describes itself as a CLI for shortening links with the Dub API, loads package metadata for version output, and registers commands for login, config, domains, shorten, and links. Those commands map to a practical attribution path: authenticate, select or configure a workspace context, manage the domain where branded links live, create a short URL, and inspect or manage link records after creation. Sources: packages/cli/src/index.ts

The CLI package manifest adds detail about how that surface is distributed. It publishes the dub binary from dist/index.js, marks the package as public, prefers global installation, and depends on the dub SDK, commander, configstore, oauth2-client, prompts, zod, and node-fetch. That dependency mix is significant for attribution-facing tooling: it supports command routing, persistent local configuration, authentication, schema validation, API access, and user prompts. Contributors changing link or domain workflows should consider both the API behavior and the installed CLI experience. Sources: packages/cli/package.json

The UI package represents the reusable building blocks used to make attribution understandable in the product interface. Its barrel export includes general primitives such as buttons, forms, tables, filters, modals, popovers, switches, date pickers, pagination controls, badges, and charts. It also exports link-preview, link-logo, utm-builder, tooltip-advanced-link-features, mini-area-chart, and timestamp-tooltip, which are directly relevant to configuring campaign links and explaining their performance. In practice, link attribution requires interfaces that let users build campaign URLs, preview branded links, inspect time-based metrics, and understand advanced tracking options without exposing raw pipeline details. Sources: packages/ui/src/index.tsx

The utilities package is intentionally small at this entry point: it re-exports constants and functions. That matters because attribution systems depend on consistent interpretation of shared values, not just request handlers. Constants can encode product-wide defaults, domains, or limits, while utility functions can normalize dates, URLs, query parameters, or display formats. When a link click, conversion event, dashboard report, and CLI response all need to agree on the same meaning, shared utilities reduce drift between surfaces. Sources: packages/utils/src/index.ts

The email package supports attribution operations that need human notification. Its sendEmail function sends through Resend when configured, falls back to SMTP when SMTP_HOST and SMTP_PORT are set, and logs a configuration warning when neither provider is available. sendBatchEmail follows the same provider order and accepts an optional idempotencyKey for Resend batch delivery. In affiliate-program workflows, email delivery can support notifications about imports, partner activity, commissions, payouts, approvals, or operational errors, so provider fallback is part of the reliability story. Sources: packages/email/src/index.ts

Execution Flow

A typical user path begins with a workspace owner or developer creating a short link for a campaign, partner, product launch, or deep-link destination. Through the dashboard, that experience is backed by UI components for forms, UTM building, previewing the final link, and displaying analytics. Through the CLI, the equivalent first steps are to authenticate with dub login, configure context with dub config, choose or manage a branded domain with dub domains, and create a link with dub shorten or the broader dub links command family. The source entry point does not spell out each subcommand’s options, but it does define these command families as the public CLI shape.

After the link exists, attribution starts at click time. The official docs emphasize that click tracking happens before redirect, which protects the measurement from client-side blockers and lets Dub attach server-observed metadata to the event. From the user’s point of view, this is why a short link is more than a redirect alias: it becomes the durable source of campaign, partner, device, location, and referrer information. Later, lead or sale tracking uses the click identifier, often propagated as dub_id, to connect downstream conversion events to the original link.

Affiliate programs add another layer to the same flow. A partner link is a short link with relationship and reward context. When that link drives a click, and the click becomes a lead or sale, the attribution record can become the basis for commissions and payouts. The package-level source included here does not define commission schemas, but the root monorepo and email surfaces show how product subsystems are packaged: shared UI for program dashboards, utilities for consistent data handling, CLI/API access for link resources, and email delivery for operational notifications. Sources: package.json, packages/email/src/index.ts, packages/ui/src/index.tsx

Public Surfaces and Contracts

For developers, the most concrete contract on this page is the CLI binary. The package name is dub-cli, but the executable command is dub. Its package manifest exposes dist/index.js as main, exports, and bin, and the TypeScript entry point uses commander to register the command tree. That means documentation, examples, and support responses should refer to the installed binary as dub, not as the package name. The root package includes a publish-cli script that builds the @dub/cli filter and publishes from packages/cli, so release changes should preserve both package metadata and command behavior. Sources: package.json, packages/cli/package.json, packages/cli/src/index.ts

dub --version
dub login
dub config
dub domains
dub shorten https://example.com
dub links

The shared package contracts are barrel exports. packages/ui/src/index.tsx imports styles once and then re-exports component families, hooks, icons, layout, content, miscellaneous helpers, and logos. packages/utils/src/index.ts re-exports constants and functions. packages/email/src/index.ts exposes sendEmail and sendBatchEmail rather than forcing callers to choose Resend or SMTP directly. These contracts keep attribution features composable: a new dashboard view can consume common UI, a worker can call email helpers, and a command can rely on shared package behavior while the monorepo build system coordinates release and type checking. Sources: packages/ui/src/index.tsx, packages/utils/src/index.ts, packages/email/src/index.ts

Implementation Notes for Contributors

When changing attribution behavior, start by identifying which layer owns the user-visible contract. Link creation and management changes may need API, dashboard, and CLI updates. Presentation changes may belong in @dub/ui if they are reusable across analytics, links, partner programs, or settings screens. Shared parsing, formatting, or constants should live behind @dub/utils exports when multiple packages need the same behavior. Notification behavior should call the email package entry points so provider selection remains consistent between Resend and SMTP deployments.

Be careful with terminology. A click is the observed short-link event before redirect. A lead is a conversion event that identifies meaningful intent or signup. A sale is a revenue event. A commission is the partner-program financial consequence of an attributed sale or qualifying event. A deep link is a link that opens an app destination while still participating in conversion tracking. Keeping those terms distinct helps avoid UI copy, CLI help, and API examples that accidentally imply every click is a lead or every sale creates the same payout workflow.

Next Steps

Read Links and Short URLs next if you need the core link resource model, Conversion Tracking Events if you are implementing lead, sale, open, or event tracking, and Partner Programs and Bounties if you are working on affiliate-program workflows. For developer tooling, continue to CLI Workflows and CLI Reference. For reporting, read Analytics Overview and the device, location, referrer, and UTM analytics pages so attribution changes preserve the dimensions users expect in campaign performance reports.

Ask a question...