velmora-starter 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# velmora-starter
+
+Velmora Starter 的项目创建工具，用于快速生成 Vue 3、TypeScript、Vite 和 Element Plus 工程。
+
+## 环境要求
+
+- Node.js `20.19+` 或 `22.12+`
+
+## 创建项目
+
+```bash
+npm create velmora-starter@latest my-app
+```
+
+CLI 默认只创建项目文件，不会自动下载依赖。创建完成后执行：
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+如果需要在创建后自动安装依赖：
+
+```bash
+npm create velmora-starter@latest my-app --install
+```
+
+## 常用命令
+
+```bash
+npm run dev
+npm run typecheck
+npm run lint
+npm run build
+```
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "velmora-starter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Create a project from Velmora Starter",
+  "type": "module",
+  "bin": {
+    "velmora-starter": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "template",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "keywords": [
+    "vue",
+    "vite",
+    "starter",
+    "scaffold"
+  ],
+  "license": "MIT"
+}

package/src/generator.mjs

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+import {
+  cp,
+  copyFile,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  writeFile
+} from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath, URL } from "node:url";
+
+const templateRoot = fileURLToPath(new URL("../template", import.meta.url));
+const packageNamePattern = /^[a-z0-9][a-z0-9._-]*$/;
+
+export function validateProjectName(projectName) {
+  if (!packageNamePattern.test(projectName)) {
+    throw new Error(
+      "项目名称只能包含小写字母、数字、点、下划线和连字符，并且必须以字母或数字开头。"
+    );
+  }
+}
+
+export function formatProjectTitle(projectName) {
+  return projectName
+    .split(/[-_.]+/)
+    .filter(Boolean)
+    .map((part) => `${part[0].toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+async function ensureEmptyTarget(targetDirectory) {
+  try {
+    const entries = await readdir(targetDirectory);
+    if (entries.length > 0) {
+      throw new Error(`目标目录不为空：${targetDirectory}`);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    await mkdir(targetDirectory, { recursive: true });
+  }
+}
+
+async function replaceTemplateTokens(targetDirectory, projectName) {
+  const replacements = [
+    ["package.json", "velmora-project-name", projectName],
+    [".env", "VELMORA_PROJECT_TITLE", formatProjectTitle(projectName)],
+    [".env", "VELMORA_PROJECT_NAMESPACE", projectName],
+    ["README.md", "VELMORA_PROJECT_TITLE", formatProjectTitle(projectName)]
+  ];
+
+  for (const [file, token, value] of replacements) {
+    const filePath = resolve(targetDirectory, file);
+    const source = await readFile(filePath, "utf8");
+    await writeFile(filePath, source.replaceAll(token, value));
+  }
+}
+
+async function restoreDotfiles(targetDirectory) {
+  for (const file of ["gitignore", "npmrc"]) {
+    const sourcePath = resolve(targetDirectory, `_${file}`);
+    await copyFile(sourcePath, resolve(targetDirectory, `.${file}`));
+    await rm(sourcePath);
+  }
+}
+
+function installDependencies(targetDirectory) {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, ["install"], {
+      cwd: targetDirectory,
+      stdio: "inherit"
+    });
+
+    child.on("error", rejectPromise);
+    child.on("exit", (code) => {
+      if (code === 0) resolvePromise();
+      else rejectPromise(new Error(`npm install 执行失败，退出码：${code}`));
+    });
+  });
+}
+
+export async function createProject({
+  directory,
+  install = false,
+  cwd = process.cwd()
+}) {
+  const targetDirectory = resolve(cwd, directory);
+  const projectName = basename(targetDirectory);
+
+  validateProjectName(projectName);
+  await ensureEmptyTarget(targetDirectory);
+  await cp(templateRoot, targetDirectory, { recursive: true });
+  await restoreDotfiles(targetDirectory);
+  await replaceTemplateTokens(targetDirectory, projectName);
+
+  if (install) await installDependencies(targetDirectory);
+
+  return { projectName, targetDirectory };
+}

package/src/index.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import console from "node:console";
+import { createInterface } from "node:readline/promises";
+import process, { stdin, stdout } from "node:process";
+import { createProject } from "./generator.mjs";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`
+create-velmora-starter <project-name> [--install]
+
+创建一个 Velmora Starter 项目。
+  `);
+  process.exit(0);
+}
+
+const install = args.includes("--install");
+let directory = args.find((arg) => !arg.startsWith("-"));
+
+if (!directory) {
+  const prompt = createInterface({ input: stdin, output: stdout });
+  directory = (await prompt.question("项目名称：")).trim();
+  prompt.close();
+}
+
+if (!directory) {
+  console.error("项目名称不能为空。");
+  process.exit(1);
+}
+
+try {
+  const result = await createProject({ directory, install });
+  console.log(`\n项目 ${result.projectName} 创建完成。`);
+  console.log(`cd ${directory}`);
+  if (!install) console.log("npm install");
+  console.log("npm run dev\n");
+} catch (error) {
+  console.error(`\n创建失败：${error.message}`);
+  process.exitCode = 1;
+}

package/template/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

package/template/.env

@@ -0,0 +1,6 @@
+VITE_APP_TITLE=VELMORA_PROJECT_TITLE
+VITE_APP_NAMESPACE=VELMORA_PROJECT_NAMESPACE
+VITE_PORT=8848
+VITE_PUBLIC_PATH=/
+VITE_ROUTER_HISTORY=hash
+VITE_API_BASE_URL=/api

package/template/.env.development

@@ -0,0 +1,5 @@
+VITE_ENABLE_MOCK=true
+VITE_SOURCE_MAP=true
+VITE_COMPRESSION=none
+VITE_CDN=false
+VITE_REMOVE_CONSOLE=false

package/template/.env.production

@@ -0,0 +1,5 @@
+VITE_ENABLE_MOCK=false
+VITE_SOURCE_MAP=false
+VITE_COMPRESSION=brotli
+VITE_CDN=false
+VITE_REMOVE_CONSOLE=false

package/template/.env.staging

@@ -0,0 +1,5 @@
+VITE_ENABLE_MOCK=false
+VITE_SOURCE_MAP=true
+VITE_COMPRESSION=gzip
+VITE_CDN=false
+VITE_REMOVE_CONSOLE=false

package/template/.husky/commit-msg

@@ -0,0 +1 @@
+pnpm exec commitlint --edit "$1"

package/template/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm lint

package/template/.nvmrc

@@ -0,0 +1 @@
+20.19.0

package/template/.prettierignore

@@ -0,0 +1,4 @@
+dist
+node_modules
+report.html
+pnpm-lock.yaml

package/template/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "none"
+}

package/template/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "stylelint.vscode-stylelint"
+  ]
+}

package/template/README.md

@@ -0,0 +1,18 @@
+# VELMORA_PROJECT_TITLE
+
+基于 Vue 3、TypeScript、Vite 和 Element Plus 创建的项目。
+
+## 开始使用
+
+```bash
+npm install
+npm run dev
+```
+
+## 校验与构建
+
+```bash
+npm run typecheck
+npm run lint
+npm run build
+```

package/template/_gitignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+report.html
+*.local
+*.log
+.DS_Store
+.idea
+.vscode/*
+!.vscode/extensions.json

package/template/_npmrc

@@ -0,0 +1,2 @@
+auto-install-peers=true
+strict-peer-dependencies=false

package/template/build/cdn.ts

@@ -0,0 +1,25 @@
+import { Plugin as importToCdn } from "vite-plugin-cdn-import";
+
+/** 将稳定的第三方运行时依赖切换为 jsDelivr CDN 资源。 */
+export function createCdnPlugin() {
+  return importToCdn({
+    prodUrl: "https://cdn.jsdelivr.net/npm/{name}@{version}/{path}",
+    modules: [
+      { name: "vue", var: "Vue", path: "dist/vue.global.prod.js" },
+      {
+        name: "vue-router",
+        var: "VueRouter",
+        path: "dist/vue-router.global.prod.js"
+      },
+      { name: "pinia", var: "Pinia", path: "dist/pinia.iife.prod.js" },
+      { name: "axios", var: "axios", path: "dist/axios.min.js" },
+      {
+        name: "element-plus",
+        var: "ElementPlus",
+        path: "dist/index.full.min.js",
+        css: "dist/index.css"
+      },
+      { name: "echarts", var: "echarts", path: "dist/echarts.min.js" }
+    ]
+  });
+}

package/template/build/compression.ts

@@ -0,0 +1,25 @@
+import type { PluginOption } from "vite";
+import compression from "vite-plugin-compression";
+import type { BuildEnv } from "./env";
+
+/** 根据环境配置按需创建 gzip、brotli 压缩插件。 */
+export function createCompressionPlugins(
+  mode: BuildEnv["compression"]
+): PluginOption[] {
+  if (mode === "none") return [];
+
+  const plugins: PluginOption[] = [];
+  const common = { threshold: 10 * 1024, deleteOriginFile: false };
+
+  if (mode === "gzip" || mode === "both") {
+    plugins.push(compression({ ...common, algorithm: "gzip", ext: ".gz" }));
+  }
+
+  if (mode === "brotli" || mode === "both") {
+    plugins.push(
+      compression({ ...common, algorithm: "brotliCompress", ext: ".br" })
+    );
+  }
+
+  return plugins;
+}

package/template/build/env.ts

@@ -0,0 +1,34 @@
+/** 构建阶段统一使用的环境配置，避免插件各自解析字符串环境变量。 */
+export type BuildEnv = {
+  appTitle: string;
+  appNamespace: string;
+  port: number;
+  publicPath: string;
+  sourceMap: boolean;
+  enableMock: boolean;
+  enableCdn: boolean;
+  removeConsole: boolean;
+  compression: "none" | "gzip" | "brotli" | "both";
+};
+
+const toBoolean = (value: string | undefined) => value === "true";
+
+export function resolveBuildEnv(env: Record<string, string>): BuildEnv {
+  const compression = env.VITE_COMPRESSION || "none";
+
+  if (!["none", "gzip", "brotli", "both"].includes(compression)) {
+    throw new Error(`Unsupported VITE_COMPRESSION: ${compression}`);
+  }
+
+  return {
+    appTitle: env.VITE_APP_TITLE || "Vue App",
+    appNamespace: env.VITE_APP_NAMESPACE || "vue-app",
+    port: Number(env.VITE_PORT || 8848),
+    publicPath: env.VITE_PUBLIC_PATH || "/",
+    sourceMap: toBoolean(env.VITE_SOURCE_MAP),
+    enableMock: toBoolean(env.VITE_ENABLE_MOCK),
+    enableCdn: toBoolean(env.VITE_CDN),
+    removeConsole: toBoolean(env.VITE_REMOVE_CONSOLE),
+    compression: compression as BuildEnv["compression"]
+  };
+}

package/template/commitlint.config.js

@@ -0,0 +1,3 @@
+export default {
+  extends: ["@commitlint/config-conventional"]
+};

package/template/eslint.config.js

@@ -0,0 +1,44 @@
+import js from "@eslint/js";
+import vue from "eslint-plugin-vue";
+import tseslint from "typescript-eslint";
+import vueParser from "vue-eslint-parser";
+import prettier from "eslint-config-prettier";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "dist",
+      "node_modules",
+      "report.html",
+      "docs/node_modules",
+      "docs/docs/.vitepress/cache",
+      "docs/docs/.vitepress/dist"
+    ]
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  ...vue.configs["flat/recommended"],
+  {
+    files: ["**/*.vue"],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: {
+        parser: tseslint.parser,
+        sourceType: "module"
+      }
+    },
+    rules: {
+      "vue/multi-word-component-names": "off"
+    }
+  },
+  {
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" }
+      ]
+    }
+  },
+  prettier
+);

package/template/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#ffffff" />
+    <title>%VITE_APP_TITLE%</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/mock/health.ts

@@ -0,0 +1,10 @@
+import { defineFakeRoute } from "vite-plugin-fake-server/client";
+
+// 用于开发环境确认 Mock 服务与 API 前缀是否正常工作。
+export default defineFakeRoute([
+  {
+    url: "/api/health",
+    method: "get",
+    response: () => ({ status: "ok" })
+  }
+]);

package/template/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "velmora-project-name",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "cross-env NODE_OPTIONS=--max-old-space-size=4096 vite",
+    "build": "rimraf dist && cross-env NODE_OPTIONS=--max-old-space-size=8192 vite build",
+    "build:staging": "rimraf dist && vite build --mode staging",
+    "preview": "vite preview",
+    "report": "cross-env ANALYZE=true npm run build",
+    "typecheck": "vue-tsc --noEmit",
+    "lint:eslint": "eslint . --max-warnings 0",
+    "lint:prettier": "prettier --check .",
+    "lint:stylelint": "stylelint \"src/**/*.{vue,css,scss}\"",
+    "lint": "npm run lint:eslint && npm run lint:prettier && npm run lint:stylelint",
+    "format": "prettier --write .",
+    "prepare": "husky"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "dependencies": {
+    "@vueuse/core": "^14.0.0",
+    "@vueuse/motion": "^3.0.3",
+    "animate.css": "^4.1.1",
+    "axios": "^1.12.2",
+    "echarts": "^6.0.0",
+    "element-plus": "^2.11.5",
+    "localforage": "^1.10.0",
+    "mitt": "^3.0.1",
+    "nprogress": "^0.2.0",
+    "pinia": "^3.0.3",
+    "qs": "^6.14.0",
+    "vue": "^3.5.22",
+    "vue-router": "^4.6.3"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/js": "^9.38.0",
+    "@iconify/json": "^2.2.400",
+    "@tailwindcss/vite": "^4.1.16",
+    "@types/node": "^20.19.23",
+    "@types/nprogress": "^0.2.3",
+    "@types/qs": "^6.14.0",
+    "@vitejs/plugin-vue": "^6.0.1",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-vue": "^10.5.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.6",
+    "postcss": "^8.5.6",
+    "postcss-html": "^1.8.0",
+    "postcss-scss": "^4.0.9",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "rollup-plugin-visualizer": "^6.0.5",
+    "sass": "^1.93.2",
+    "stylelint": "^16.25.0",
+    "stylelint-config-recess-order": "^7.4.0",
+    "stylelint-config-recommended-vue": "^1.6.1",
+    "stylelint-config-standard": "^39.0.0",
+    "stylelint-config-standard-scss": "^16.0.0",
+    "stylelint-order": "^7.0.0",
+    "stylelint-prettier": "^5.0.3",
+    "stylelint-scss": "^6.12.1",
+    "tailwindcss": "^4.1.16",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "unplugin-icons": "^22.5.0",
+    "vite": "^7.1.12",
+    "vite-plugin-cdn-import": "^1.0.1",
+    "vite-plugin-compression": "^0.5.1",
+    "vite-plugin-fake-server": "^2.2.0",
+    "vite-plugin-remove-console": "^2.2.0",
+    "vite-svg-loader": "^5.1.0",
+    "vue-eslint-parser": "^10.2.0",
+    "vue-tsc": "^3.1.2"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts,vue}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,scss,vue}": "stylelint --fix",
+    "*.{json,md,yml,yaml}": "prettier --write"
+  }
+}

package/template/src/App.vue

@@ -0,0 +1,9 @@
+<script setup lang="ts">
+import { ElConfigProvider } from "element-plus";
+</script>
+
+<template>
+  <el-config-provider>
+    <router-view />
+  </el-config-provider>
+</template>

package/template/src/api/http.ts

@@ -0,0 +1,7 @@
+export { http } from "@/utils/http";
+export type {
+  HttpError,
+  HttpRequestConfig,
+  HttpResponse,
+  RequestMethod
+} from "@/utils/http/types";

package/template/src/directives/auth/index.ts

@@ -0,0 +1,15 @@
+import type { Directive, DirectiveBinding } from "vue";
+import { hasAuth } from "@/utils/route-auth";
+
+/** 根据当前路由 meta.auths 控制元素是否保留。 */
+export const auth: Directive<HTMLElement, string | string[]> = {
+  mounted(element, binding: DirectiveBinding<string | string[]>) {
+    if (!binding.value) {
+      throw new Error(
+        "[Directive: auth]: need auths! Like v-auth=\"['btn.add', 'btn.edit']\""
+      );
+    }
+
+    if (!hasAuth(binding.value)) element.remove();
+  }
+};

package/template/src/directives/copy/index.ts

@@ -0,0 +1,34 @@
+import type { Directive } from "vue";
+import { message } from "@/utils/message";
+
+type CopyElement = HTMLElement & {
+  copyValue?: string;
+  copyHandler?: () => void;
+};
+
+/** 在指定事件（默认双击）发生时复制绑定文本。 */
+export const copy: Directive<CopyElement, string> = {
+  mounted(element, binding) {
+    element.copyValue = binding.value;
+    element.copyHandler = async () => {
+      try {
+        await navigator.clipboard.writeText(element.copyValue ?? "");
+        message("复制成功", { type: "success" });
+      } catch {
+        message("复制失败", { type: "error" });
+      }
+    };
+    element.addEventListener(binding.arg ?? "dblclick", element.copyHandler);
+  },
+  updated(element, binding) {
+    element.copyValue = binding.value;
+  },
+  unmounted(element, binding) {
+    if (element.copyHandler) {
+      element.removeEventListener(
+        binding.arg ?? "dblclick",
+        element.copyHandler
+      );
+    }
+  }
+};

package/template/src/directives/index.ts

@@ -0,0 +1,19 @@
+import type { App } from "vue";
+import { auth } from "./auth";
+import { copy } from "./copy";
+import { longpress } from "./longpress";
+import { optimize } from "./optimize";
+import { perms } from "./perms";
+import { ripple } from "./ripple";
+
+export { auth, copy, longpress, optimize, perms, ripple };
+
+/** 一次性注册工程提供的全部全局指令。 */
+export function setupDirectives(app: App) {
+  app.directive("auth", auth);
+  app.directive("copy", copy);
+  app.directive("longpress", longpress);
+  app.directive("optimize", optimize);
+  app.directive("perms", perms);
+  app.directive("ripple", ripple);
+}