Dub 前端工具库 dub/utils 深度解析函数设计、常量资产与 Monorepo 工程化实践【免费下载链接】dubThe modern link attribution platform. Loved by world-class marketing teams like Framer, Perplexity, Superhuman, Twilio, Buffer and more.项目地址: https://gitcode.com/GitHub_Trending/du/dub本文围绕 Dub 开源仓库中 packages/utils/README.md 所定义的dub/utils工具库展开系统梳理其在 Dub 多 Web 应用app.dub.co、admin.dub.co、partners.dub.co 等之间承担的基础能力从样式合并、短链 ID 生成、请求重试与超时控制到日期格式化、货币显示与全局常量资产。读完本文你将掌握该工具库的安装方式、完整函数与常量清单、核心实现的源码级原理以及它作为独立 ESM 包在 pnpm Monorepo 中的工程化构建与发布实践。一、包定位Dub 全应用的公共基础设施根据 README 的描述dub/utils是用于 Dub 各 Web 应用的实用函数库a library of utility functions that are used across Dubs web applications。它的定位决定了两个设计取向跨端复用同时服务于服务端与客户端代码因此包内既有纯逻辑函数如nanoid、timeAgo也有面向 React/SWR 的封装如fetcher。单一事实来源将 Dub 全站共享的常量资产国家、货币、域名、定价信息等统一收敛到该包避免在多个应用间复制粘贴导致不一致。从仓库结构看该包全部源码位于 packages/utils/src通过 src/index.ts 一行聚合导出export * from ./constants; export * from ./functions;即整个包对外只暴露两大命名空间constants常量与functions函数下文分别展开。二、安装与接入一条命令引入全量工具README 给出了唯一的安装方式pnpm i dub/utils结合 package.json 可以进一步了解其接入细节包名dub/utils版本0.2.0构建产物main与module均指向./dist/index.mjs类型声明为./dist/index.d.ts说明该包是ESM-only输出发布文件files字段仅包含dist/**即 npm 包只发布编译产物不含源码与配置文件peerDependencies声明next15.5.7、react19.1.3、react-dom19.1.3表明部分函数如cn、fetcher面向 Next.js React 19 环境设计由宿主应用提供这些运行时依赖避免重复打包运行时依赖sindresorhus/slugifyslug 化、chrono-node自然语言日期解析、clsx与tailwind-merge样式合并、ms毫秒格式化、nanoid短 ID、punycode国际化域名处理。在 Dub 仓库的 pnpm workspace见 pnpm-workspace.yaml中各应用通过 workspace 协议直接依赖本地包因此pnpm i dub/utils既能从 npm registry 安装也能在本地 monorepo 内直接软链到 packages/utils。三、函数库全景按职责划分的六大类functions/index.ts 共导出了约 50 个独立模块按职责可划分为六类下面结合源码逐一讲解代表性实现。3.1 样式与 React 辅助cncn.ts是 Dub 前端最常用的类名合并工具实现极简但功力深厚import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }它先由clsx完成条件类名的合并支持字符串、对象、数组等混合入参再交给tailwind-merge对 Tailwind CSS 类进行冲突消解——例如同时传入p-2和p-4时后者会覆盖前者保证最终样式符合预期。这与 tailwind.config.ts 的定制主题体系配合使用是 Dub 大量 UI 组件的公共基底。同属此类的还有is-click-on-interactive-child判断点击是否落在交互子元素上常用于弹层/下拉关闭逻辑、is-iframeable校验页面是否允许被 iframe 嵌入等。3.2 网络请求SWR fetcher、重试与超时fetcherfetcher.ts是为 SWR 定制的数据拉取器请求失败时解析响应体中的error.message作为错误信息并构造带info与status字段的SWRError抛出使上层 UI 能精确感知 HTTP 状态码。这也是 Dub 仪表盘数据层apps/web/lib/swr统一采用的取值约定。fetchWithRetryfetch-with-retry.ts则面向服务端等对稳定性要求更高的场景其默认策略为参数默认值说明timeout5000单次请求超时毫秒数通过AbortController中断maxRetries10最大重试次数retryDelay1000基础重试间隔毫秒数其重试策略具有清晰的语义分层429 限流或 5xx 服务端错误按retryDelay i² * 50的退避公式等待后重试指数退避的轻量实现403 未授权立即抛出Unauthorized不重试其他 4xx解析响应体错误信息后直接抛出网络错误/超时等待退避后重试直到耗尽maxRetries最终抛出包含 Failed after N retries 的汇总错误。fetchWithTimeoutfetch-with-timeout.ts是更轻量的单次请求封装默认 5 秒超时超时即reject(new Error(Request timed out))适合对快速失败有明确要求的调用点。3.3 短 ID 与哈希nanoidnanoid.ts是 Dub 链接短码生成的基石export const nanoid (chars?: number) { return customAlphabet( 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz, chars || 7, // 默认 7 位随机字符串 )(); };使用 62 字符字母表默认生成7 位大小写敏感的随机短码——这与 Dub 对外短链接dub.sh/xxxxxxx的形态直接对应Dub 的完整短码生成链路见 apps/web/lib/api/create-id.ts 及其对nanoid的调用。配套的还有hash-string字符串稳定哈希与random-value随机取值。3.4 时间与日期日期相关函数集中在 datetime 子目录覆盖format-date、format-date-smart、format-datetime、format-datetime-smart、format-period、get-datetime-local、get-days-difference、get-first-and-last-day、parse-datetime基于chrono-node的自然语言解析以及面向计费的billing-utils。timeAgotime-ago.ts是 Dub 界面中刚刚 / 5m ago / 3h ago这类相对时间的实现其边界处理值得借鉴空值返回Never未来时间戳或距今超过 23 小时回退为en-US本地化日期Sep 11跨年份时自动补全年份作者在注释中说明与 Twitter 展示时间戳的方式类似不足 1 秒显示Just now其余情况用ms库格式化为5m、3h等传入withAgo: true时追加 ago后缀。3.5 货币与格式化currencyFormattercurrency-formatter.ts以分为单位接收金额内部先经toCentsNumber归一化再借助Intl.NumberFormat输出本地化货币字符串。其亮点是对零小数货币如 JPY的处理当目标货币在 currency-zero-decimal.ts 的零小数列表中时不除以 100并启用trailingZeroDisplay: stripIfInteger去除多余的.00。该函数支撑了 Dub 佣金与收入报表apps/web/ui/analytics中的金额展示。同类的还有format-file-size文件大小人性化、nformatter数字缩写如 1.2k、pretty-print、to-cents-number、combine-words词组合并等。3.6 字符串、集合与杂项字符串camel-case、capitalize、normalize-string、pluralize基于sindresorhus/slugify风格、truncate、smart-truncate、regex-escape、punycode国际化域名转换、trim集合chunk分批切片、group-by、unique、pick、pluck、keys、deep-equal、array-equal、stable-sort稳定排序流程控制sleepsetTimeout的 Promise 封装、promisesPromise 工具、process-in-batches分批处理大数据集Dub 业务域link-constructor链接组装、domains域名处理、construct-metadata元数据构造、avatar头像 URL、resize-image图片缩放、log日志、urlsURL 工具、parse-filter-value解析过滤参数值支撑分析页筛选。四、常量资产一份数据全站共享constants/index.ts 将 Dub 的业务静态数据统一收拢避免各应用各自维护常量模块内容countries/regions/continents国家、区域、大洲的基础数据country-currency-codes/country-phone-codes国家与货币、电话区号映射cctlds国家顶级域名ccTLD列表用于域名校验与分类dub-domains/domainsDub 自有域名与通用域名数据reserved-slugs保留的短链/用户名 slug 黑名单防止撞车localhost本地开发环境识别数据connect-supported-countries、paypal-supported-countries、stablecoin-supported-countries、tremendous-supported-countries各支付/激励渠道支持的国家白名单samlSSO/SAML 相关配置数据integrations/all-tools集成列表与工具清单middleware/misc中间件与杂项常量pricing/定价套餐文案与数值pricing-plans、pricing-plan-main-features、pricing-plan-compare-features、pricing-plan-taglines、plan-period-utils、trial-limits定价相关常量独立成pricing子目录如 pricing-plans.tsx、trial-limits.ts支撑 Dub 套餐对比与试用限制逻辑是常量即配置思想的典型实践——修改一处全站生效。五、工程化tsup 构建与 ESM 分发tsup.config.ts 揭示了该包的构建策略export default defineConfig((options: Options) ({ entry: [src/**/*.ts], format: [esm], dts: true, minify: true, clean: process.env.VERCEL 1, external: [react], ...options, }));要点包括entry 为src/**/*.ts每个源文件作为独立入口打包配合package.json的sideEffects: false让打包器可以按需 tree-shaking只把用到的函数打进最终 bundleformat: [esm]仅输出 ESM与现代 Next.js/Rspack 工具链对齐dts: true自动生成.d.ts类型声明保证 TS 项目下的完整类型推导minify: true生产环境压缩external: [react]React 不打包进产物交由宿主应用提供避免重复实例化。开发时可运行pnpm --filter dub/utils dev对应tsup --watch实现源码改动热更新build输出到dist/另有lint与check-typestsc --noEmit保障代码质量。六、总结与使用建议dub/utils展示了大型开源产品中公共包的正确打开方式小而美的函数原子 全局唯一的常量资产 面向现代工具链的 ESM 构建。在 Dub 仓库内它被 app.dub.co、admin.dub.co、partners.dub.co 等多个 Web 应用共同消费既是样式与请求层的公共基底也是国家、货币、定价等业务数据的单一事实来源。对于希望在自己的 Next.js React 19 项目中复用这些模式的开发者建议直接pnpm i dub/utils后按需导入利用 tree-shaking 控制体积参考 src/index.ts 的命名空间划分保持常量与函数分离的组织习惯借鉴fetchWithRetry的分层重试策略与currencyFormatter的零小数货币处理提升自有工具的健壮性需要深挖某个函数时以 functions 与 constants 目录为索引逐文件阅读每个模块均自带独立类型声明与注释适合作为零依赖工具函数的设计范本。【免费下载链接】dubThe modern link attribution platform. Loved by world-class marketing teams like Framer, Perplexity, Superhuman, Twilio, Buffer and more.项目地址: https://gitcode.com/GitHub_Trending/du/dub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
