@zw-team/create-app

一个用于快速创建 React 项目模板的 CLI 工具，支持从 GitLab 私有仓库动态下载模板。

功能特性

• 🚀 快速创建 React 项目模板
• 📦 支持 JSX 和 TSX 两种模板类型
• 🎯 交互式命令行界面
• 📁 自动创建项目目录并初始化模板
• 🔄 自动检查模板更新，确保使用最新版本
• 💾 智能缓存机制，提升下载速度
• 🔒 支持 GitLab 私有仓库（通过 Token 认证）

安装

npm install -g @zw-team/create-app
# 或
pnpm add -g @zw-team/create-app
# 或
yarn global add @zw-team/create-app

使用方法

基本用法

# 直接运行（推荐）
npx @zw-team/create-app

# 或指定模板类型
npx @zw-team/create-app --template react

参数说明

• --force: 强制重新下载模板，忽略缓存

环境变量配置

如果使用私有 GitLab 仓库，需要配置以下环境变量：

# GitLab Personal Access Token（必需，用于访问私有仓库）
export GITLAB_TOKEN=your_personal_access_token

# 模板仓库地址（可选，默认使用内置地址）
export TEMPLATE_REPO=https://git.wozhangwan.com/frontend/frontend-demo

# 模板分支（可选，默认根据 flavor 自动选择）
export TEMPLATE_BRANCH=master

获取 GitLab Token：

1. 登录 GitLab
2. 进入 Settings → Access Tokens
3. 创建 Personal Access Token，权限选择 read_repository
4. 复制 token 并设置为环境变量

交互流程

1. 输入项目名称（必填）

   • 工具会提示你输入项目名称
   • 项目名称不能为空
   • 如果目标文件夹已存在且不为空，会提示错误

2. 选择模板类型

   • TSX: TypeScript + React 模板（从 template-tsx-demo 分支下载）
   • JSX: JavaScript + React 模板（从 template-jsx-demo 分支下载）

3. 自动下载和创建项目

   • 工具会自动检查缓存
   • 如果缓存存在且是最新版本，使用缓存
   • 如果检测到远程仓库有更新，自动下载最新版本
   • 复制模板文件到项目目录
   • 更新 package.json 中的项目名称

使用示例

基本使用

# 创建 React 项目
npx @zw-team/create-app

# 交互式流程示例：
# 请输入项目名称: my-react-app
# 请选择 React 模板类型:
#   ❯ TSX
#     JSX

使用私有仓库

# 设置 GitLab Token
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx

# 运行 CLI
npx @zw-team/create-app

强制重新下载

# 忽略缓存，强制重新下载最新模板
npx @zw-team/create-app --force

一行命令（带环境变量）

GITLAB_TOKEN=your_token npx @zw-team/create-app

模板说明

模板分支映射

• TSX: 从 template-tsx-demo 分支下载
• JSX: 从 template-jsx-demo 分支下载

React JSX 模板

• 使用 JavaScript + JSX
• 包含完整的项目结构和配置
• 支持路由、状态管理、API 请求等功能

React TSX 模板

• 使用 TypeScript + TSX
• 包含完整的类型定义
• 提供更好的类型安全和开发体验

缓存机制

缓存位置

模板缓存存储在用户主目录下的隐藏文件夹：

~/.create-app/templates/react/{flavor}/

自动更新检查

• 每次使用时，工具会自动检查远程仓库是否有更新
• 通过比较远程分支的 commit hash 与缓存版本
• 如果检测到更新，会自动下载最新版本
• 如果无更新，使用缓存以提升速度

清理缓存

如果需要清理缓存，可以手动删除缓存目录：

# macOS/Linux
rm -rf ~/.create-app

# Windows
rmdir /s %USERPROFILE%\.create-app

或使用 --force 参数强制重新下载。

创建完成后

创建完成后，按照提示执行：

cd my-react-app
pnpm install
pnpm dev

注意事项

• ✅ 支持直接运行 npx @zw-team/create-app，无需指定 --template 参数
• ❌ 不支持位置参数（如 create-app vue 会报错）
• 🔒 私有仓库需要配置 GITLAB_TOKEN 环境变量
• 📦 模板使用 pnpm 作为包管理器
• 🔄 模板会自动检查更新，确保使用最新版本
• 💾 首次下载后会自动缓存，后续使用更快

项目结构

创建的项目包含以下主要目录：

my-react-app/
├── src/
│   ├── api/          # API 接口
│   ├── components/   # 组件
│   ├── hooks/        # 自定义 Hooks
│   ├── router/       # 路由配置
│   ├── store/        # 状态管理
│   ├── utils/        # 工具函数
│   └── views/        # 页面视图
├── .cursor/          # Cursor 编辑器配置
├── .husky/           # Git hooks
├── .vscode/          # VSCode 配置
└── package.json      # 项目配置

常见问题

Q: 下载失败，提示需要认证？

A: 请设置 GITLAB_TOKEN 环境变量：

export GITLAB_TOKEN=your_token

Q: 如何强制使用最新模板？

A: 使用 --force 参数：

npx @zw-team/create-app --force

Q: 模板更新后，会自动获取最新版本吗？

A: 是的，工具会自动检查远程仓库更新。如果检测到更新，会自动下载最新版本。

Q: 可以自定义模板仓库地址吗？

A: 可以，通过环境变量 TEMPLATE_REPO 配置：

export TEMPLATE_REPO=https://your-gitlab.com/your/repo

Q: 缓存在哪里？如何清理？

A: 缓存位置：~/.create-app/templates/。可以手动删除该目录或使用 --force 参数。

版本

当前版本：0.1.0