@stdex/create 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 安坚实
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# 项目模板 - Project Templates
 
-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.
+简体中文 | [English](./README_EN.md)
+
+## 模板列表
+
+| 目录        | 内容     | 备注                                       |
+| ----------- | -------- | ------------------------------------------ |
+| base        | 基础模板 | 配置了 Prettier 和 ESLint                  |
+| service     | 后端服务 | TypeScript + starlight-server + Prisma ORM |
+| site        | 前端站点 | TypeScript + React + Ant Design + Vite     |
+| miniprogram | 小程序   | TypeScript + SCSS + gulp.js                |
+
+---
+
+## 使用方法
+
+```shell
+# 这个命令本质上是执行 `npm exec @stdex/create`，即执行这个包 `package.json` 中的 `bin` 配置的脚本。
+npm init @stdex@latest {template} -- --name=xxx
+```
+
+- 若不指定 `template`，则使用 `基础模板`。
+- 若指定 `name`，则用指定名称新建一个文件夹然后初始化项目，否则在当前目录初始化项目（要求当前目录为空）
+
+---
+
+## 开发约定
+
+### 指定依赖版本
+
+除非有明确的版本需要，否则 `package.json` 中的依赖版本都指定为 `latest`，项目初始化时会替换为实际版本号。
+
+### 定义变量
+
+在模板根目录放置 `variables.json`，格式如下：
+
+```json
+[
+  {
+    "name": "VARIABLE_NAME", // 变量名
+    "describe": "xxxx", // 变量介绍
+    "defaults": "xxxx" // 变量默认值，此项不存在代表是必填变量
+  },
+  ...
+]
+```
+
+然后在项目任意文件中，可用 `{{VARIABLE_NAME}}` 的形式放置占位符，在初始化项目时会替换为实际变量值。
+
+### 初始化脚本
+
+可以在模板根目录创建一个 `setup.js`，格式如下：
+
+```js
+// context 中各函数的用法见 create/src/index.js 中的同名函数
+export async function setup(context: { command, confirmPath, getDirectoryPath }) {
+  // do something
+}
+```
+
+此函数会在项目自动初始化流程运行完执行，之后此脚本文件会被删除。
+
+### 指定 .gitignore
+
+因为安装 npm 包时会自动把 `.gitignore` 重命名为 `.npmignore`，因此模板里需要把此文件命名为 `gitignore`（不带开头的点）。
+在初始化项目时会自动重命名为 `.gitignore`。

package/README_EN.md

@@ -0,0 +1,67 @@
+# Project Templates
+
+[简体中文](./README.md) | English
+
+## Templates
+
+| Directory   | Purpose         | Notes                                      |
+| ----------- | --------------- | ------------------------------------------ |
+| base        | Base template   | Configured with Prettier and ESLint        |
+| service     | Backend service | TypeScript + starlight-server + Prisma ORM |
+| site        | Frontend site   | TypeScript + React + Ant Design + Vite     |
+| miniprogram | Mini program    | TypeScript + SCSS + gulp.js                |
+
+---
+
+## Usage
+
+```shell
+# This command runs `npm exec @stdex/create`, which executes the script specified by the `bin` field in this package's `package.json`.
+npm init @stdex@latest {template} -- --name=xxx
+```
+
+- If `template` is omitted, the base template is used.
+- If `name` is specified, a new directory with that name is created and the project is initialized inside it. Otherwise, the project is initialized in the current directory, which must be empty.
+
+---
+
+## Development Conventions
+
+### Specifying Dependency Versions
+
+Unless a specific version is required, set dependency versions in `package.json` to `latest`. They will be replaced with the actual version numbers when the project is initialized.
+
+### Defining Variables
+
+Place a `variables.json` file in the template root using the following format:
+
+```json
+[
+  {
+    "name": "VARIABLE_NAME", // Variable name
+    "describe": "xxxx", // Variable description
+    "defaults": "xxxx" // Default value; omitting this field makes the variable required
+  },
+  ...
+]
+```
+
+You can then place placeholders in the form `{{VARIABLE_NAME}}` in any project file. During project initialization, they will be replaced with the actual variable values.
+
+### Setup Script
+
+You can create a `setup.js` file in the template root using the following format:
+
+```js
+// See the functions with the same names in create/src/index.js for details on using the functions in `context`.
+export async function setup(context: { command, confirmPath, getDirectoryPath }) {
+  // Do something
+}
+```
+
+This function runs after the automatic project initialization process finishes. The script file is then deleted.
+
+### Specifying .gitignore
+
+Because installing an npm package automatically renames `.gitignore` to `.npmignore`, this file must be named `gitignore` (without the leading dot) in a template.
+It is automatically renamed to `.gitignore` when the project is initialized.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@stdex/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "npm init 项目模板 - Project Templates For 'npm init'",
+  "homepage": "https://github.com/anjianshi/stdex-packages/create/",
+  "type": "module",
+  "bin": {
+    "create": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "templates",
+    "!templates/**/node_modules",
+    "!templates/**/.swc",
+    "!templates/**/.DS_Store",
+    "!templates/**/dist"
+  ],
+  "bugs": {
+    "url": "https://github.com/anjianshi/stdex-packages/issues",
+    "email": "anjianshi@gmail.com"
+  },
+  "license": "MIT",
+  "author": "anjianshi <anjianshi@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "github:anjianshi/stdex-packages"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-node": "1.2.0",
+    "@stdex/presets-prettier": "1.2.0"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc",
+  "scripts": {
+    "dev": "rm -rf test && node ./src/index.js base --name=test"
+  }
 }

package/src/eslint.config.js

@@ -0,0 +1,2 @@
+import configs from '@stdex/presets-eslint-node'
+export default configs

package/src/index.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import child_process from 'child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+import chalk from 'chalk'
+
+// -------------------------
+// 工具函数
+// -------------------------
+
+/**
+ * 返回文件所处目录的绝对路径
+ */
+function getDirectoryPath(fileUrl) {
+  return path.dirname(fileURLToPath(new URL(typeof fileUrl !== 'string' ? fileUrl.url : fileUrl)))
+}
+
+/**
+ * 确认路径信息
+ * @return null | 'file' | 'directory'
+ */
+function confirmPath(path) {
+  const stat = fs.statSync(path, { throwIfNoEntry: false })
+  if (!stat) return null
+  return stat.isDirectory() ? 'directory' : 'file'
+}
+
+function exit(message, code = 1) {
+  console.error(chalk.red(message))
+  process.exit(code)
+}
+
+/**
+ * 执行命令，返回 status code
+ * 若 exitOnError 为 true，执行失败时会直接退出程序
+ */
+async function command(command, exitOnError = true) {
+  console.log('\n> ' + chalk.green(command))
+  return new Promise(resolve => {
+    const subprocess = child_process.spawn(command, {
+      shell: true,
+      cwd: projectPath,
+    })
+    subprocess.stdout.on('data', data => process.stdout.write(chalk.gray(data)))
+    subprocess.stderr.on('data', data => process.stdout.write(chalk.red(data)))
+    subprocess.on('close', code => {
+      if (code !== 0 && exitOnError) exit('命令执行失败')
+      process.stdout.write('\n')
+      resolve(code)
+    })
+  })
+}
+
+// -------------------------
+// 整理参数
+// -------------------------
+
+const args = process.argv.slice(2)
+const projectName = args
+  .map(arg => {
+    if (arg.startsWith('--name=')) return arg.slice(7)
+    return null
+  })
+  .find(v => v)
+const projectPath = path.resolve(projectName || '.')
+const template = args.find(arg => !arg.startsWith('--')) || 'base'
+const templatesPath = path.resolve(getDirectoryPath(import.meta.url), '../templates')
+const templatePath = path.resolve(templatesPath, template)
+
+console.log('[项目初始化]')
+if (projectName) console.log('项目名称: ' + projectName)
+console.log('项目路径: ' + projectPath)
+console.log('使用模板: ' + template)
+
+// -------------------------
+// 确认环境
+// -------------------------
+
+if (!templatePath.startsWith(templatesPath) || confirmPath(templatePath) !== 'directory') {
+  exit('模板不存在：' + templatePath)
+}
+
+const projectPathStat = confirmPath(projectPath)
+if (projectPathStat === 'file') exit('项目路径存在同名文件，无法初始化')
+else if (projectPathStat) {
+  if (fs.readdirSync(projectPath).length) exit('项目路径不为空，无法初始化')
+} else {
+  fs.mkdirSync(projectPath, { recursive: true })
+}
+
+// -------------------------
+// 复制模板内容
+// -------------------------
+
+console.log('复制模板内容...')
+fs.cpSync(templatePath, projectPath, {
+  recursive: true,
+  filter(src, dest) {
+    console.log(dest.slice(projectPath.length))
+    return true
+  },
+})
+
+const filesToRename = [
+  { from: '_gitignore', to: '.gitignore' },
+  { from: '_pnpm-workspace.yaml', to: 'pnpm-workspace.yaml' },
+  { from: '_env', to: '.env' },
+]
+for (const item of filesToRename) {
+  const fromPath = path.join(projectPath, item.from)
+  const toPath = path.join(projectPath, item.to)
+  if (confirmPath(fromPath) === 'file') {
+    fs.renameSync(fromPath, toPath)
+  }
+}
+
+// -------------------------
+// 变量替换
+// -------------------------
+
+let variableSupportedExts =
+  'js,cjs,mjs,ts,cts,mts,jsx,tsx,json,md,html,css,scss,less,styl,txt,ini,yaml,svg'
+variableSupportedExts = variableSupportedExts.split(',')
+
+const variablesFile = path.join(projectPath, 'variables.json')
+if (confirmPath(variablesFile) === 'file') {
+  const variables = JSON.parse(fs.readFileSync(variablesFile))
+  fs.unlinkSync(variablesFile)
+  if (variables.length) {
+    const values = await getVariableValues(variables)
+    await replaceVariables(values)
+  }
+}
+
+async function getVariableValues(variables) {
+  console.log('\n[补充项目信息]')
+  const values = [] // { name, value }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  for (const variable of variables) {
+    const defaults = 'defaults' in variable ? variable.defaults : undefined
+    while (true) {
+      let answer = await rl.question(
+        variable.describe + (defaults === undefined ? '' : `(${defaults})`) + '：',
+      )
+      answer = answer.trim()
+      if (!answer) {
+        if (defaults !== undefined) answer = defaults
+        else {
+          console.log(chalk.red('不能为空'))
+          continue
+        }
+      }
+      values.push({ name: variable.name, value: answer })
+      break
+    }
+  }
+  rl.close()
+
+  return values
+}
+
+async function replaceVariables(values) {
+  console.log('\n[替换变量]')
+
+  const directoryItems = fs.readdirSync(projectPath, { recursive: true, withFileTypes: true })
+  for (const item of directoryItems) {
+    if (!item.isFile()) continue
+
+    const filepath = path.join(item.parentPath, item.name)
+    if (!variableSupportedExts.find(ext => filepath.endsWith('.' + ext))) continue
+
+    const origContent = fs.readFileSync(filepath, 'utf8').toString()
+    let content = origContent
+    for (const { name, value } of values) {
+      const match = '{{' + name + '}}'
+      if (content.includes(match)) content = content.replaceAll(match, value)
+    }
+    if (content !== origContent) {
+      fs.writeFileSync(filepath, content)
+      console.log(filepath)
+    }
+  }
+}
+
+// -------------------------
+// 安装依赖
+// -------------------------
+
+const packageJSONPath = path.join(projectPath, 'package.json')
+if (confirmPath(packageJSONPath) === 'file') {
+  const packageJSON = JSON.parse(fs.readFileSync(packageJSONPath))
+  const dependencies = Object.entries(packageJSON.dependencies || {})
+  const devDependencies = Object.entries(packageJSON.devDependencies || {})
+  if (dependencies.length || devDependencies.length) {
+    delete packageJSON.dependencies
+    delete packageJSON.devDependencies
+    fs.writeFileSync(packageJSONPath, JSON.stringify(packageJSON, null, 2))
+
+    console.log('\n[安装依赖]')
+
+    console.log('确认可用的包管理器...')
+    const usePnpm = (await command('which pnpm', true)) === 0
+    if (!usePnpm) console.log('pnpm 不存在，使用 npm 安装依赖')
+
+    const installCommand = usePnpm ? 'pnpm add ' : 'npm install '
+    if (dependencies.length) await command(installCommand + formatDependencies(dependencies))
+    if (devDependencies.length)
+      await command(installCommand + '--save-dev ' + formatDependencies(devDependencies))
+  }
+}
+
+function formatDependencies(dependencies) {
+  return dependencies
+    .map(([name, ver]) => (ver !== 'latest' ? `${name}@${ver}` : name))
+    .join(' ')
+}
+
+// -----------------------------
+// 执行模板的自定义初始化脚本
+// -----------------------------
+
+const setupScriptPath = path.join(projectPath, 'setup.js')
+if (confirmPath(setupScriptPath) === 'file') {
+  console.log('\n[执行初始化脚本]')
+
+  const context = { getDirectoryPath, confirmPath, command }
+  const module = await import(setupScriptPath)
+  await module.setup(context)
+  fs.unlinkSync(setupScriptPath)
+}

package/templates/base/eslint.config.js

@@ -0,0 +1,2 @@
+import configs from '@stdex/presets-eslint-base'
+export default configs

package/templates/base/index.js

@@ -0,0 +1,3 @@
+export function run() {
+  return 1
+}

package/templates/base/package.json

@@ -0,0 +1,16 @@
+{
+  "private": true,
+  "name": "project",
+  "description": "基础项目",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-base": "workspace:*",
+    "@stdex/presets-prettier": "workspace:*",
+    "eslint": "latest"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc"
+}

package/templates/miniprogram/README.md

@@ -0,0 +1,27 @@
+# {{appname}}
+
+## 开发
+
+预览：运行 `pnpm watch`，然后在 `微信开发者工具` 里查看运行结果。  
+发布：运行 `pnpm build`，然后在 `微信开发者工具` 里执行发布。
+
+## 文件结构
+
+```yaml
+project/
+  typings/: 小程序及自定义类型定义
+  dist/: 小程序代码构建结果，实际运行和上传的是此目录的内容
+  src/: 小程序代码
+```
+
+## 关于小程序类型定义
+
+`typings/` 目录中的小程序类型定义与 TypeScript 自带的类型定义有冲突，经历过手动修改。  
+如果后续更新小程序类型定义，可能需要再次手动修改。  
+更新方法：在 `微信开发者工具` 中，右键点击 `typings/types/wx/` 目录，点击“更新声明文件”。
+
+## 缺陷
+
+当前不支持引入 npm 包。
+小程序设计了引入 npm 包的机制，但是不能正确支持 ES6 Module 形式的包。
+所以目前有需要的依赖的话，需要手动把代码复制进来。

package/templates/miniprogram/_gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+node_modules/
+dist/

package/templates/miniprogram/eslint.config.cjs

@@ -0,0 +1,25 @@
+const globals = require('@stdex/presets-eslint-base/globals.cjs')
+module.exports = [
+  {
+    ignores: ['dist/*'],
+  },
+  ...require('@stdex/presets-eslint-typescript'),
+  {
+    languageOptions: {
+      globals: globals.browser,
+    },
+  },
+  {
+    files: ['gulpfile.js'],
+    languageOptions: {
+      globals: globals.node,
+    },
+  },
+  {
+    files: ['typings/**/*.d.ts'],
+    rules: {
+      'spaced-comment': 'off',
+      '@typescript-eslint/triple-slash-reference': 'off',
+    },
+  },
+]

package/templates/miniprogram/gulpfile.js

@@ -0,0 +1,81 @@
+const childProcess = require('node:child_process')
+const gulp = require('gulp')
+const renamePlugin = require('gulp-rename')
+const sassPluginFactory = require('gulp-sass')
+const swcPlugin = require('gulp-swc')
+const dartSass = require('sass')
+const { replaceTscAliasPaths } = require('tsc-alias')
+
+const sassPlugin = sassPluginFactory(dartSass)
+
+/**
+ * --------------------
+ * 常量定义
+ * --------------------
+ */
+const dist = 'dist/'
+
+/**
+ * --------------------
+ * 任务定义
+ * --------------------
+ */
+function clean(cb) {
+  childProcess.exec(`rm -rf ${dist}`, (err, stdout, stderr) => {
+    if (stdout.trim()) process.stdout.write(stdout)
+    if (stderr.trim()) process.stderr.write(stderr)
+    cb()
+  })
+}
+
+function typescript(cb, path) {
+  const swcOptions = {
+    jsc: {
+      target: 'ES2019', // 编译到较新的语法，但不是最新的（不然 ?. 语言小程序不支持）
+    },
+    module: {
+      type: 'commonjs', // 编译成 commonjs 模块，因为小程序原生不支持 ES6 Module
+    },
+  }
+  return gulp
+    .src(path || 'src/**/*.ts', { base: './src' })
+    .pipe(swcPlugin(swcOptions))
+    .pipe(gulp.dest(dist))
+}
+
+function tsAlias(cb) {
+  replaceTscAliasPaths().then(cb)
+}
+
+function sass(cb, path) {
+  return gulp
+    .src(path || 'src/**/*.scss', { base: './src' })
+    .pipe(sassPlugin().on('error', sassPlugin.logError))
+    .pipe(renamePlugin({ extname: '.wxss' }))
+    .pipe(gulp.dest(dist))
+}
+
+function assets(cb, path) {
+  return gulp
+    .src(path || ['src/**/*.*', '!src/**/*.(ts|scss)'], { base: './src', encoding: false })
+    .pipe(gulp.dest(dist))
+}
+
+function watch() {
+  function handler(path) {
+    if (path.endsWith('.ts')) return gulp.series(typescript.bind(null, null, path), tsAlias)()
+    else if (path.endsWith('.scss')) return sass(null, path)
+    else return assets(null, path)
+  }
+  gulp.watch('src/**/*').on('add', handler).on('change', handler)
+}
+
+/**
+ * --------------------
+ * 导出任务
+ * --------------------
+ */
+const build = gulp.series(clean, gulp.parallel(gulp.series(typescript, tsAlias), sass, assets))
+exports.build = build
+
+exports.watch = gulp.series(build, watch)

package/templates/miniprogram/package.json

@@ -0,0 +1,22 @@
+{
+  "private": true,
+  "name": "project",
+  "version": "1.0.0",
+  "scripts": {
+    "watch": "gulp watch",
+    "build": "gulp build"
+  },
+  "devDependencies": {
+    "@stdex/presets-eslint-typescript": "workspace:*",
+    "@stdex/presets-prettier": "workspace:*",
+    "@stdex/presets-typescript": "workspace:*",
+    "@swc/core": "latest",
+    "gulp": "latest",
+    "gulp-rename": "latest",
+    "gulp-sass": "latest",
+    "gulp-swc": "latest",
+    "sass": "latest",
+    "tsc-alias": "latest"
+  },
+  "prettier": "@stdex/presets-prettier/prettierrc"
+}

package/templates/miniprogram/project.config.json

@@ -0,0 +1,31 @@
+{
+  "appid": "{{appid}}",
+  "compileType": "miniprogram",
+  "condition": {},
+  "description": "项目配置文件",
+  "editorSetting": {
+    "tabIndent": "insertSpaces",
+    "tabSize": 2
+  },
+  "libVersion": "widelyUsed",
+  "miniprogramRoot": "dist/",
+  "packOptions": {
+    "ignore": [],
+    "include": []
+  },
+  "setting": {
+    "babelSetting": {
+      "ignore": [],
+      "disablePlugins": [],
+      "outputPath": ""
+    },
+    "coverView": true,
+    "minified": true,
+    "postcss": true,
+    "showShadowRootInWxmlPanel": true,
+    "skylineRenderEnable": true
+  },
+  "simulatorType": "wechat",
+  "simulatorPluginLibVersion": {},
+  "srcMiniprogramRoot": "dist/"
+}

package/templates/miniprogram/project.private.config.json

@@ -0,0 +1,8 @@
+{
+  "description": "项目私有配置文件。此文件中的内容将覆盖 project.config.json 中的相同字段。项目的改动优先同步到此文件中。详见文档：https://developers.weixin.qq.com/miniprogram/dev/devtools/projectconfig.html",
+  "projectname": "{{appname}}",
+  "setting": {
+    "compileHotReLoad": true
+  },
+  "condition": {}
+}