@beater/nextjs-template

v0.1.0

Published

7 months ago

This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).

Downloads

0High
0Medium
0Low

beater

This is a Next.js project bootstrapped with create-next-app.

🚀 一键脚手架安装

需要 Node.js >= 18。
推荐使用 npm create 或 npx 直接拉起脚手架，无需预装。

创建项目

# 使用 npm create（推荐）
npm create @beater/nextjs-template@latest my-app

# 或使用 npx
npx @beater/nextjs-template@latest my-app

# 指定包管理器并跳过自动安装
npm create @beater/nextjs-template@latest my-app -- --pm pnpm --no-install

脚手架会：

生成新目录且不会修改当前目录
将 package.json 的 name 设置为你的项目名，并保持 private: true
保留 .env.example、.gitignore 等必要模板文件
支持自动选择/指定包管理器安装依赖（--pm），用 --no-install 可跳过安装

本地快速验证

pnpm run smoke:scaffold

该脚本会在临时目录生成一个脚手架项目并验证 package.json 是否写入成功（默认跳过依赖安装）。

🛠️ 技术栈

本项目集成了以下主流技术栈和工具：

样式方案: Tailwind CSS - 高效的实用工具优先 CSS 框架
UI 组件库:
- shadcn/ui - 设计精美、可定制的组件库
- sonner - 优雅的 Toast 通知组件，完美适配 shadcn/ui
- motion - 强大的 React 动画库，支持手势和布局动画
接口通信: tRPC - 端到端类型安全的 API 层
性能监控: Sentry - 实时应用性能监控与错误追踪
国际化: next-intl - 完善的 Next.js 国际化解决方案
身份认证:
- NextAuth.js - 安全灵活的身份验证库
- @casl/ability - 灵活、类型安全的权限管理系统 ❌
数据库 ORM: Sequelize - 强大的 Node.js ORM 框架
工具库:
- lodash-es - 现代化的 JavaScript 实用工具库
- dayjs - 轻量级日期库（Day.js 的 API 与 Moment.js 兼容）
- axios - 流行的 Promise 基础的 HTTP 客户端
- zustand - 轻量级、简洁的状态管理库

💡 推荐增加的实用库

以下是根据项目需求，推荐增加的一些实用库：

📝 表单处理

react-hook-form - 高性能、灵活的 React 表单库，与 Zod 完美集成
@hookform/resolvers - react-hook-form 与 Zod 的集成解析器

🔔 通知提示

sonner - 优雅的 Toast 通知组件，完美适配 shadcn/ui
或 react-hot-toast - 轻量级、可定制的 Toast 通知库

📅 日期处理

date-fns - 现代化的日期工具库，体积小、功能强大
或 dayjs - 轻量级日期库（Day.js 的 API 与 Moment.js 兼容）

🎨 动画库

framer-motion - 强大的 React 动画库，支持手势和布局动画

📊 数据表格

@tanstack/react-table - 功能强大的表格库，支持排序、筛选、分页等

🔐 权限控制

@casl/ability - 灵活、类型安全的权限管理系统

🌐 HTTP 客户端（如果需要独立使用）

axios - 流行的 Promise 基础的 HTTP 客户端
或使用原生 fetch API（Next.js 已内置支持）

🗄️ 状态管理（如需要全局状态）

zustand - 轻量级、简洁的状态管理库
或 jotai - 基于原子化思想的 React 状态管理库

📤 文件上传

react-dropzone - 优雅的文件拖拽上传组件

🧪 测试工具

vitest - 快速的单元测试框架，兼容 Vite
@testing-library/react - React 组件测试工具
@testing-library/jest-dom - 扩展 Jest 的 DOM 匹配器

🔧 开发工具

prettier - ✅ 已安装，代码格式化工具
husky - ✅ 已安装，Git hooks 管理工具
@commitlint/cli - ✅ 已安装，提交信息规范检查
lint-staged - ✅ 已安装，对暂存文件运行 linters
dotenv - 环境变量管理（已有 next-intl，但 dotenv 更通用）

🗄️ 数据缓存/队列（后端增强）

ioredis - 强大的 Redis 客户端，支持集群和哨兵
bullmq - 基于 Redis 的现代任务队列系统

📈 图表可视化

recharts - 基于 React 和 D3 的图表库
或 chart.js + react-chartjs-2 - 功能丰富的图表库

📝 富文本编辑器

tiptap - 现代化的无头富文本编辑器框架
或 lexical - Meta 开源的富文本编辑器框架

🎯 虚拟滚动（大数据列表）

@tanstack/react-virtual - 高性能虚拟滚动库

🔍 搜索功能

fuse.js - 轻量级模糊搜索库
或 @typesense/typesense-js - 功能强大的搜索库

🌐 国际化增强

已有 next-intl，但可以考虑添加 date-fns/locale 用于日期本地化

📦 工具增强

zod - ✅ 已安装，用于运行时类型验证和 Schema 定义
class-validator - 类验证器（如使用类风格 API）
nanoid - 生成唯一 ID 的库（比 UUID 更小更快）

🔄 数据同步/实时

@trpc/client - ✅ 已安装，tRPC 支持 WebSocket，可用于实时数据
或独立的 WebSocket 客户端如 socket.io-client

📋 开发规范

本项目已配置完整的开发规范工具链，确保代码质量和提交规范。

已配置的工具

Husky - Git hooks 管理工具
Commitlint - 提交信息规范检查
Commitizen - 交互式提交工具，帮助生成规范化的提交信息
Prettier - 代码格式化工具
lint-staged - 对暂存文件运行检查

工作流程

1. 代码提交前自动检查

在提交代码时，会自动执行以下检查：

Pre-commit Hook: 自动运行 lint-staged，对暂存的文件进行：
- ESLint 检查和自动修复
- Prettier 格式化
Commit-msg Hook: 自动验证提交信息是否符合规范

2. 提交信息规范

本项目采用 Conventional Commits 规范：

<type>(<scope>): <subject>

<body>

<footer>

类型 (type) 必须是以下之一：

feat: 新功能
fix: 修复 bug
docs: 文档变更
style: 代码格式（不影响代码运行的变动）
refactor: 重构（既不是新增功能，也不是修改 bug 的代码变动）
perf: 性能优化
test: 增加测试
chore: 构建过程或辅助工具的变动
revert: 回滚
build: 打包
ci: 持续集成修改

示例：

feat: 添加用户登录功能

fix: 修复表单验证问题

docs: 更新 API 文档

style: 格式化代码

refactor: 重构用户服务模块

3. 提交代码

使用 pnpm commit 命令进行交互式提交，会自动引导您填写符合规范的提交信息：

# 1. 添加要提交的文件
git add .

# 2. 使用交互式提交命令
pnpm commit

pnpm commit 会引导您：

选择提交类型（feat、fix、docs 等）
填写提交主题
填写详细描述（可选）
填写 Breaking Changes（如有）
填写相关的 Issue（如有）

4. 可用命令

# 格式化所有代码
pnpm format

# 检查代码格式（不修改）
pnpm format:check

# 运行 ESLint 检查
pnpm lint

# 运行 ESLint 并自动修复
pnpm lint:fix

# 交互式提交代码（推荐）
pnpm commit

# 初始化 Husky（首次克隆项目后运行）
pnpm prepare

4. 首次设置

如果是首次克隆项目，需要初始化 Husky：

pnpm install
pnpm prepare

这会自动设置 Git hooks，确保提交时自动运行检查。

配置文件

.prettierrc.json - Prettier 格式化配置
.prettierignore - Prettier 忽略文件
commitlint.config.ts - Commitlint 提交信息规范配置
.husky/pre-commit - 提交前 Git hook
.husky/commit-msg - 提交信息验证 Git hook
package.json - lint-staged 配置

📦 发布脚手架到 npm

确认版本：npm version patch（或 minor/major）更新版本号。
预览即将发布的内容：npm pack --dry-run（确保 files 列表、bin 入口和模板文件齐全）。
登录 npm：npm login，确保 publishConfig.access 保持为 public。
发布：npm publish（需要 Node 18+）。
验证：在新终端运行 npm create @beater/nextjs-template@latest demo-app -- --no-install 验证脚手架是否可用。

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More

To learn more about Next.js, take a look at the following resources:

Next.js Documentation - learn about Next.js features and API.
Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.