@dub/utils Package

Purpose and Scope

@dub/utils is Dub's shared utility package for code that needs to be reused across Dub web applications. Its README defines the package as a library of utility functions used across Dub's web applications, while the package metadata describes it as utility functions and constants for Dub. That distinction matters for contributors: this package is not a feature surface like the dashboard, CLI, or analytics API. It is a supporting library that keeps common application constants, formatting helpers, and cross-cutting primitives out of individual app directories so those apps can consume consistent values.

Sources: packages/utils/README.md, packages/utils/package.json

Use this package when a value or helper is intended to be shared rather than owned by one route, component, or service. The source evidence shows two major categories in the public surface: constants and date/time functions. Constants include environment-aware domains, hostnames, brand assets, workspace identifiers, region and country datasets, pricing copy, and integration-related lists. Date/time exports cover formatting, smart formatting, billing utilities, period formatting, local datetime conversion, day differences, first/last day helpers, and parsing entry points.

Sources: packages/utils/src/constants/index.ts, packages/utils/src/constants/main.ts, packages/utils/src/functions/datetime/index.ts

Installation and Package Contract

Install the package with pnpm using the package name published in the README:

pnpm i @dub/utils

The package is published as @dub/utils at version 0.1.60 in the supplied metadata. It declares sideEffects: false, which signals to bundlers that unused exports can be tree-shaken when the package is consumed through its module entry. The runtime entry points are ./dist/index.mjs for both main and module, and TypeScript consumers receive declarations from ./dist/index.d.ts. Only dist/** is included in the published files list, so consumers should import from package exports rather than reaching into src paths.

Sources: packages/utils/README.md, packages/utils/package.json

Development of the package follows the same monorepo package pattern as other Dub packages. The package scripts expose build through tsup, dev through tsup --watch, lint over src/, and check-types through tsc --noEmit. Peer dependencies are aligned to Dub's app runtime stack: next, react, and react-dom. Utility dependencies include @sindresorhus/slugify, chrono-node, clsx, ms, nanoid, punycode, and tailwind-merge, which indicate that this package may include helpers for slugs, natural-language dates, class-name composition, durations, IDs, domain normalization, and Tailwind class merging even though those individual modules are outside this page's source scope.

Sources: packages/utils/package.json

Relevant Source Files

• packages/utils/README.md - Defines the package purpose and shows the public installation command.
• packages/utils/package.json - Defines the published package name, version, module and type entry points, scripts, dependencies, peer dependencies, and public publish configuration.
• packages/utils/src/constants/index.ts - Re-exports the constants modules that make up the package's shared constant surface.
• packages/utils/src/constants/main.ts - Defines core Dub domains, hostnames, environment-specific application URLs, brand asset URLs, workspace and program identifiers, and storage URL defaults.
• packages/utils/src/functions/datetime/index.ts - Re-exports date and time utility modules that provide formatting, parsing, period, billing, and date-range helpers.

API Components

The constants index is the main aggregation point for shared values. It re-exports country and geography datasets such as cctlds, continents, countries, country-currency-codes, country-phone-codes, and regions; infrastructure-oriented groups such as domains, dub-domains, localhost, middleware, and reserved-slugs; business and integration groupings such as integrations, paypal-supported-countries, stablecoin-supported-countries, tremendous-supported-countries, and connect-supported-countries; and enterprise or UI-related groups such as layout, misc, and saml. It also exposes pricing modules for plan comparison features, main features, taglines, plans, and trial limits.

Sources: packages/utils/src/constants/index.ts

The main constants file gives the package much of its operational identity. SHORT_DOMAIN is set to dub.sh, and hostname sets distinguish app, API, admin, and partners traffic. APP_HOSTNAMES includes app.dub.co, preview.dub.co, and localhost variants; API_HOSTNAMES includes api.dub.co, api-staging.dub.co, api.dub.sh, and API localhost variants; ADMIN_HOSTNAMES and PARTNERS_HOSTNAMES follow the same pattern for admin and partners subdomains. These sets are useful because application code can reason about host classes without duplicating string lists in multiple places.

Sources: packages/utils/src/constants/main.ts

Environment-specific URL constants encode Dub's production, preview, and local conventions. APP_DOMAIN, API_DOMAIN, and PARTNERS_DOMAIN switch on NEXT_PUBLIC_VERCEL_ENV, using production domains in production, staging or preview domains in preview, and localhost URLs for local development. The APP_DOMAIN_WITH_NGROK and PARTNERS_DOMAIN_WITH_NGROK variants add support for NEXT_PUBLIC_NGROK_URL or Vercel preview URLs, which is important when webhook callbacks, embedded flows, or partner-facing experiences need an externally reachable URL during development. The same file also centralizes asset URLs such as DUB_LOGO, DUB_LOGO_SQUARE, DUB_QR_LOGO, DUB_WORDMARK, and DUB_THUMBNAIL.

Sources: packages/utils/src/constants/main.ts

Date and Time Utilities

The date/time function index is a small but important public boundary. It exports named modules rather than implementing logic inline, which keeps consumers insulated from file layout while preserving a single import area for temporal helpers. The visible exports include billing-utils, format-date, format-date-smart, format-datetime, format-datetime-smart, format-period, get-datetime-local, get-days-difference, get-first-and-last-day, and parse-datetime. Together, those names show the intended use cases: display dates, display datetimes, choose smarter human-readable output, compute ranges, convert for local datetime inputs, compare days, and parse incoming date strings.

Sources: packages/utils/src/functions/datetime/index.ts

For feature teams, the practical rule is to prefer these exports when formatting time in shared product experiences, analytics views, billing flows, or reporting screens. The package dependency on chrono-node in package.json is consistent with parse-oriented datetime utilities, and the dependency on ms is consistent with duration-related helpers. Because the package publishes generated declarations from dist, contributors should add or modify source modules, ensure they are re-exported through the appropriate index, and then run the package build and type-check scripts before relying on those helpers elsewhere.

Sources: packages/utils/package.json, packages/utils/src/functions/datetime/index.ts

Compact Reference

Implementation Guidance

When adding to @dub/utils, start by deciding whether the code is a shared primitive or a feature-specific implementation detail. Constants that describe Dub-wide domains, supported countries, pricing copy, reserved slugs, or integration capabilities belong naturally in the constants area because they are consumed across product surfaces. By contrast, route-specific calculations or UI-only state should remain close to the app or component that owns them. This boundary keeps the package useful without turning it into a catch-all for unrelated application behavior.

Sources: packages/utils/src/constants/index.ts, packages/utils/src/constants/main.ts

For constants, export through the relevant index so callers have a stable import path. For date/time helpers, add the helper module under the datetime function area and expose it through packages/utils/src/functions/datetime/index.ts if it is part of the public utility surface. Before publishing or depending on the change, run the package scripts that match the change: pnpm --filter @dub/utils build for emitted output, pnpm --filter @dub/utils check-types for declaration safety, and pnpm --filter @dub/utils lint for source quality. The root monorepo also includes a dedicated publish script for this package, but publishing should be treated as a release operation rather than a normal local-development step.

Sources: packages/utils/package.json, packages/utils/src/functions/datetime/index.ts

Next Steps

Read this page together with the broader package and monorepo documentation when you need to understand how @dub/utils is built and released. If you are consuming the package, begin with the installation command and the compact reference above. If you are contributing to it, inspect the relevant constants or datetime index, add the new public export deliberately, and verify the package with its local scripts before wiring the helper into Dub's web applications.

Sources: packages/utils/README.md, packages/utils/package.json