Vercel Examples UI 组件库使用指南为 Next.js 示例项目接入统一设计体系【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples本指南围绕vercel/examples-ui组件包展开它是当前仓库internal/packages/ui中维护并被大量示例共用的 UI 库基于 React、TypeScript 与 Tailwind CSS 构建。读完本文你将掌握从安装、Tailwind/PostCSS 配置、全局样式引入到在 App Router 与 Pages Router 两种架构中接入Layout、getLayout、getMetadata等核心能力的完整流程并能结合仓库源码理解其底层实现从而在自己的示例项目中快速获得与 Vercel 官方示例一致的外观与交互。组件包概览一个被全仓库共用的 UI 层vercel/examples-ui的设计目标是一套组件全仓库复用。它被当前仓库中大量示例如 app-directory/css-in-js、app-directory/i18n、edge-middleware/ab-testing-simple 等作为依赖引入统一了页面头部导航、页脚、排版、按钮、输入框、代码块等基础元素的视觉与交互。从 internal/packages/ui/src/index.tsx 的导出清单可以看到包内提供了一组覆盖日常示例页面需求的组件导出组件/工具用途Layout页面布局顶部导航 内容区 页脚的整体框架getLayout布局工厂按页面级Layout属性选择布局未定义时回退为NoopgetMetadata元数据工具生成带- Vercel Examples后缀的title与descriptionNav顶部导航展示示例路径面包屑、More Examples与 Deploy 按钮Button按钮6 种 variant、3 种 size支持渲染为button或aLink/A链接基于next/link支持secondary样式与原生a降级Text排版h1/h2/description/body/smallText五种变体Page内容容器限制最大宽度max-w-3xl并居中List列表ul/ol两种变体带自定义项目符号Code/Snippet代码展示行内代码与代码块Input输入框统一边框、焦点样式LoadingDots加载动画三点闪烁动画供按钮 loading 态使用DeployButton部署按钮根据仓库路径生成 Vercel Clone Deploy 链接Head文档头注入title、meta description与 favicon包版本方面internal/packages/ui/package.json 声明当前版本为2.0.4许可证为 MITpeerDependencies 要求next任意版本以及react/react-dom的^17.0.2 || ^18.0.0-0 || ^19.0.0-0运行时依赖仅clsx与swc/helpers非常轻量。第一步安装组件包与 Tailwind 相关依赖在任意示例项目中安装vercel/examples-ui三种包管理器任选其一npm i vercel/examples-ui # 或 pnpm i vercel/examples-ui # 或 yarn add vercel/examples-ui该包依赖 Tailwind CSS 来拾取自身样式因此若项目尚未安装 Tailwind需一并安装配套工具链npm i tailwindcss postcss autoprefixer # 或 pnpm i tailwindcss postcss autoprefixer仓库内实际项目可验证这一点例如 app-directory/css-in-js/package.json 的 dependencies 中就同时包含vercel/examples-ui与tailwindcss。值得一提的是包的exports字段见 package.json暴露了三个入口主入口./dist/index.js、./tailwindCommonJS 格式的 Tailwind 预设以及./globals.css全局样式后续配置将逐一用到。第二步配置 Tailwind——引入官方预设与组件包内容路径为了让 Tailwind 既能识别组件包内部的样式类设计令牌又能扫描到包编译产物中的 class 名需要在tailwind.config.js中同时做两件事通过presets引入vercel/examples-ui/tailwind并在content中加入组件包的编译产物目录module.exports { presets: [require(vercel/examples-ui/tailwind)], content: [./node_modules/vercel/examples-ui/**/*.js], }仓库中的真实示例会在此基础上叠加自己应用的扫描路径例如 app-directory/css-in-js/tailwind.config.js 与 app-directory/i18n/tailwind.config.js 都在content中额外加入了./app/**/*.{js,ts,jsx,tsx}与./components/**/*.{js,ts,jsx,tsx}module.exports { presets: [require(vercel/examples-ui/tailwind)], content: [ ./app/**/*.{js,ts,jsx,tsx}, ./components/**/*.{js,ts,jsx,tsx}, ./node_modules/vercel/examples-ui/**/*.js, ], }那么 preset 到底提供了什么查看 internal/packages/ui/src/tailwind.cjs 可以看到它通过theme.extend向 Tailwind 注入了一整套设计令牌品牌色板blue/lightblue/violet/rosa/yellow/orange等主题色中性色阶accents09从#fff到#000与success/error/warning三态色均含DEFAULT/dark/light/lighter四级派生语义色selection继承 cyan.light、link继承 success 蓝、code继承 rosa、secondary继承 accents 的多个层级字体族以-apple-system、system-ui为首选的 sans 字体栈动画关键帧blink闪烁动画供LoadingDots使用定义在 loading-dots.tsx 的animate-[blink_1s_ease_0s_infinite_normal_both]中。这意味着只要引入该 preset示例页面中诸如bg-accents-1、text-link、border-accents-2这类语义 class 就能直接生效无需在每个示例中重复定义色板。第三步配置 PostCSS项目根目录需要存在postcss.config.js启用 Tailwind 与 Autoprefixer 插件// If you want to use other PostCSS plugins, see the following: // https://tailwindcss.com/docs/using-with-preprocessors module.exports { plugins: { tailwindcss: {}, autoprefixer: {}, }, }这样 Tailwind 的tailwind指令才能被正确编译为最终 CSS。第四步引入全局样式组件包内置了一份全局样式globals.css它包含 Tailwind 的base/components/utilities三层指令以及对html/body/li的基础重置见 internal/packages/ui/src/globals.css例如body.loading * { transition: none !important; }——规避 Chrome 页面加载时的过渡动画跳动bug统一的box-sizing: border-box与html { height: 100%; touch-action: manipulation; }设置默认字体族、抗锯齿渲染与overscroll-behavior-x: none。在 App Router 中引入在任意 layout 或页面中导入即可import vercel/examples-ui/globals.css仓库中的真实做法可以看 app-directory/css-in-js/app/layout.tsx它在根布局中同时导入了Layout、getMetadata与globals.css并通过getMetadata生成页面标题。在 Pages Router 中引入打开pages/_app.tsx并添加导入以包含包的全局 CSS 与 Tailwind base CSSimport vercel/examples-ui/globals.css如果项目还没有pages/_app.tsx最小化形态如下import type { AppProps } from next/app import vercel/examples-ui/globals.css export default function MyApp({ Component, pageProps }: AppProps) { return Component {...pageProps} / }第五步接入默认 Layout——两种路由架构下的统一外壳组件包提供了示例通用的页面外壳顶部导航栏展示示例路径面包屑、More Examples入口与 Deploy 按钮、居中的内容区以及带有 Vercel Logo 的页脚。在_app.tsx中组合getLayout与Layout即可启用import type { AppProps } from next/app import type { LayoutProps } from vercel/examples-ui/layout import { getLayout } from vercel/examples-ui import vercel/examples-ui/globals.css export default function MyApp({ Component, pageProps }: AppProps) { const Layout getLayoutLayoutProps(Component) return ( Layout titleAPI Rate Limiting with Upstash pathedge-middleware/api-rate-limit-upstash Component {...pageProps} / /Layout ) }这里的title与path是关键参数title用于导航栏与文档头path则对应示例在仓库中的目录路径。仓库中的 edge-middleware/ab-testing-simple/pages/_app.tsx 就是完全按此模式实现的其path为edge-middleware/ab-testing-simple。底层机制查看 internal/packages/ui/src/layout.tsx 可知getLayout的实现是Component?.Layout || Noop——即优先取页面组件上挂载的静态Layout属性若页面未定义则回退到仅渲染 children 的Noop组件。这种页面可选覆盖的设计让每个示例页面都能自定义布局同时又默认继承统一的示例外壳。Layout组件本身由Nav见 nav.tsx与页脚组成Nav会基于path自动拼接形如Vercel Examples / edge-middleware / ab-testing-simple的面包屑并生成指向仓库对应目录的链接。App Router 中的对应做法App Router 没有_app.tsx改为在根布局中直接使用Layout。以 app-directory/css-in-js/app/layout.tsx 为例import type { ReactNode } from react import { Layout, getMetadata } from vercel/examples-ui import vercel/examples-ui/globals.css export const metadata getMetadata({ title: CSS-in-JS libraries in the app directory, description: Learn how to use CSS-in-JS libraries in the Next.js app directory., }) export default function RootLayout({ children }: { children: ReactNode }) { return ( html langen body Layout pathapp-directory/css-in-js{children}/Layout /body /html ) }注意getMetadata定义于 index.tsx会自动把标题规范为标题 - Vercel Examples的格式并透传 description与 App Router 的export const metadata约定无缝衔接。页面内的组件组合从布局到内容接入全局外壳后示例页面内部通常按Page容器 →Text标题/段落 →List列表 →Snippet代码块 →Button交互的结构组织。以 edge-middleware/ab-testing-simple/pages/index.tsx 开头几行为例import { Layout, Page, Text, Link, List } from vercel/examples-ui // ... Page Text varianth1 classNamemb-6 {/* 页面主标题 */} /Text Text classNamemb-4 {/* 说明文字 */} /Text {/* ... */} /Page几个常用组件的关键行为可以从源码确认Buttonbutton.tsxvariant支持primary/secondary/ghost/violet/black/white六种size支持sm/md/lg通过泛型化的Component属性可渲染为button或a如DeployButton即用Componenta输出链接loading为 true 时内部渲染三点LoadingDots动画。Linklink.tsx默认包装next/link支持componenta降级为原生锚点用于 Multi Zones 等跨应用场景secondary控制灰阶配色还通过任意值选择器[_code]保证了行内代码的链接配色一致性。Texttext.tsxh1对应 5xl 加粗、h2对应 4xl、description对应灰阶描述文本、smallText对应蓝色小字标签。Snippet/Codesnippet.tsx、code.tsxSnippet提供带边框背景的代码块Code提供带反引号视觉的行内代码。DeployButtondeploy-button.tsx根据repositoryUrl、projectName、repositoryName、env等参数拼装 Vercel Clone 链接渲染为 Clone Deploy 按钮。为组件库做贡献本地构建与热更新如果你希望修改组件库本身并在本地示例中即时验证文档给出了一套完整的开发流程1. 构建产物在仓库根目录安装依赖后执行pnpm build2. 监听模式进入本目录internal/packages/ui并在终端运行pnpm build:swc -wpnpm build:swc对应 package.json 中的swc src -d dist --copy-files见 package.json即用 SWC 把src编译到dist并复制非 JS 资源如globals.css、tailwind.cjs-w开启文件监听改动即时增量编译。3. 在示例中链接本地包修改包后可在任意示例中用 npm 直接安装刚打包出的 tarballnpm i $(npm pack ../../internal/packages/ui | tail -1)注意请确保internal/packages/ui下的依赖已安装否则符号链接将无法解析导入。4. 创建 changeset当修改需要发布版本时运行pnpm changeset这与仓库根目录的 monorepo 协作规范一致本包位于internal/packages工作区相关脚本见 internal/packages/package.json变更记录可参考 internal/packages/ui/CHANGELOG.md。小结vercel/examples-ui的价值在于把示例该长什么样沉淀成一个可安装、可复用、可贡献的包通过 Tailwind preset 注入设计令牌通过globals.css提供基础样式通过Layout/getLayout/getMetadata统一页面外壳与元数据再配合Button/Text/Page等原子组件让仓库中每一个示例都能以最小成本获得一致的观感。对开发者而言无论你的示例跑在 App Router 还是 Pages Router 上只需按本文五步配置即可快速复用整套示例 UI 能力。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考