Skip to main content
doc0blade47/dubdocumentation home
Sign in

Project Structure

Last updated Oct 12, 2026
Relevant source files

The following files were used as context for generating this wiki page:

Overview

The repository is structured as a pnpm workspace monorepo defined in pnpm-workspace.yaml, using Turborepo for pipeline orchestration and build task caching as configured in turbo.json and package.json. It coordinates multiple core applications, including the primary Next.js web console in apps/web, alongside shared packages for UI components in packages/ui, utility functions and constants in packages/utils, transactional email definitions in packages/email, developer tooling via [[CLI Tool]], and integration modules such as [[HubSpot & Intercom]].

Sources: pnpm-workspace.yaml:1-5, package.json:5-21, turbo.json:1-19

Monorepo workspace organization and tooling

Workspace Layout and Package Management

The repository uses pnpm workspaces configured via pnpm-workspace.yaml, encompassing application directories in apps/*, generated templates in apps/web/.react-email, shared packages in packages/*, and embed modules located under packages/embeds/*. Package dependency resolution pins chrono-node to 2.7.5 under resolutions, and workspace package management is tied to pnpm@9.15.9.

packages:
  - "apps/*"
  - "apps/web/.react-email"
  - "packages/*"
  - "packages/embeds/*"

Sources: pnpm-workspace.yaml:1-5, package.json:31-34

Note

Root dependency management relies on development tooling packages including prettier@3.2.5, eslint@8.48.0, turbo@1.12.5, and workspace references for @dub/tailwind-config and tsconfig.

Sources: package.json:22-30

Turborepo Pipeline Orchestration

Turborepo orchestrates execution tasks defined in turbo.json with a remote or local schema target pointing to https://turbo.build/schema.json and **/.env tracked as a global dependency. The pipeline configuration defines four primary tasks governing build caching, persistence, and inter-package dependencies.

Task NameDepends OnCachePersistentOutputs
build^buildEnabledFalse!.next/cache/**, .next/**, dist/**
devNoneDisabledTrueNone
cleanNoneDisabledFalseNone
test^buildEnabledFalseNone

Sources: turbo.json:1-19

Important

The build and test pipeline tasks both enforce upstream dependency builds via ^build, ensuring that shared packages like packages/ui and packages/utils compile before consuming applications or tests execute.

Sources: turbo.json:5-18

Root Scripts and Publishing Workflows

The root package.json defines scripts for workspace maintenance, code formatting via Prettier with Tailwind and import-organizing plugins, and package publication workflows for specific modular packages.

{
  "scripts": {
    "build": "turbo build",
    "build:packages": "pnpm -r --filter \"./packages/**\" build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "clean": "turbo clean",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "prettier-check": "prettier --check \"**/*.{ts,tsx,md}\"",
    "publish-cli": "turbo build --filter='@dub/cli' && cd packages/cli && npm publish && cd ../../",
    "publish-embed-core": "turbo build --filter='@dub/embed-core' && cd packages/embeds/core && npm publish && cd ../../../",
    "publish-embed-react": "turbo build --filter='@dub/embed-react' && cd packages/embeds/react && npm publish && cd ../../../",
    "publish-tw": "turbo build --filter='@dub/tailwind-config' && cd packages/tailwind-config && npm publish && cd ../../",
    "publish-ui": "turbo build --filter='@dub/ui' && cd packages/ui && npm publish && cd ../../",
    "publish-utils": "turbo build --filter='@dub/utils' && cd packages/utils && npm publish && cd ../../",
    "script": "echo 'Run this script in apps/web'",
    "test": "turbo run test"
  }
}

Sources: package.json:5-21

Web application routing and layouts

App Directory Layout Hierarchies and Domain Wrappers

The web application (apps/web) is structured around a Next.js App Directory configuration defined in apps/web/package.json and type-checked via apps/web/tsconfig.json. TypeScript paths resolve @/pages/*, @/scripts/*, @/styles/*, @/ui/*, and @/lib/* relative to the application base URL. The root layout in apps/web/app/layout.tsx imports global styles, font variables (satoshi, inter, geistMono), and wraps children with RootProviders, while injecting a client-side theme script for embeds.

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html
      lang="en"
      className={cn(satoshi.variable, inter.variable, geistMono.variable)}
    >
      <body>
        <RootProviders>{children}</RootProviders>
 

Sources: apps/web/app/layout.tsx:9-21

Multi-tenant domain and enterprise routing handles specialized layouts across different subdomains and path segments. For instance, apps/web/app/[domain]/layout.tsx wraps external pages with responsive navigation and footer components.

export default function ExternalPagesLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex min-h-screen flex-col justify-between bg-neutral-50/80">
      <NavMobile />
      <Nav maxWidthWrapperClassName="max-w-screen-lg lg:px-4 xl:px-0" />
      {children}
      <Footer className="max-w-screen-lg border-0 bg-transparent lg:px-4 xl:px-0" />
    </div>
  );

Sources: apps/web/app/domain/layout.tsx:3-15

Enterprise edition routing aliases app route hierarchies, such as apps/web/app/(ee)/app.dub.co/layout.tsx re-exporting the default layout from the main application namespace.

export { default } from "../../app.dub.co/layout";

Sources: apps/web/app/ee/app.dub.co/layout.tsx:1-1

Note

Request routing across root domains, link redirects, and multi-tenant admin consoles is governed by Next.js middleware alongside these layout hierarchies, as detailed in Request Routing.

Sources: apps/web/app/layout.tsx:1-41, apps/web/app/domain/layout.tsx:1-16

Enterprise Settings and Integration Layouts

Enterprise settings modules utilize dedicated sub-layouts within the dashboard slug path structure. The integrations layout file located at apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/settings/integrations/layout.tsx wraps child route views in IntegrationsLayoutClient.

Sources: apps/web/app/app.dub.co/dashboard/slug/ee/settings/integrations/layout.tsx:1-10

Feature-specific sub-pages under enterprise settings inherit these wrappers. For example, the email domains settings page located at apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/settings/domains/email/page.tsx renders the EmailDomains client component.

Sources: apps/web/app/app.dub.co/dashboard/slug/ee/settings/domains/email/page.tsx:1-5

Warning

Enterprise workspace features like SAML SSO configuration and directory provisioning depend on BoxyHQ integrations initialized within these dashboard settings hierarchies.

Sources: apps/web/app/app.dub.co/dashboard/slug/ee/settings/integrations/layout.tsx:1-10, apps/web/app/app.dub.co/dashboard/slug/ee/settings/domains/email/page.tsx:1-5

Legacy API route forwarding

Workspace and Domain Endpoint Aliasing

The codebase maintains backward compatibility for legacy project-centric API endpoints through wildcard re-exports. These route files alias outdated /api/(old)/projects/* request paths directly to current workspace and domain handlers, preventing breaking changes for legacy client integrations.

Legacy Route PathRe-exported Target PathTarget Purpose
apps/web/app/api/(old)/projects/route.ts../../workspaces/routeWorkspace list and creation endpoints
apps/web/app/api/(old)/projects/[slug]/route.ts../../../workspaces/[idOrSlug]/routeIndividual workspace retrieval, update, and deletion handlers
apps/web/app/api/(old)/projects/[slug]/domains/route.ts../../../../domains/routeWorkspace custom domain listing and registration endpoints
apps/web/app/api/(old)/projects/[slug]/domains/default/route.ts../../../../../domains/default/routeDefault domain configuration handlers

Sources: apps/web/app/api/old/projects/route.ts:1-1, apps/web/app/api/old/projects/slug/route.ts:1-1, apps/web/app/api/old/projects/slug/domains/route.ts:1-1, apps/web/app/api/old/projects/slug/domains/default/route.ts:1-1

Re-export Implementation Details

Each forwarding route utilizes TypeScript's export * wildcard syntax to pass all HTTP request methods (GET, POST, PUT, DELETE, PATCH) through to the target handler without alteration.

export * from "../../workspaces/route";

Sources: apps/web/app/api/old/projects/route.ts:1-1

Similarly, nested slug and domain sub-routes forward path parameters up to the unified domain and workspace directory structures.

export * from "../../../../domains/route";

Sources: apps/web/app/api/old/projects/slug/domains/route.ts:1-1

Note

Grouping legacy endpoints under the (old) directory segment allows Next.js to isolate deprecated URL paths while delegating all execution logic to current workspace controllers.

Sources: apps/web/app/api/old/projects/route.ts:1-1, apps/web/app/api/old/projects/slug/route.ts:1-1

Design system and component package

Component Architecture and Bundling Configuration

The @dub/ui package acts as the centralized design system for the application, organizing interface building blocks, hooks, icons, and layout primitives. Package bundling is handled via tsup, generating output formats and declaration files from multiple entry points defined in tsup.config.ts.

export default defineConfig((options: Options) => ({
  entry: {
    index: "src/index.tsx",
    "icons/index": "src/icons/index.tsx",
    "charts/index": "src/charts/index.ts",
  },
  format: ["esm"],

Sources: packages/ui/tsup.config.ts:3-9

The build process injects "use client" banners into output artifacts automatically through esbuild configuration options, allowing consumer applications to utilize components directly within client boundaries.

esbuildOptions(options) {
  options.banner = {
    js: '"use client"',
  };
},

Sources: packages/ui/tsup.config.ts:10-14

Entry Point KeySource PathOutput FormatPurpose
indexsrc/index.tsxESMCore components, hooks, layout elements, and logos
icons/indexsrc/icons/index.tsxESMStandalone icon package exports
charts/indexsrc/charts/index.tsESMVisualization and charting module exports

Sources: packages/ui/tsup.config.ts:4-8, packages/ui/package.json:12-27

Note

The sideEffects: false configuration in package.json enables tree-shaking across bundlers, discarding unused components when importing selective subpaths like ./icons or ./charts.

Sources: packages/ui/package.json:5-5

Root Exports and Navigation Modules

The main entry point src/index.tsx aggregates exports across multiple domain categories, exposing UI primitives, hooks, graphics, and navigation components.

// components
export * from "./accordion";
export * from "./activity-ring";
export * from "./alert";
export * from "./avatar";
export * from "./badge";
export * from "./button";
export * from "./card-list";
export * from "./card-selector";
export * from "./carousel";
export * from "./checkbox";
export * from "./combobox";
export * from "./date-picker";
export * from "./dots-pattern";
export * from "./dub-status-badge";
export * from "./empty-state";
export * from "./file-upload";
export * from "./filter";
export * from "./form";
export * from "./grid";
export * from "./input";
export * from "./label";
export * from "./menu-item";
export * from "./mini-area-chart";
export * from "./modal";
export * from "./multi-value-input";
export * from "./number-stepper";
export * from "./pagination-controls";
export * from "./popover";
export * from "./progress-circle";
export * from "./progressive-blur";
export * from "./radio-group";
export * from "./rich-text-area";
export * from "./scroll-container";
export * from "./sheet";
export * from "./shimmer-dots";
export * from "./slider";
export * from "./smart-datetime-picker";
export * from "./status-badge";
export * from "./switch";
export * from "./table";
export * from "./timestamp-tooltip";
export * from "./toggle-group";
export * from "./tooltip";
export * from "./truncated-list";
export * from "./utm-builder";
 
// hooks
export * from "./hooks";
 
// icons
export * from "./icons";
 
// layout
export * from "./background";
export * from "./footer";
export * from "./max-width-wrapper";
export * from "./nav";
 

Sources: packages/ui/src/index.tsx:4-62

Navigation features are organized within a dedicated subdirectory under src/nav/index.ts, re-exporting both desktop and mobile navigation controllers.

export * from "./nav";
export * from "./nav-mobile";

Sources: packages/ui/src/nav/index.ts:1-2

Warning

Because @dub/ui declares React 19 and Next 15.5 as peer dependencies, consuming applications must match these runtime versions to prevent hydration mismatches or context provider failures.

Sources: packages/ui/package.json:35-39

Shared utilities and embed libraries

Utility Package Configuration and Constants

The @dub/utils package houses cross-cutting constants, validation helpers, localization data, and pricing parameters consumed across the monorepo. Its build process relies on tsup, configured to compile all TypeScript source files under src/ into ECMAScript modules while generating declaration files and minified outputs.

export default defineConfig((options: Options) => ({
  entry: ["src/**/*.ts"],
  format: ["esm"],
  dts: true,
  minify: true,
  clean: process.env.VERCEL === "1",
  external: ["react"],
  ...options,
}));

Sources: packages/utils/tsup.config.ts:3-11

The package cleans build output artifacts conditionally when executed within a Vercel deployment pipeline, and treats React as an external peer dependency.

export * from "./constants";
export * from "./functions";

Sources: packages/utils/src/index.ts:1-2

Constants are partitioned into distinct domain modules covering geographic metadata, pricing structures, and regional support lists.

Module SubpathTarget Source FileExport Scope
./constantssrc/constants/index.tsTools, ccTLDs, regions, and domains
./functionssrc/functions/index.tsGeneral-purpose helper functions
./pricing/...src/constants/pricing/...Plan limits, trial rules, and feature comparisons

Sources: packages/utils/src/index.ts:1-2, packages/utils/src/constants/index.ts:1-28

Note

The clean: process.env.VERCEL === "1" setting ensures that build directories are wiped exclusively in cloud CI environments, preserving incremental local builds during active development.

Sources: packages/utils/tsup.config.ts:8-8

Constant Module Aggregation

The central entry point for constant definitions, src/constants/index.ts, re-exports data arrays and mapping tables across twenty foundational categories and multiple pricing utilities.

export * from "./all-tools";
export * from "./cctlds";
export * from "./connect-supported-countries";
export * from "./continents";
export * from "./countries";
export * from "./country-currency-codes";
export * from "./country-phone-codes";
export * from "./domains";
export * from "./dub-domains";
export * from "./integrations";
export * from "./localhost";
export * from "./main";
export * from "./middleware";
export * from "./misc";
export * from "./paypal-supported-countries";
export * from "./regions";
export * from "./reserved-slugs";
export * from "./saml";
export * from "./stablecoin-supported-countries";
export * from "./tremendous-supported-countries";
 
// pricing copy & values
export * from "./pricing/plan-period-utils";
export * from "./pricing/pricing-plan-compare-features";
export * from "./pricing/pricing-plan-main-features";
export * from "./pricing/pricing-plan-taglines";
export * from "./pricing/pricing-plans";
export * from "./pricing/trial-limits";

Sources: packages/utils/src/constants/index.ts:1-28

Supported domain sets, reserved URL slugs, country phone codes, and payment gateway eligibility criteria are all exposed through this barrel file for consumption by API routes and frontend interfaces.

export * from "./all-tools";
export * from "./cctlds";
export * from "./connect-supported-countries";
export * from "./continents";
export * from "./countries";
export * from "./country-currency-codes";
export * from "./country-phone-codes";
export * from "./domains";
export * from "./dub-domains";
export * from "./integrations";
export * from "./localhost";
export * from "./main";
export * from "./middleware";
export * from "./misc";
export * from "./paypal-supported-countries";
export * from "./regions";
export * from "./reserved-slugs";
export * from "./saml";
export * from "./stablecoin-supported-countries";
export * from "./tremendous-supported-countries";

Sources: packages/utils/src/constants/index.ts:1-20

Tip

Grouping regional compliance lists—such as PayPal, Connect, Stablecoin, and Tremendous supported countries—into individual modules under src/constants/ simplifies feature-gating checks across billing and payout workflows.

Sources: packages/utils/src/constants/index.ts:3-20

Core Embed Modules

The @dub/embeds/core package provides foundational logic, constants, and TypeScript interfaces for client-side widget integration.

export * from "./constants";
export * from "./core";
export * from "./types";

Sources: packages/embeds/core/src/index.ts:1-3

The package exports three core submodules handling operational constants (./constants), core execution flows (./core), and type definitions (./types) required to mount interactive embed elements safely in external host environments.

export * from "./constants";
export * from "./core";
export * from "./types";

Sources: packages/embeds/core/src/index.ts:1-3

Integration applications and email definitions

Stripe App Definitions

The packages/stripe-app workspace maintains configuration files for integrating the platform with Stripe apps. The developer manifest file stripe-app.dev.json extends the base configuration schema.

Sources: packages/stripe-app/stripe-app.dev.json:1-3

Note

Separating development configuration overrides into stripe-app.dev.json allows local extension testing without mutating production Stripe app manifests.

Sources: packages/stripe-app/stripe-app.dev.json:1-3

React Email Type Declarations

The packages/email workspace handles transactional messaging templates and incorporates custom TypeScript declarations for @react-email/components. The package compilation is governed by tsconfig.json, which extends the shared base configuration and configures NodeNext module resolution alongside React JSX transforms.

{
  "extends": "../tsconfig/base.json",
  "include": [
    "src/**/*"
  ],
  "typeRoots": ["node_modules/@types", "src"],
  "exclude": [
    "node_modules"
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    "strict": true,
    "skipLibCheck": true
  }

Sources: packages/email/tsconfig.json:1-18

Type definitions for @react-email/components are explicitly declared in src/react-email.d.ts to provide strict prop typings for layout primitives and typography elements utilized across transactional Email Notification workflows.

Component ExportHTML Element MappingReact Attribute Interface
Html<html>React.HtmlHTMLAttributes<HTMLHtmlElement>
Head<head>React.HTMLAttributes<HTMLHeadElement>
Body<body>React.HTMLAttributes<HTMLBodyElement>
Container<table>React.TableHTMLAttributes<HTMLTableElement>
Section<table>React.TableHTMLAttributes<HTMLTableElement>
Row<tr>React.HTMLAttributes<HTMLTableRowElement>
Column<td>React.TdHTMLAttributes<HTMLTableDataCellElement>
Img<img>React.ImgHTMLAttributes<HTMLImageElement>
Link<a>React.AnchorHTMLAttributes<HTMLAnchorElement>
Text``React.HTMLAttributes<HTMLParagraphElement>
Heading<h1>-<h6>React.HTMLAttributes<HTMLHeadingElement>
Hr<hr>React.HTMLAttributes<HTMLHRElement>
PreviewFragment container{ children: React.ReactNode }
TailwindStyle provider wrapper{ children: React.ReactNode }

Sources: packages/email/src/react-email.d.ts:1-20

Warning

The module declaration for @react-email/components must remain synchronized with upstream package releases to prevent type mismatches during template compilation.

Sources: packages/email/src/react-email.d.ts:1-20

Was this page helpful?