Relevant source files
The following files were used as context for generating this wiki page:
- pnpm-workspace.yaml
- package.json
- apps/web/package.json
- packages/email/package.json
- turbo.json
- packages/ui/package.json
- apps/web/app/api/old/projects/route.ts
- apps/web/app/api/old/projects/slug/route.ts
- packages/ui/src/index.tsx
- packages/cli/tsconfig.json
- apps/web/lib/auth/index.ts
- packages/ui/tsup.config.ts
- apps/web/tsconfig.json
- packages/hubspot-app/package.json
- packages/stripe-app/stripe-app.dev.json
- packages/ui/src/nav/index.ts
- apps/web/app/layout.tsx
- packages/email/tsconfig.json
- apps/web/app/ee/app.dub.co/layout.tsx
- apps/web/app/app.dub.co/dashboard/slug/ee/settings/integrations/layout.tsx
- packages/utils/src/index.ts
- packages/utils/src/constants/index.ts
- packages/embeds/core/src/index.ts
- apps/web/app/api/old/projects/slug/domains/route.ts
- apps/web/app/domain/layout.tsx
- packages/utils/tsup.config.ts
- apps/web/app/app.dub.co/dashboard/slug/ee/settings/domains/email/page.tsx
- packages/email/src/react-email.d.ts
- apps/web/lib/edge-config/index.ts
- apps/web/app/api/old/projects/slug/domains/default/route.ts
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 Name | Depends On | Cache | Persistent | Outputs |
|---|---|---|---|---|
build | ^build | Enabled | False | !.next/cache/**, .next/**, dist/** |
dev | None | Disabled | True | None |
clean | None | Disabled | False | None |
test | ^build | Enabled | False | None |
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 Path | Re-exported Target Path | Target Purpose |
|---|---|---|
apps/web/app/api/(old)/projects/route.ts | ../../workspaces/route | Workspace list and creation endpoints |
apps/web/app/api/(old)/projects/[slug]/route.ts | ../../../workspaces/[idOrSlug]/route | Individual workspace retrieval, update, and deletion handlers |
apps/web/app/api/(old)/projects/[slug]/domains/route.ts | ../../../../domains/route | Workspace custom domain listing and registration endpoints |
apps/web/app/api/(old)/projects/[slug]/domains/default/route.ts | ../../../../../domains/default/route | Default 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 Key | Source Path | Output Format | Purpose |
|---|---|---|---|
index | src/index.tsx | ESM | Core components, hooks, layout elements, and logos |
icons/index | src/icons/index.tsx | ESM | Standalone icon package exports |
charts/index | src/charts/index.ts | ESM | Visualization 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 Subpath | Target Source File | Export Scope |
|---|---|---|
./constants | src/constants/index.ts | Tools, ccTLDs, regions, and domains |
./functions | src/functions/index.ts | General-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 Export | HTML Element Mapping | React 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> |
Preview | Fragment container | { children: React.ReactNode } |
Tailwind | Style 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
Related
On This Page
OverviewMonorepo workspace organization and toolingWorkspace Layout and Package ManagementTurborepo Pipeline OrchestrationRoot Scripts and Publishing WorkflowsWeb application routing and layoutsApp Directory Layout Hierarchies and Domain WrappersEnterprise Settings and Integration LayoutsLegacy API route forwardingWorkspace and Domain Endpoint AliasingRe-export Implementation DetailsDesign system and component packageComponent Architecture and Bundling ConfigurationRoot Exports and Navigation ModulesShared utilities and embed librariesUtility Package Configuration and ConstantsConstant Module AggregationCore Embed ModulesIntegration applications and email definitionsStripe App DefinitionsReact Email Type DeclarationsRelated