npm package: @goozyshi/start-kit
Description: Start Kit - 零配置的页面导航与模板生成工具
Author: goozyshi
Latest version: 1.0.9

<div align="center">

# Start Kit

**🚀 零配置的 Vite + Vue3 多页面开发仪表盘**

---

## ✨ 核心功能

### 🔍 智能页面扫描

- 自动识别 `src/page`、`src/pages`、`src/views`、`pages` 等常见目录
- 实时检测 Vue 和 Vite 版本
- 支持三级目录结构可视化展示

### 🎨 快速页面生成

- **零配置** - 开箱即用的页面模板
- **多级目录** - 支持 `page-name` 或 `2025/11` 等嵌套路径
- **灵活多语言** - 自由选择 English / العربية / Türkçe 任意组合
- **实时预览** - 输入页面名称时即时显示生成路径
- **CSS 安全** - 自动处理数字开头的页面名（如 `2025`），生成 `.page-2025` 避免样式错误

### 📡 开发体验

- **服务器状态检测** - 实时显示主项目开发服务器运行状态
- **一键跳转** - 点击页面名直接在新标签页打开
- **热更新列表** - 创建新页面后自动刷新仪表盘

---

## 🚀 快速开始

### 安装

```bash
# 使用 npm
npm install start-kit --save-dev
npm install start-kit -D --legacy-peer-deps


# 使用 yarn
yarn add start-kit -D

# 使用 pnpm
pnpm add start-kit -D
```

### 添加启动脚本

在项目的 `package.json` 中添加：

```json
{
  "scripts": {
    "dashboard": "start-kit"
  }
}
```

### 启动仪表盘

```bash
npm run dashboard
```

**就这么简单！** 🎉 仪表盘会自动：

- 扫描项目中的所有页面
- 启动可视化界面（默认端口 8080）
- 自动在浏览器打开

---

## 📖 使用指南

### CLI 命令

Start Kit 命令：

```bash
start-kit [options]   # 启动仪表盘
```

**可用选项：**

| 选项            | 说明             | 默认值 |
| --------------- | ---------------- | ------ |
| `--port <port>` | 指定端口号       | `8080` |
| `--no-open`     | 不自动打开浏览器 | -      |
| `--help, -h`    | 显示帮助信息     | -      |
| `--version, -v` | 显示版本号       | -      |

**示例：**

```bash
# 使用默认配置启动
start-kit

# 指定端口
start-kit --port 3000

# 不自动打开浏览器
start-kit --no-open

# 指定端口并静默启动
start-kit --port 9000 --no-open
```

### 同时启动仪表盘和开发服务器

在 `package.json` 中添加组合命令：

```json
{
  "scripts": {
    "dev": "vite",
    "dashboard": "start-kit",
    "dev:all": "npm run dashboard & npm run dev"
  }
}
```

然后运行：

```bash
npm run dev:all
```

仪表盘会检测主项目服务器状态并显示在右上角 🟢。

---

## 🎨 创建新页面

### 步骤

1. 点击左侧导航底部的 **"➕ 创建新页面"** 按钮
2. 填写表单：

| 字段           | 说明                              | 示例                                           |
| -------------- | --------------------------------- | ---------------------------------------------- |
| **页面名称**   | 支持单级或多级目录，使用 `/` 分隔 | `honor-wall`<br>`2025/11`<br>`activity/spring` |
| **选择模板**   | 当前支持 SoulStar 模板            | `SoulStar模板`                                 |
| **多语言配置** | 勾选需要的语言（默认全选）        | ☑️ English<br>☑️ العربية<br>☑️ Türkçe          |

3. 查看 **生成路径预览**，确认无误
4. 点击 **"创建页面"**

### 生成的文件结构

```
src/page/{pageName}/
├── index.html              # 页面入口 HTML
├── main.ts                 # Vue 应用初始化
├── lang.ts                 # i18n 多语言配置（根据选择的语言生成）
├── router/
│   └── index.ts            # Vue Router 配置
├── pages/
│   ├── App.vue             # 根组件（包含路由出口）
│   └── Home.vue            # 主页面组件
├── api/
│   └── index.ts            # API 接口定义
└── assets/
    └── css/
        └── common.scss     # 通用样式变量
```

---

## 📦 模板结构

### SoulStar 模板特性

当前提供的 SoulStar 模板包含以下技术栈和特性：

#### 🛠️ 技术栈

- ✅ **Vue 3** - Composition API + `<script setup>` 语法
- ✅ **TypeScript** - 完整的类型支持
- ✅ **Vue Router** - 单页应用路由
- ✅ **Vue I18n** - 国际化多语言（单文件格式）
- ✅ **Vant 4** - 移动端 UI 组件库
- ✅ **SCSS** - CSS 预处理器

#### 🎯 特性

- ✅ **HeaderV2 顶部导航** - 统一的页面头部组件
- ✅ **CSS 变量系统** - 主题色、字体、尺寸等统一管理
- ✅ **RTL 布局支持** - 阿语自动适配（postcss-rtlcss）
- ✅ **响应式设计** - 移动端优先的布局
- ✅ **类型安全** - TypeScript 严格模式

#### 🌍 支持的语言

| 语言代码 | 语言名称 | 说明                 |
| -------- | -------- | -------------------- |
| `en`     | English  | 英语（默认）         |
| `ar`     | العربية  | 阿拉伯语（支持 RTL） |
| `tr`     | Türkçe   | 土耳其语             |

**多语言配置示例：**

生成的 `lang.ts` 文件格式：

```typescript
const allLang = {
  en: {
    title: "MyPage",
    welcome: "Welcome to MyPage",
    description: "This is a template page generated by Start Kit.",
    start_building: "Start building your page here.",
  },
  ar: {
    title: "MyPage",
    welcome: "مرحباً بك في MyPage",
    description: "هذه صفحة قالب تم إنشاؤها بواسطة Start Kit.",
    start_building: "ابدأ في بناء صفحتك هنا.",
  },
  tr: {
    title: "MyPage",
    welcome: "MyPage'e hoş geldiniz",
    description: "Bu, Start Kit tarafından oluşturulan bir şablon sayfasıdır.",
    start_building: "Sayfanızı burada oluşturmaya başlayın.",
  },
};

export default allLang satisfies AllLang<(typeof allLang)["en"]>;
```

---

## 📋 环境要求

| 依赖             | 版本要求                 |
| ---------------- | ------------------------ |
| **Node.js**      | >= 14.18.0               |
| **Vue**          | ^3.0.0                   |
| **Vite**         | ^3.0.0                   |
| **Element Plus** | ^2.0.0 _(用于仪表盘 UI)_ |

---

## 🎯 适用场景

Start Kit 特别适合以下项目类型：

- ✅ **Vite + Vue3 多页面应用 (MPA)**
- ✅ **需要管理多个独立页面/活动页**
- ✅ **多语言国际化项目（尤其是包含 RTL 语言）**
- ✅ **快速迭代的营销活动页面**
- ✅ **组件库或设计系统的演示页面**

---

## 💡 常见问题

### 1. 仪表盘提示 "未找到页面目录"

**原因：** 项目中不存在 Start Kit 识别的页面目录。

**解决方案：**

- 确保项目中存在以下目录之一：

  - `src/page`
  - `src/pages`
  - `src/views`
  - `pages`

- 或在项目根目录创建 `vite-dashboard.config.js` 自定义页面目录：

```javascript
module.exports = {
  pageDir: "src/custom-pages", // 自定义路径
};
```

### 2. 服务器状态显示 "未运行"

**说明：** 仪表盘会检测主项目开发服务器（默认端口 8084）。

**解决方案：**

- 启动主项目开发服务器：`npm run dev`
- 或使用组合命令：`npm run dev:all`

### 3. 创建页面后列表不更新

**说明：** 页面创建成功后会自动刷新列表。

**如果未自动刷新：**

1. 手动刷新浏览器页面
2. 检查控制台是否有错误信息
3. 确认页面文件已成功生成到目标目录

### 4. 如何自定义模板？

**当前版本：** 仅支持内置的 SoulStar 模板。

**未来版本计划：** 将支持自定义模板配置。

如有定制需求，请提交 [Issue](https://github.com/goozyshi/start-kit/issues)。

---

## 📦 发布到 NPM

### 准备工作

确认以下检查清单：

```bash
# 1. 检查依赖是否安装完整
npm install

# 2. 更新版本号（根据变更类型选择）
npm version patch   # 修复 bug: 1.0.0 -> 1.0.1
npm version minor   # 新增特性: 1.0.0 -> 1.1.0
npm version major   # 破坏性变更: 1.0.0 -> 2.0.0

# 3. 预览即将发布的文件
npm pack --dry-run
```

### 发布到 NPM

```bash
# 登录 NPM（首次需要）
npm login

# 发布
npm publish

# 如果是测试包，使用
npm publish --tag beta
```

### ⚠️ 发布注意事项

- ✅ 本包采用**源码发布**，无需构建步骤
- ✅ UI 界面由 Vite 在运行时编译，确保兼容性
- ✅ 所有依赖（包括 Vue 和 Element Plus）已打包在内，用户无需额外安装
- ✅ `.npmignore` 已配置，确保不发布 `.git`、`node_modules` 等

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

**如何贡献：**

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📝 开源协议

[MIT](https://github.com/goozyshi/start-kit/blob/main/LICENSE) License © 2025 [goozyshi](https://github.com/goozyshi)

---

## 🔗 相关链接

- 📦 [GitHub 仓库](https://github.com/goozyshi/start-kit)
- 📮 [NPM 包](https://www.npmjs.com/package/start-kit)
- 🐛 [提交 Issue](https://github.com/goozyshi/start-kit/issues)
- 💬 [讨论区](https://github.com/goozyshi/start-kit/discussions)

---

<div align="center">

**Made with ❤️ by [goozyshi](https://github.com/goozyshi)**

如果这个项目对你有帮助，请给个 ⭐️ Star 支持一下！

</div>