@gogoal-fund/template-helper

模板编译工具，将源代码转换为模板格式，支持多种模板引擎和自定义规则。

🚀 功能特性

• 🔄 智能转换: 将源代码自动转换为模板格式
• 📝 多格式支持: 支持多种标记格式和模板引擎
• 🛠️ 高度可配置: 灵活的配置选项满足不同需求
• 📦 包处理: 特殊处理 package.json 文件
• 🎯 精确控制: 支持文件重命名、忽略规则等
• ⚡ 高性能: 基于 TypeScript 和 ES 模块

📦 安装

npm install @gogoal-fund/template-helper
# 或者
pnpm add @gogoal-fund/template-helper

🎯 快速开始

基础用法

import { templatize } from '@gogoal-fund/template-helper'

// 简单编译
const result = await templatize({
  sourceDir: './source',
  outputDir: './template'
})

console.log(`处理了 ${result.processedFiles} 个文件`)

高级配置

import { TemplateCompiler } from '@gogoal-fund/template-helper'

const compiler = new TemplateCompiler({
  textExtensions: ['.js', '.ts', '.vue', '.json', '.md'],
  ignore: ['node_modules', 'dist', '.git'],
  markerMap: {
    'PACKAGE_NAME': '<%= packageName %>',
    'VERSION': '<%= version %>',
    'DESCRIPTION': '<%= description %>'
  },
  ejsFiles: ['src/**/*.ts', 'package.json']
})

const result = await compiler.compile({
  sourceDir: './my-source',
  outputDir: './my-template',
  configPath: './template.config.json'
})

📋 配置选项

TemplateConfig

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | textExtensions | string[] | ['.js', '.ts', '.jsx', '.tsx', '.vue', '.json', '.md', '.html', '.css', '.txt'] | 文本文件扩展名列表 | | ignore | string[] | ['node_modules', 'dist', '.git', 'coverage'] | 忽略的文件/目录模式 | | renameMap | Record<string, string> | {} | 文件重命名映射 | | packageReplacements | Record<string, any> | {} | package.json 替换规则 | | markerMap | Record<string, string> | {} | 标记替换映射 | | ejsFiles | string[] | [] | 需要添加 .ejs 扩展名的文件 |

TemplatizeOptions

| 属性 | 类型 | 必需 | 描述 | |------|------|------|------| | sourceDir | string | ✅ | 源代码目录 | | outputDir | string | ✅ | 输出目录 | | configPath | string | ❌ | 配置文件路径 | | config | TemplateConfig | ❌ | 内联配置 |

🎨 模板标记规范

支持三种标记格式：

1. 块注释格式

/* TEMPLATE:PACKAGE_NAME */
old-package-name
/* END_TEMPLATE:PACKAGE_NAME */

2. 行注释格式

// TEMPLATE:VERSION START
1.0.0
// TEMPLATE:VERSION END

3. 简单标记格式

const description = '[[DESCRIPTION]]'

📝 配置文件示例

创建 templatize.config.json:

{
  "textExtensions": [".js", ".ts", ".vue", ".json", ".md"],
  "ignore": ["node_modules", "dist", ".git", "coverage", "*.log"],
  "renameMap": {
    "example.config.js": "config.template.js"
  },
  "packageReplacements": {
    "name": "<%= packageName %>",
    "version": "<%= version %>",
    "description": "<%= description %>",
    "author": "<%= author %>"
  },
  "markerMap": {
    "PACKAGE_NAME": "<%= packageName %>",
    "VERSION": "<%= version %>",
    "DESCRIPTION": "<%= description %>",
    "AUTHOR": "<%= author %>",
    "CURRENT_YEAR": "<%= new Date().getFullYear() %>"
  },
  "ejsFiles": [
    "src/**/*.ts",
    "src/**/*.js",
    "README.md",
    "package.json"
  ]
}

🛠️ 使用场景

1. 项目脚手架生成

// 将项目模板转换为脚手架模板
await templatize({
  sourceDir: './my-project',
  outputDir: './scaffolding-template',
  config: {
    markerMap: {
      'PROJECT_NAME': '<%= projectName %>',
      'AUTHOR_NAME': '<%= authorName %>'
    },
    ejsFiles: ['package.json', 'README.md', 'src/**/*.ts']
  }
})

2. 组件库模板化

// 将组件转换为可配置模板
const compiler = new TemplateCompiler({
  markerMap: {
    'COMPONENT_NAME': '<%= componentName %>',
    'COMPONENT_PREFIX': '<%= prefix %>'
  },
  packageReplacements: {
    'name': '@<%= scope %>/<%= componentName %>',
    'description': '<%= description %>'
  }
})

3. 文档模板生成

// 生成文档模板
await templatize({
  sourceDir: './docs-source',
  outputDir: './docs-template',
  config: {
    markerMap: {
      'PROJECT_TITLE': '<%= title %>',
      'VERSION': '<%= version %>',
      'BUILD_DATE': '<%= new Date().toISOString() %>'
    }
  }
})

🔧 CLI 使用

创建 CLI 脚本：

#!/usr/bin/env node
import { templatize } from '@gogoal-fund/template-helper'
import { join } from 'path'

const sourceDir = process.argv[2] || './source'
const outputDir = process.argv[3] || './template'
const configPath = join(sourceDir, 'templatize.config.json')

try {
  const result = await templatize({
    sourceDir,
    outputDir,
    configPath
  })
  
  console.log('✅ 模板编译完成!')
  console.log(`📊 处理文件: ${result.processedFiles}`)
  console.log(`⏱️ 耗时: ${result.duration}ms`)
} catch (error) {
  console.error('❌ 编译失败:', error.message)
  process.exit(1)
}

📊 最佳实践

1. 目录结构建议

my-template/
├── source/                 # 源代码目录
│   ├── templatize.config.json
│   ├── package.json
│   ├── src/
│   └── docs/
├── template/               # 输出目录
├── scripts/
│   └── build-template.js   # 编译脚本
└── README.md

2. 配置分离

• 将配置放在 templatize.config.json 中
• 使用环境变量控制不同环境的配置
• 支持配置继承和覆盖

3. 标记命名规范

• 使用大写字母和下划线：PACKAGE_NAME
• 保持语义化：CURRENT_YEAR, BUILD_DATE
• 避免与代码冲突的名称

4. 模板验证

import { TemplateCompiler } from '@gogoal-fund/template-helper'

// 编译后验证
const result = await compiler.compile(options)
if (result.processedFiles === 0) {
  throw new Error('没有文件被处理，请检查配置')
}

🤝 贡献指南

欢迎贡献代码！请确保：

1. 添加测试用例
2. 更新文档
3. 遵循代码规范
4. 提交前运行测试

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 构建
pnpm build

# 开发模式
pnpm dev

📄 许可证

MIT License

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 更新日志