Next.js 14+、Tailwind CSS 3.4和TypeScript的样板和启动器。

🚀 支持App Router的Next.js、Tailwind CSS和TypeScript的样板和启动器 ⚡️ 首先优先考虑开发者体验：Next.js、TypeScript、ESLint、Prettier、Husky、Lint-Staged、Jest（由Vitest替代）、Testing Library、Commitlint、VSCode、PostCSS、Tailwind CSS、使用Clerk进行身份验证、使用DrizzleORM的数据库（PostgreSQL、SQLite和MySQL）、使用Sentry进行错误监控、使用Pino.js进行日志记录和日志管理、代码即监控、Storybook、多语言（i18n）等。为Next.js 15做好准备。

克隆此项目并用它创建你自己的Next.js项目。你可以查看Next.js模板演示。

赞助商




在此添加您的logo

特点

首先考虑开发者体验，代码结构极其灵活，只保留您所需要的内容：

⚡ 支持 App Router 的 Next.js
🔥 使用 TypeScript 进行类型检查
💎 集成 Tailwind CSS
✅ TypeScript 和 React 18 的严格模式
🔒 使用 Clerk 进行身份认证：注册、登录、登出、忘记密码、重置密码等
👤 无密码身份认证，包括魔法链接、多因素认证（MFA）、社交认证（Google、Facebook、Twitter、GitHub、Apple 等）、使用密钥的无密码登录、用户模拟
📦 使用 DrizzleORM 的类型安全 ORM，兼容 PostgreSQL、SQLite 和 MySQL
🌐 使用 next-intl 和 Crowdin 实现多语言支持（i18n）
♻️ 使用 T3 Env 实现类型安全的环境变量
⌨️ 使用 React Hook Form 处理表单
🔴 使用 Zod 进行验证
📏 使用 ESLint 进行代码检查（默认 Next.js、Next.js Core Web Vitals、Tailwind CSS 和 Airbnb 配置）
💖 使用 Prettier 进行代码格式化
🦊 使用 Husky 进行 Git Hooks
🚫 使用 Lint-staged 对 Git 暂存文件运行 linter
🚓 使用 Commitlint 检查 git 提交
📓 使用 Commitizen 编写符合标准的提交信息
🦺 使用 Vitest 和 React Testing Library 进行单元测试
🧪 使用 Playwright 进行集成和端到端测试
👷 使用 GitHub Actions 在拉取请求时运行测试
🎉 使用 Storybook 进行 UI 开发
🚨 使用 Sentry 进行错误监控
☂️ 使用 Codecov 进行代码覆盖率测试
📝 使用 Pino.js 进行日志记录，使用 Better Stack 进行日志管理
🖥️ 使用 Checkly 进行代码监控
🎁 使用 Semantic Release 自动生成更新日志
🔍 使用 Percy 进行视觉测试（可选）
💡 使用 @ 前缀进行绝对导入
🗂 VSCode 配置：调试、设置、任务和扩展
🤖 SEO 元数据、JSON-LD 和 Open Graph 标签
🗺️ Sitemap.xml 和 robots.txt
⌘ 使用 Drizzle Studio 进行数据库探索，使用 Drizzle Kit 进行 CLI 迁移工具
⚙️ Bundler Analyzer
🌈 包含免费的极简主题
💯 最大化 Lighthouse 得分

Next.js 内置功能：

☕ 压缩 HTML 和 CSS
💨 实时重载
✅ 缓存破坏

理念

对你来说没有隐藏的内容，你可以自由进行必要的调整以满足你的需求和偏好
每月更新依赖
易于定制
代码最小化
SEO 友好
🚀 生产就绪

要求

Node.js 20+ 和 npm

开始使用

在本地环境中运行以下命令：

git clone --depth=1 https://github.com/ixartz/Next-js-Boilerplate.git my-project-name
cd my-project-name
npm install

请注意，所有依赖项每月都会更新。

然后，你可以通过执行以下命令在开发模式下本地运行项目，并启用实时重载：

npm run dev

使用你喜欢的浏览器打开 http://localhost:3000 查看你的项目。

设置身份认证

在 Clerk.com 创建一个 Clerk 账户，并在 Clerk 仪表板中创建一个新应用。然后，将 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 和 CLERK_SECRET_KEY 复制到 .env.local 文件中（该文件不会被 Git 跟踪）：

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_pub_key
CLERK_SECRET_KEY=your_clerk_secret_key

现在，你有了一个与 Next.js 完全集成的身份认证系统：注册、登录、登出、忘记密码、重置密码、更新个人资料、更新密码、更新邮箱、删除账户等。

设置远程数据库

该项目使用 DrizzleORM，这是一个类型安全的 ORM，兼容 PostgreSQL、SQLite 和 MySQL 数据库。默认情况下，该项目设置为与 PostgreSQL 无缝协作，你可以轻松选择任何 PostgreSQL 数据库提供商。

翻译（i18n）设置

对于翻译，该项目使用 next-intl 结合 Crowdin。作为开发者，你只需要关注英语（或其他默认语言）版本。其他语言由 Crowdin 自动生成和处理。你可以使用 Crowdin 与翻译团队协作，或在机器翻译的帮助下自行翻译消息。

要设置翻译（i18n），请在 Crowdin.com 创建一个账户并创建一个新项目。在新创建的项目中，你将能够找到项目 ID。你还需要通过进入账户设置 > API 来创建一个新的个人访问令牌。然后，在你的 GitHub Actions 中，你需要定义以下环境变量：CROWDIN_PROJECT_ID 和 CROWDIN_PERSONAL_TOKEN。

在 GitHub Actions 中定义环境变量后，每次你向 main 分支推送新的提交时，你的本地化文件都会与 Crowdin 同步。

项目结构

.
├── README.md                       # README 文件
├── .github                         # GitHub 文件夹
├── .husky                          # Husky 配置
├── .storybook                      # Storybook 文件夹
├── .vscode                         # VSCode 配置
├── migrations                      # 数据库迁移
├── public                          # 公共资源文件夹
├── scripts                         # 脚本文件夹
├── src
│   ├── app                         # Next JS App（App Router）
│   ├── components                  # React 组件
│   ├── libs                        # 第三方库配置
│   ├── locales                     # 本地化文件夹（i18n 消息）
│   ├── models                      # 数据库模型
│   ├── styles                      # 样式文件夹
│   ├── templates                   # 模板文件夹
│   ├── types                       # 类型定义
│   ├── utils                       # 实用工具文件夹
│   └── validations                 # 验证模式
├── tests
│   ├── e2e                         # 端到端测试，也包括代码监控
│   └── integration                 # 集成测试
├── tailwind.config.js              # Tailwind CSS 配置
└── tsconfig.json                   # TypeScript 配置

自定义

你可以通过在整个项目中搜索 FIXME: 来轻松配置 Next.js Boilerplate，以进行快速自定义。以下是一些最重要的文件进行自定义：

public/apple-touch-icon.png、public/favicon.ico、public/favicon-16x16.png 和 public/favicon-32x32.png：你的网站图标，可以从 https://favicon.io/favicon-converter/ 生成
src/utils/AppConfig.ts：配置文件
src/templates/BaseTemplate.tsx：默认主题
next.config.mjs：Next.js 配置
.env：默认环境变量如果您需要进一步定制，可以访问完整的代码源。提供的代码仅是供您开始项目的示例。天空才是极限 🚀。

提交消息格式

该项目遵循约定式提交规范。这意味着所有提交消息必须按照规范格式化。为了帮助您编写提交消息，项目使用Commitizen，这是一个交互式CLI，可以指导您完成提交过程。要使用它，请运行以下命令：

npm run commit

使用约定式提交的一个好处是它允许我们自动生成CHANGELOG文件。它还允许我们根据发布中包含的提交类型自动确定下一个版本号。

测试

所有单元测试都与源代码位于同一目录中，这使得找到它们更容易。该项目使用Vitest和React Testing Library进行单元测试。您可以使用以下命令运行测试：

npm run test

集成和端到端测试

该项目使用Playwright进行集成和端到端测试。您可以使用以下命令运行测试：

npx playwright install # 仅在新环境中首次运行时需要
npm run test:e2e

启用Edge运行时（可选）

App Router文件夹与Edge运行时兼容。您可以通过在src/app/layouts.tsx中添加以下行来启用它：

export const runtime = 'edge';

请注意，数据库迁移与Edge运行时不兼容。因此，您需要在src/libs/DB.ts中禁用自动迁移：

await migrate(db, { migrationsFolder: './migrations' });

禁用后，您需要手动运行迁移：

npm run db:migrate

每次更新数据库架构时，您也需要运行此命令。

部署到生产环境

在构建过程中，会自动执行数据库迁移。因此，您无需手动运行迁移。但是，在您的环境变量中，需要定义DATABASE_URL。

然后，您可以使用以下命令生成生产构建：

$ npm run build

这会生成经过优化的样板生产构建。要测试生成的构建，您可以运行：

$ npm run start

您还需要使用自己的密钥定义环境变量CLERK_SECRET_KEY。

该命令启动一个带有生产构建的本地服务器。然后，您可以使用您喜欢的浏览器打开http://localhost:3000来查看项目。

错误监控

该项目使用Sentry进行错误监控。对于开发环境，您无需做任何事情：Next.js Boilerplate已经配置为使用Sentry和Spotlight（Sentry的开发版本）。所有错误都会自动发送到您的本地Spotlight实例。因此，您可以在本地尝试Sentry体验。

对于生产环境，您需要创建一个Sentry账户并创建一个新项目。然后，在next.config.mjs中，您需要更新withSentryConfig函数中的org和project属性。您还需要在sentry.client.config.ts、sentry.edge.config.ts和sentry.server.config.ts中添加您的Sentry DSN。

代码覆盖率

Next.js Boilerplate依赖于Codecov作为代码覆盖率报告解决方案。要使用Codecov，请创建一个Codecov账户并将其连接到您的GitHub账户。在您的Codecov仪表板上，应该显示您的仓库列表。选择您要为其启用Codecov的仓库并复制令牌。然后，在您的GitHub Actions中，您需要定义CODECOV_TOKEN环境变量并粘贴您复制的令牌。

请确保将CODECOV_TOKEN创建为GitHub Actions密钥，不要直接将其粘贴到源代码中。

日志记录

该项目使用Pino.js进行日志记录。默认情况下，对于开发环境，日志显示在控制台中。

对于生产环境，该项目已经集成了Better Stack，以使用SQL管理和查询您的日志。要使用Better Stack，您需要创建一个Better Stack账户并创建一个新的源：转到您的Better Stack Logs仪表板 > 源 > 连接源。然后，您需要为您的源命名并选择Node.js作为平台。

创建源后，您将能够看到您的源令牌并复制它。然后，在您的环境变量中，您可以将令牌粘贴到LOGTAIL_SOURCE_TOKEN变量中。现在，所有日志都会自动发送并由Better Stack摄取。

Checkly监控

该项目使用Checkly来确保您的生产环境始终正常运行。Checkly会定期运行以*.check.spec.ts扩展名结尾的测试，并在任何测试失败时通知您。此外，您可以灵活地在多个位置执行测试，以确保您的应用程序在全球范围内可用。

要使用Checkly，您必须首先在他们的网站上创建一个账户。一旦您有了账户，您可以在GitHub Actions中设置CHECKLY_API_KEY环境变量，方法是在Checkly仪表板中生成一个新的API密钥。此外，您还需要定义CHECKLY_ACCOUNT_ID，这也可以在Checkly仪表板的用户设置 > 常规中找到。

要完成设置，请确保更新checkly.config.ts文件，使用您自己的电子邮件地址和生产URL。