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 避免样式错误

📡 开发体验

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

🚀 快速开始

安装

# 使用 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 中添加：

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

启动仪表盘

npm run dashboard

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

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

📖 使用指南

CLI 命令

Start Kit 命令：

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

可用选项：

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

示例：

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

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

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

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

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

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

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

然后运行：

npm run dev:all

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

🎨 创建新页面

步骤

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

| 字段 | 说明 | 示例 | | -------------- | --------------------------------- | ---------------------------------------------- | | 页面名称 | 支持单级或多级目录，使用 / 分隔 | honor-wall2025/11activity/spring | | 选择模板 | 当前支持 SoulStar 模板 | SoulStar模板 | | 多语言配置 | 勾选需要的语言（默认全选） | ☑️ English☑️ العربية☑️ 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 文件格式：

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 自定义页面目录：

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

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

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

解决方案：

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

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

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

如果未自动刷新：

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

4. 如何自定义模板？

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

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

如有定制需求，请提交 Issue。

📦 发布到 NPM

准备工作

确认以下检查清单：

# 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

# 登录 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 License © 2025 goozyshi

🔗 相关链接

• 📦 GitHub 仓库
• 📮 NPM 包
• 🐛 提交 Issue
• 💬 讨论区

Made with ❤️ by goozyshi

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