Native / additional build steps:

# Push Prisma schema to your database (no migration files)
pnpm prisma:push

# Required environment variables must be set before starting the dev server
# (see Project setup below)

Project setup

1. Copy source - Place the contents of source/ at the root of your Next.js project (or inside apps/web/ in a Turborepo monorepo).

2. Install dependencies - Use the install commands above. Node v23+ and pnpm 9.15+ are recommended.

3. Configure tsconfig.json - Ensure path aliases are present:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

4. Set environment variables - Create .env.local:

NEXTAUTH_SECRET=your_secret
NEXTAUTH_URL=http://app.localhost:3000
DATABASE_URL=mysql://user:pass@localhost:3306/dub
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...
STRIPE_SECRET_KEY=sk_test_...
RESEND_API_KEY=re_...
TINYBIRD_API_KEY=...

5. Start local services - Run docker-compose up -d to spin up MySQL and Redis.

6. Seed the database - Run pnpm run script dev/seed from apps/web/.

7. Start the dev server - pnpm dev. The app expects subdomain routing (app.localhost:3000, admin.localhost:3000). Add entries to /etc/hosts or use a tool like pnpm dlx serve.

Public API

ReferralsEmbedBounties

// app/(ee)/app.dub.co/embed/referrals/bounties/index.tsx
export function ReferralsEmbedBounties(): JSX.Element

Renders the referral embed bounty list and detail views. Reads initial bounty data from useReferralsEmbedData() context, maintains local state for selected bounty and view mode (detail | submission-form | submission-view), and animates transitions with framer-motion. Use this inside the referral embed page when you want the full bounty UI surface.

ProgramBrandAssets

// app/app.dub.co/(dashboard)/[slug]/(ee)/program/resources/program-brand-assets/index.tsx
export function ProgramBrandAssets(): JSX.Element

Renders the brand asset management section for a program (logos, colors, files, links). Uses useProgramResources for data fetching and next-safe-action for delete mutations. Provides modal hooks (useLogoModal, useColorModal, useFileModal, useLinkModal) with edit-mode support. Drop this into any program settings page that requires resource CRUD.

lib/api/links (barrel exports)

// lib/api/links/index.ts
export * from "./archive-link";
export * from "./bulk-create-links";
export * from "./create-link";
export * from "./delete-link";
export * from "./get-links-count";
export * from "./get-links-for-workspace";
export * from "./process-link";
export * from "./update-link";
export * from "./utils";

Central server-side link operations. Import individual functions (createLink, updateLink, deleteLink, processLink, etc.) from @/lib/api/links in API route handlers or server actions. processLink handles URL normalization, key generation, and domain validation before persistence.

lib/analytics/utils (barrel exports)

// lib/analytics/utils/index.ts
export * from "./convert-to-csv";
export * from "./edit-query-string";
export * from "./get-interval-data";
export * from "./valid-date-range-for-plan";

Analytics utility helpers. convertToCsv serializes analytics rows for export. editQueryString builds typed analytics filter URLs. getIntervalData returns granularity metadata for a given time interval. validDateRangeForPlan guards against plan-restricted date ranges before querying Tinybird.

Working examples

Scenario - Rendering the bounty embed in a custom portal

Embed the bounty UI inside your own partner portal page. The component reads data from context so wrap it in the ReferralsEmbedDataProvider first.

// app/my-portal/referrals/page.tsx
import { ReferralsEmbedBounties } from "@/app/(ee)/app.dub.co/embed/referrals/bounties";
import { ReferralsEmbedDataProvider } from "@/app/(ee)/app.dub.co/embed/referrals/page-client";

export default function ReferralsPage() {
  return (
    <ReferralsEmbedDataProvider>
      <main className="max-w-2xl mx-auto py-10">
        <h1 className="text-xl font-semibold mb-4">Your Bounties</h1>
        <ReferralsEmbedBounties />
      </main>
    </ReferralsEmbedDataProvider>
  );
}

Scenario - Creating a link via the server-side API helper

Use createLink inside a Next.js route handler or server action to programmatically create a short link.

// app/api/my-links/route.ts
import { createLink } from "@/lib/api/links";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const body = await req.json();

  const link = await createLink({
    url: body.url,
    domain: "dub.sh",
    key: body.key ?? undefined,
    workspaceId: body.workspaceId,
    userId: body.userId,
  });

  return NextResponse.json(link, { status: 201 });
}

Scenario - Exporting analytics data to CSV

Convert a Tinybird analytics result set into a downloadable CSV string using the analytics utility.

// lib/export-analytics.ts
import { convertToCsv, getIntervalData } from "@/lib/analytics/utils";

async function exportClicksAsCsv(rows: Record<string, unknown>[]) {
  const intervalMeta = getIntervalData("30d");
  console.log("Granularity:", intervalMeta.granularity);

  const csv = convertToCsv(rows, {
    columns: ["date", "clicks", "country"],
  });

  return csv; // write to file or stream to browser
}

Scenario - Rendering program brand assets in a settings page

Mount the ProgramBrandAssets component inside any program settings route. It handles its own data fetching, modals, and mutations.

// app/app.dub.co/(dashboard)/[slug]/(ee)/program/settings/brand/page.tsx
import { ProgramBrandAssets } from "@/app/app.dub.co/(dashboard)/[slug]/(ee)/program/resources/program-brand-assets";

export default function BrandSettingsPage() {
  return (
    <section className="space-y-6">
      <h2 className="text-lg font-medium">Brand Assets</h2>
      <ProgramBrandAssets />
    </section>
  );
}

File walkthrough

• app/ - Next.js App Router root; contains all page, layout, and route handler files organized by subdomain.
• app/(ee)/ - Enterprise-edition feature routes gated behind a license; includes admin dashboard, advanced partner portal pages, and EE API routes.
• app/[domain]/ - Catch-all handler for custom short-link domains that resolves redirects at the edge.
• app/api/ - Public REST API route handlers exposed to SDK consumers.
• app/app.dub.co/ - Core workspace dashboard: link table, analytics views, program management.
• app/cloaked/ - Serves cloaked (iframe-wrapped) redirect pages.
• app/password/ - Password-gate UI for protected links.
• guides/ - Prose/MDX documentation pages served inside the app.
• lib/ - All shared server-side code: SWR hooks, Zod schemas, Prisma queries, server actions, third-party integrations.
• lib/api/links/ - Atomic link operation functions used by both API routes and server actions.
• lib/analytics/utils/ - Pure utility functions for analytics data transformation and validation.
• playwright/ - E2E test setup, fixtures, and specs using Playwright.
• public/ - Static files served verbatim (favicons, OG images, etc.).
• scripts/ - One-off maintenance and seed scripts executed via pnpm run script.
• styles/ - Global CSS imports and Tailwind base overrides.
• ui/ - Reusable React components: charts, modals, partner cards, empty states, shared layout primitives.
• middleware.ts - Edge middleware that handles subdomain routing, auth redirects, and link cloaking logic.
• next.config.js - Rewrites, image remote patterns, transpile packages, and bundle analyzer config.
• tailwind.config.ts - Design token extensions, custom plugins, and content paths.
• instrumentation.ts - Registers OpenTelemetry and Vercel Speed Insights on server startup.
• docker-compose.yml - Defines MySQL and Redis services for local development.

Common pitfalls and fixes

• Missing subdomain routing locally - The app uses app.localhost, admin.localhost, etc. Add them to /etc/hosts pointing to 127.0.0.1, or the middleware will redirect every request to a 404.
• The table does not exist Prisma error - You skipped pnpm prisma:push; run it to sync the schema without creating migration files.
• @dub/ui or @dub/utils not resolving - These are internal monorepo packages; if you extracted apps/web outside the monorepo, replace them with their published npm equivalents or copy packages/ui and packages/utils alongside and update tsconfig paths.
• next-safe-action version mismatch - The codebase uses useAction from next-safe-action/hooks; pin to ^7 to avoid breaking API changes introduced in v8.
• Tinybird queries returning empty - validDateRangeForPlan silently clamps ranges for free plans; pass the correct plan tier or override the guard in dev to see historical data.
• NEXTAUTH_URL must match the exact subdomain - Setting it to http://localhost:3000 instead of http://app.localhost:3000 causes auth callbacks to fail with a redirect mismatch error.

Vibe-coding prompt template

I have a copy of the Dub open-source link attribution platform source in the `source/` directory.
USAGE.md in the same folder documents the real exports, file structure, and setup steps.
The upstream package is `dub-monorepo`.

My project is a [describe your project: e.g., "Next.js 14 SaaS app using the App Router and Prisma"].

Please help me integrate the Dub source step by step:

1. Read USAGE.md and the file excerpts to understand the real exported symbols.
2. Add the required environment variables from USAGE.md to my `.env.local`.
3. Copy the relevant parts of `source/lib/api/links` into my project so I can call `createLink` and `updateLink` from my own API routes.
4. Wire up `source/lib/analytics/utils` so I can export analytics data as CSV.
5. If I need the partner/referral embed UI, show me how to mount `ReferralsEmbedBounties` inside my existing layout.
6. Adjust all `@/` path aliases to match my project's `tsconfig.json` `paths` configuration.
7. Point out any peer-dependency version conflicts before making changes.

Do not invent any imports or functions that are not visible in USAGE.md or the source file excerpts.

License and credit

The enterprise-edition portions of this source (app/(ee)/) are covered by a separate license described in source/app/(ee)/LICENSE.md. The remainder of the codebase is released under the open-source license found in the repository root (source/LICENSE.md if present — see the upstream GitHub repository for the authoritative license text).

Upstream project: Dub by dub.co — the open-source link attribution platform.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.