使用21st.dev网站组件的方法

使用21st.dev网站的组件方法

21st.dev 是一个开源的 React UI 组件市场，专门为设计工程师和前端开发者提供高质量的 UI 组件。它的灵感来自于 shadcn/ui，旨在帮助开发者快速构建精美的用户界面，尤其适用于 AI 产品的开发。21st.dev 目前已经托管了海量开源组件，类型涵盖各种极具设计感(由官方审核)头像、dialog、按钮、日历，甚至完整 Page，应有尽有，并且这些组件都经过 21st.dev 官方审核，质量上还是比较有保证的。下面讲一下怎么把21st.dev上的组件加入自己项目。

点击复制你想使用的组件页面的Installation的命令，以使用npx shadcn@latest add https://21st.dev/r/shadcnblockscom/contact-2 为例

下面是一份在 Vite React 项目中使用这条命令前需要完成的准备清单。

1. 确认项目基础环境

确保当前项目是一个可运行的 Vite React 项目，并且已经安装了基本依赖。

2. 安装 Tailwind 相关依赖

先安装 shadcn 常用的样式基础包：

npm install -D tailwindcss@3.4.17 postcss autoprefixer tailwindcss-animate

如果后续组件需要，也会安装这些常用依赖：

npm install clsx tailwind-merge lucide-react

下面是完整且可直接复制的命令（含 shadcn 推荐依赖）：

# 安装 Tailwind 及 PostCSS
npm install -D tailwindcss@3.4.17 postcss autoprefixer tailwindcss-animate

# 常用 runtime 工具
npm install clsx tailwind-merge lucide-react

# 可选：Radix / cva 等（按需添加）
npm install @radix-ui/react-checkbox @radix-ui/react-slot class-variance-authority

3. 创建 Tailwind 配置

在项目根目录新增 tailwind.config.cjs，并配置：

• 扫描范围指向 index.html 和 src/**/*.{js,jsx,ts,tsx}
• 开启 darkMode: ['class']
• 增加 tailwindcss-animate 插件
• 定义 shadcn 常用的颜色变量和圆角变量

示例 tailwind.config.cjs（可直接复制）：

const plugin = require('tailwindcss/plugin')
module.exports = {
	content: [
		'./index.html',
		'./src/**/*.{js,jsx,ts,tsx}'
	],
	darkMode: ['class'],
	theme: {
		extend: {
			colors: {
				// 示例：按需替换成你的设计色
				primary: 'var(--shadcn-primary)',
			},
			borderRadius: {
				lg: 'var(--radius-lg, 0.5rem)'
			}
		}
	},
	plugins: [require('tailwindcss-animate')]
}

4. 创建 PostCSS 配置

在项目根目录新增 postcss.config.cjs，内容包含：

• tailwindcss
• autoprefixer

示例 postcss.config.cjs：

module.exports = {
	plugins: {
		tailwindcss: {},
		autoprefixer: {}
	}
}

5. 配置全局样式入口

在 src/index.css 中加入 Tailwind 指令：

• @tailwind base;
• @tailwind components;
• @tailwind utilities;

同时补上 shadcn 需要的 CSS 变量和基础样式。

示例 src/index.css（保留并在此基础上扩展）：

@tailwind base;
@tailwind components;
@tailwind utilities;

:root{
	--shadcn-primary: 255 99 71; /* 或者使用 rgba/hex */
	--radius-lg: 0.5rem;
}

/* shadcn 常用基础样式示例 */
.container { @apply max-w-3xl mx-auto px-4 }

/* 其他按需扩展 */

6. 配置路径别名

在 vite.config.js 里把 @ 指向 src，例如：

• @/components
• @/lib/utils

这样 shadcn CLI 才能正确识别组件路径。

示例 vite.config.js 片段：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
	resolve: {
		alias: {
			'@': path.resolve(__dirname, 'src')
		}
	},
	plugins: [react()]
})

7. 增加 jsconfig.json 或 tsconfig.json

如果项目是 JavaScript 项目，建议新增 jsconfig.json，配置：

• baseUrl: "."
• paths: { "@/*": ["./src/*"] }

这样编辑器和 shadcn CLI 都能识别别名。

示例 jsconfig.json（JavaScript 项目使用）：

{
	"compilerOptions": {
		"baseUrl": ".",
		"paths": {
			"@/*": ["./src/*"]
		}
	},
	"exclude": ["node_modules"],
	"ignoreDeprecations": "6.0"
}

8. 创建 components.json

在项目根目录新增 components.json，告诉 shadcn：

• Tailwind 配置文件位置
• CSS 入口文件位置
• 别名规则
• 使用的样式风格

示例 components.json（shadcn CLI 用）：

{
	"tailwind": "./tailwind.config.cjs",
	"css": "src/index.css",
	"aliases": {
		"components": "@/components",
		"ui": "@/components/ui",
		"lib": "@/lib"
	}
}

9. 创建工具函数文件

在 src/lib/utils.js 中新增 cn()，通常写法是：

• 用 clsx 处理类名组合
• 用 tailwind-merge 合并冲突类名

示例 src/lib/utils.js：

import clsx from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs) {
	return twMerge(clsx(...inputs))
}

10. 执行 shadcn 添加命令

准备完成后运行：

npx shadcn@latest add https://21st.dev/r/shadcnblockscom/contact-2

命令运行示例（交互式）：

# 运行并按提示选择要生成的组件
npx shadcn@latest add https://21st.dev/r/shadcnblockscom/contact-2

第一次运行时，CLI 可能会：

• 安装 shadcn
• 让你确认组件库和 preset
• 检查 Tailwind 和路径别名

11. 检查生成结果

命令成功后，通常会生成：

• src/components/ui/*
• 页面主组件文件

然后可以直接在 src/App.jsx 中引用并使用。具体引用方式按照How to use中的代码

12. 验证构建

最后运行构建命令确认项目可用：

npm run build

本地运行（开发时）可使用：

npm run dev

快速总结

这条命令能顺利执行的前提是：

• Tailwind 已安装并配置完成
• @ 路径别名可用
• components.json 已存在
• src/lib/utils.js 已准备好

只要这几项都完成，npx shadcn@latest add ... 就可以正常生成组件。