create-modsemi 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# create-modsemi
+
+[English](#english) | [繁體中文](#繁體中文)
+
+---
+
+## English
+
+Scaffold a [ModSemi](https://github.com/your-username/modsemi) project in seconds.
+
+**ModSemi** is a React 19 + Modern.js + Semi Design admin template, similar to Ant Design Pro.
+
+### Usage
+
+```bash
+npm create modsemi@latest
+# or
+pnpm create modsemi
+# or
+yarn create modsemi
+# or
+npx create-modsemi
+```
+
+Optionally pass the project name directly:
+
+```bash
+npm create modsemi@latest my-app
+```
+
+The CLI will ask:
+
+1. **Project name** — used as the directory name and `package.json` name
+2. **API proxy target** — backend URL for local dev (written into `modern.config.ts`)
+3. **Enable Orval** — whether to include Orval API code generation + Swagger sample
+
+### What you get
+
+- React 19 + Modern.js 3.x + Semi Design 2.x (`@douyinfe/semi-ui-19`)
+- 4 layout modes: Side / Top / Mix / Double (default)
+- Auth system with Zustand persist
+- Role-based access control (`useAccess` + `<Access>`)
+- Dev proxy pre-configured (CORS-free local development)
+- Biome for lint + format
+- GitHub Actions CI (lint + build)
+- Optional: Orval API code generation from Swagger/OpenAPI
+
+### Requirements
+
+- Node.js >= 20
+- pnpm (recommended)
+
+---
+
+## 繁體中文
+
+幾秒鐘內快速建立一個 [ModSemi](https://github.com/your-username/modsemi) 專案。
+
+**ModSemi** 是基於 React 19 + Modern.js + Semi Design 的後台管理模板，類似於 Ant Design Pro。
+
+### 使用方式
+
+```bash
+npm create modsemi@latest
+# 或
+pnpm create modsemi
+# 或
+yarn create modsemi
+# 或
+npx create-modsemi
+```
+
+也可以直接傳入專案名稱：
+
+```bash
+npm create modsemi@latest my-app
+```
+
+CLI 會依序詢問：
+
+1. **專案名稱** — 作為目錄名稱與 `package.json` 的 name 欄位
+2. **API Proxy 目標** — 本地開發時的後端 URL（寫入 `modern.config.ts`）
+3. **啟用 Orval** — 是否加入 Orval API 程式碼生成及 Swagger 範例
+
+### 你會得到什麼
+
+- React 19 + Modern.js 3.x + Semi Design 2.x（`@douyinfe/semi-ui-19`）
+- 4 種版面模式：Side / Top / Mix / Double（預設）
+- 基於 Zustand persist 的身份驗證系統
+- 角色型存取控制（`useAccess` + `<Access>`）
+- 預配置的開發 Proxy（無 CORS 的本地開發環境）
+- Biome 進行 lint + 格式化
+- GitHub Actions CI（lint + build）
+- 可選：從 Swagger/OpenAPI 使用 Orval 生成 API 程式碼
+
+### 環境需求
+
+- Node.js >= 20
+- pnpm（建議使用）

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { cancel, confirm, intro, isCancel, outro, spinner, text, } from '@clack/prompts';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { bold, cyan, dim, green, red, yellow } from 'kolorist';
+const templateDir = resolve(fileURLToPath(import.meta.url), '../../template');
+function toValidPackageName(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9-_.]/g, '');
+}
+function replaceInFile(filePath, replacements) {
+    if (!existsSync(filePath))
+        return;
+    let content = readFileSync(filePath, 'utf-8');
+    for (const [from, to] of Object.entries(replacements)) {
+        content = content.replaceAll(from, to);
+    }
+    writeFileSync(filePath, content, 'utf-8');
+}
+async function main() {
+    console.log();
+    intro(bold(cyan(' create-modsemi ')));
+    console.log(dim('  React 19 + Modern.js + Semi Design admin template\n'));
+    // ── Step 1: Project name ────────────────────────────────────────
+    const rawArg = process.argv[2];
+    let projectName;
+    if (rawArg) {
+        projectName = rawArg;
+        console.log(`  ${dim('Project name:')} ${projectName}`);
+    }
+    else {
+        const input = await text({
+            message: 'Project name',
+            placeholder: 'my-modsemi-app',
+            defaultValue: 'my-modsemi-app',
+            validate(value) {
+                const v = value.trim();
+                if (!v)
+                    return 'Project name is required';
+                if (!/^[a-zA-Z0-9-_.]+$/.test(v))
+                    return 'Use only letters, numbers, hyphens, underscores, or dots';
+            },
+        });
+        if (isCancel(input)) {
+            cancel('Cancelled');
+            process.exit(0);
+        }
+        projectName = input;
+    }
+    const packageName = toValidPackageName(projectName);
+    const targetDir = resolve(process.cwd(), projectName);
+    if (existsSync(targetDir)) {
+        const overwrite = await confirm({
+            message: `Directory "${projectName}" already exists. Overwrite?`,
+        });
+        if (isCancel(overwrite) || !overwrite) {
+            cancel('Cancelled');
+            process.exit(0);
+        }
+        rmSync(targetDir, { recursive: true, force: true });
+    }
+    // ── Step 2: API proxy target ────────────────────────────────────
+    const proxyInput = await text({
+        message: 'API proxy target (backend URL for local dev)',
+        placeholder: 'http://localhost:3001',
+        defaultValue: 'http://localhost:3001',
+        validate(value) {
+            const v = value.trim();
+            if (!v)
+                return 'Proxy target is required';
+            if (!/^https?:\/\/.+/.test(v))
+                return 'Must be a valid http/https URL';
+        },
+    });
+    if (isCancel(proxyInput)) {
+        cancel('Cancelled');
+        process.exit(0);
+    }
+    const proxyTarget = proxyInput;
+    // ── Step 3: Orval API code generation ──────────────────────────
+    const useOrval = await confirm({
+        message: 'Enable Orval API code generation? (requires Swagger/OpenAPI spec)',
+        initialValue: true,
+    });
+    if (isCancel(useOrval)) {
+        cancel('Cancelled');
+        process.exit(0);
+    }
+    // ── Step 4: Scaffold ───────────────────────────────────────────
+    const s = spinner();
+    s.start('Creating project...');
+    try {
+        mkdirSync(targetDir, { recursive: true });
+        // Copy template files
+        cpSync(templateDir, targetDir, { recursive: true });
+        // Rename _package.json → package.json
+        renameSync(join(targetDir, '_package.json'), join(targetDir, 'package.json'));
+        // Rename _gitignore → .gitignore
+        renameSync(join(targetDir, '_gitignore'), join(targetDir, '.gitignore'));
+        // Replace {{projectName}} in package.json
+        replaceInFile(join(targetDir, 'package.json'), {
+            '{{projectName}}': packageName,
+        });
+        // Replace proxy target in modern.config.ts
+        replaceInFile(join(targetDir, 'modern.config.ts'), {
+            'http://localhost:3001': proxyTarget,
+        });
+        // Remove Orval files if not needed
+        if (!useOrval) {
+            rmSync(join(targetDir, 'orval.config.ts'), { force: true });
+            rmSync(join(targetDir, 'swagger'), { recursive: true, force: true });
+            // Remove orval scripts and dependency from package.json
+            const pkgPath = join(targetDir, 'package.json');
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            delete pkg.scripts['api:gen'];
+            delete pkg.scripts['api:gen:watch'];
+            if (pkg.devDependencies)
+                delete pkg.devDependencies.orval;
+            writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+        }
+        s.stop(green('Project created!'));
+    }
+    catch (err) {
+        s.stop(red('Failed to create project'));
+        console.error(err);
+        process.exit(1);
+    }
+    // ── Done ────────────────────────────────────────────────────────
+    console.log();
+    outro(bold(green(`Done! Your project is ready at ${cyan(projectName)}/`)));
+    console.log(`
+  ${bold('Next steps:')}
+
+    ${dim('$')} ${cyan(`cd ${projectName}`)}
+    ${dim('$')} ${cyan('pnpm install')}
+    ${dim('$')} ${cyan('pnpm dev')}
+${useOrval ? `
+  ${bold('API code generation:')}
+
+    1. Put your Swagger/OpenAPI JSON in ${yellow('swagger/')}
+    2. Update ${yellow('orval.config.ts')} with your spec path
+    ${dim('$')} ${cyan('pnpm api:gen')}
+` : ''}
+  ${dim('Docs:')} https://github.com/your-username/modsemi
+  `);
+}
+main().catch(err => {
+    console.error(red('Error:'), err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "create-modsemi",
+  "version": "0.1.0",
+  "description": "Create a ModSemi project — React 19 + Modern.js + Semi Design admin template",
+  "type": "module",
+  "bin": {
+    "create-modsemi": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "modsemi",
+    "modern.js",
+    "semi-design",
+    "react",
+    "admin",
+    "template",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "kolorist": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "~5.7.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/.browserslistrc

@@ -0,0 +1,4 @@
+chrome >= 87
+edge >= 88
+firefox >= 78
+safari >= 14

package/template/.env.example

@@ -0,0 +1,9 @@
+# ModSemi 環境變數範本
+# 複製此檔案為 .env.local 並依實際環境填寫
+# .env.local 已加入 .gitignore，不會被提交到版本控制
+
+# ── API ──────────────────────────────────────────────
+# 前端 axios instance 的 baseURL
+# 本地開發時若使用 dev.server.proxy，此值保持 /api 即可
+# 正式環境改為後端實際位址
+MODERN_APP_API_BASE_URL=/api

package/template/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  ci:
+    name: Lint & Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: latest
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Build
+        run: pnpm build

package/template/.nvmrc

@@ -0,0 +1,2 @@
+lts/jod
+

package/template/README.md

@@ -0,0 +1,199 @@
+# ModSemi
+
+基于 **React 19 + Modern.js + Semi Design** 打造的开箱即用中台前端 / 设计解决方案，类似 Ant Design Pro，提供完整的中后台页面框架与组件体系。
+
+---
+
+## 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| [React](https://react.dev) | 19 | 最新版 React，支持并发特性 |
+| [Modern.js](https://modernjs.dev) | 3.x | 字节跳动开源的全栈框架，内置路由、构建、SSR |
+| [Semi Design](https://semi.design) | 2.x（React 19 适配版） | 字节跳动企业级 UI 组件库，`@douyinfe/semi-ui-19` |
+| [TypeScript](https://www.typescriptlang.org) | ~5.7 | 全量类型支持 |
+| [Biome](https://biomejs.dev) | 1.9 | 高性能代码格式化 & Lint 工具 |
+
+---
+
+## 环境要求
+
+- **Node.js** >= 20
+- **pnpm**（推荐）
+
+---
+
+## 快速開始
+
+### 方式一：使用 degit（推薦，不保留 git 歷史）
+
+```bash
+npx degit your-username/modsemi my-app
+cd my-app
+pnpm install
+pnpm dev
+```
+
+### 方式二：使用 GitHub Template
+
+點擊右上角 **"Use this template"** 建立自己的 repo，再 clone 下來：
+
+```bash
+git clone https://github.com/your-username/my-app.git
+cd my-app
+pnpm install
+pnpm dev
+```
+
+---
+
+## 環境設定
+
+### API Proxy（本地開發）
+
+複製環境變數範本，依需求調整：
+
+```bash
+cp .env.example .env.local
+```
+
+預設 `MODERN_APP_API_BASE_URL=/api`，搭配 `modern.config.ts` 的 `dev.server.proxy`，所有 `/api/**` 請求會在 Dev Server 端轉發給後端，瀏覽器不會觸發 CORS。修改 proxy target：
+
+```typescript
+// modern.config.ts
+dev: {
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3001',  // ← 改為後端位址
+        changeOrigin: true,
+        pathRewrite: { '^/api': '' },
+      },
+    },
+  },
+},
+```
+
+### 本地覆蓋設定（modern.config.local.*）
+
+Modern.js 支援 local override，在本機建立 `modern.config.local.ts`（已加入 `.gitignore`）可覆蓋任意設定，不影響其他人的開發環境：
+
+```typescript
+// modern.config.local.ts（只在本機生效）
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    port: 8080,  // 改本機 port
+  },
+});
+```
+
+---
+
+## 安装与启动
+
+### 1. 安装依赖
+
+```bash
+pnpm install
+```
+
+### 2. 启动开发服务器
+
+```bash
+pnpm dev
+```
+
+### 3. 构建生产版本
+
+```bash
+pnpm build
+```
+
+### 4. 预览生产构建
+
+```bash
+pnpm serve
+```
+
+### 5. 代码检查
+
+```bash
+pnpm lint
+```
+
+---
+
+## 主要依赖说明
+
+### 运行时依赖
+
+| 包名 | 说明 |
+|------|------|
+| `@douyinfe/semi-ui-19` | Semi Design React 19 兼容版 UI 组件库 |
+| `@modern-js/runtime` | Modern.js 运行时模块（路由、数据获取等） |
+| `react` / `react-dom` | React 19 核心库 |
+
+### 开发依赖
+
+| 包名 | 说明 |
+|------|------|
+| `@modern-js/app-tools` | Modern.js 构建与开发工具链 |
+| `@biomejs/biome` | 代码格式化与 Lint |
+| `typescript` | TypeScript 编译器 |
+| `@types/react` / `@types/react-dom` | React 类型声明 |
+
+---
+
+## MCP 集成（Semi Design MCP）
+
+Semi Design 提供了官方 MCP（Model Context Protocol）服务，可让 AI 编码助手（如 Cursor、Trae）直接查阅组件文档与源码，显著提升开发效率。
+
+### 安装配置
+
+在 Cursor 或 Trae 的 MCP 设置中添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "semi-mcp": {
+      "command": "npx",
+      "args": ["-y", "@douyinfe/semi-mcp"]
+    }
+  }
+}
+```
+
+> **字节内网用户**请将包名替换为 `@ies/semi-mcp-bytedance`。
+
+### 可用工具
+
+配置完成后，AI 助手可使用以下 MCP 工具：
+
+| 工具 | 功能 |
+|------|------|
+| `get_semi_document` | 获取组件文档（Button、Table、Form 等）及专题文档（主题定制、黑暗模式、更新日志等） |
+| `get_semi_code_block` | 获取文档中的具体代码示例（大文档中代码块被折叠时使用） |
+| `get_component_file_list` | 列出某个组件的所有源文件路径 |
+| `get_file_code` | 获取组件源文件代码（大文件显示结构，小文件显示完整内容） |
+| `get_function_code` | 获取组件源码中某个具体函数的完整实现 |
+
+### 使用示例
+
+配置完成后，直接在 AI 对话中描述需求即可，无需手动查阅文档：
+
+```
+帮我用 Semi Design 实现一个带搜索和分页的 Table 组件
+帮我查一下 Semi Design Form 的表单验证用法
+Semi Design 怎么做主题定制？
+```
+
+---
+
+## 参考文档
+
+- [Modern.js 文档](https://modernjs.dev/en)
+- [Semi Design 文档](https://semi.design/zh-CN)
+- [Semi Design React 19 迁移指南](https://semi.design/zh-CN/start/update-to-v2)
+- [React 19 文档](https://react.dev)

package/template/_gitignore

@@ -0,0 +1,33 @@
+.DS_Store
+
+.pnp
+.pnp.js
+.env.local
+.env.*.local
+.history
+*.log*
+
+node_modules/
+.yarn-integrity
+.pnpm-store/
+*.tsbuildinfo
+.changeset/pre.json
+
+dist/
+coverage/
+release/
+output/
+output_resource/
+log/
+
+.vscode/**/*
+!.vscode/settings.json
+!.vscode/extensions.json
+.idea/
+
+**/*/typings/auto-generated
+
+modern.config.local.*
+
+# orval 生成的檔案（由 pnpm api:gen 自動產生）
+src/api/generated/

package/template/_package.json

@@ -0,0 +1,36 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build",
+    "serve": "modern serve",
+    "lint": "biome check",
+    "api:gen": "orval",
+    "api:gen:watch": "orval --watch"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@douyinfe/semi-icons": "^2.94.0",
+    "@douyinfe/semi-icons-lab": "^2.94.1",
+    "@douyinfe/semi-ui-19": "^2.94.0",
+    "@modern-js/runtime": "3.1.3",
+    "axios": "^1.15.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.0",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@modern-js/app-tools": "3.1.3",
+    "@modern-js/tsconfig": "3.1.3",
+    "@types/node": "^20",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "less": "^4.6.4",
+    "orval": "^8.7.0",
+    "typescript": "~5.7.3"
+  }
+}

package/template/biome.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "defaultBranch": "main",
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "arrowParentheses": "asNeeded",
+      "jsxQuoteStyle": "double",
+      "lineWidth": 80
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noDuplicateFontNames": "off"
+      }
+    }
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "ignore": [".vscode/**/*", "node_modules/**/*", "dist/**/*"]
+  }
+}