0
# Template System
1
2
Comprehensive template processing engine for generating project files with variable substitution. The CLI uses template files with `.tmpl` extensions to generate customized project files based on user configuration.
3
4
## Capabilities
5
6
### Template Processing
7
8
Process template files with variable substitution using EJS-style syntax.
9
10
```javascript { .api }
11
/**
12
* Template variables available during project creation
13
*/
14
interface TemplateVariables {
15
name: string; // Project display name (e.g., "My Awesome Project")
16
npmname: string; // NPM package name (e.g., "@company/my-project")
17
umdname: string; // UMD global variable name (e.g., "MyProject")
18
username: string; // GitHub username (e.g., "johndoe")
19
type: 'js' | 'ts'; // Template type selection
20
manager: 'npm' | null; // Package manager preference
21
version: string; // CLI version used to create project
22
pathname: string; // Directory name to create
23
}
24
25
// Template syntax (EJS-compatible):
26
// <%=variable%> - Output variable value with HTML escaping
27
// <%-variable%> - Output variable value without escaping
28
// <% if (condition) { %> - Conditional blocks
29
// <% } %> - End conditional
30
// <% for (var i=0; i<items.length; i++) { %> - Loop constructs
31
// <% } %> - End loop
32
```
33
34
**Usage Examples:**
35
36
```javascript
37
// In template file (package.json.tmpl):
38
{
39
"name": "<%=npmname%>",
40
"version": "1.0.0",
41
"description": "<%=name%> - Generated by @js-lib/cli",
42
"author": "<%=username%>",
43
"repository": {
44
"type": "git",
45
"url": "git://github.com/<%=username%>/<%=name%>.git"
46
},
47
"main": "dist/<%=umdname%>.cjs.js",
48
"module": "dist/<%=umdname%>.esm.js"
49
}
50
51
// In template file (README.md.tmpl):
52
# [<%=name%>](https://github.com/<%=username%>/<%=name%>)
53
54
<% if (type === 'ts') { %>
55
This project is written in TypeScript for better type safety.
56
<% } else { %>
57
This project is written in JavaScript.
58
<% } %>
59
60
## Installation
61
62
```bash
63
npm install <%=npmname%>
64
```
65
```
66
67
### JavaScript Template Structure
68
69
The JavaScript template (`module-js`) provides a complete project structure with modern tooling.
70
71
```javascript { .api }
72
// JavaScript template files include:
73
interface JavaScriptTemplate {
74
// Configuration files
75
'jslib.json.tmpl': string; // Project metadata
76
'package.json.tmpl': string; // NPM package configuration
77
'rollup.config.js.tmpl': string; // Build configuration
78
'.eslintrc.js.tmpl': string; // Linting rules
79
80
// Documentation templates
81
'README.md.tmpl': string; // English README
82
'README.zh-CN.md.tmpl': string; // Chinese README
83
'CHANGELOG.md.tmpl': string; // Change log
84
'license.tmpl': string; // MIT license
85
86
// Source code templates
87
'src/index.js.tmpl': string; // Main source file
88
'test/test.js.tmpl': string; // Unit tests
89
'demo/demo-node.js.tmpl': string; // Node.js demo
90
91
// Build and CI templates
92
'.github/workflows/ci.yml.tmpl': string; // GitHub Actions
93
'build-rollup.cjs.tmpl': string; // Rollup CommonJS config
94
'commitlint.config.js.tmpl': string; // Commit linting
95
}
96
97
// Generated project structure:
98
project-name/
99
├── src/ # Source code (ES6+)
100
├── test/ # Unit tests (Mocha)
101
├── demo/ # Usage examples
102
├── dist/ # Compiled output
103
├── .github/ # CI/CD workflows
104
├── package.json # NPM configuration
105
├── rollup.config.js # Build configuration
106
├── .eslintrc.js # Code quality rules
107
├── jslib.json # Project metadata
108
└── README.md # Documentation
109
```
110
111
### TypeScript Template Structure
112
113
The TypeScript template (`module-ts`) provides the same structure with TypeScript support.
114
115
```javascript { .api }
116
// TypeScript template files include:
117
interface TypeScriptTemplate {
118
// Additional TypeScript-specific files
119
'tsconfig.json.tmpl': string; // TypeScript configuration
120
'src/index.ts.tmpl': string; // TypeScript source file
121
'test/test.ts.tmpl': string; // TypeScript unit tests
122
'typings/index.d.ts.tmpl': string; // Type declarations
123
124
// Same structure as JavaScript template but with TypeScript support
125
// All .js files become .ts files with proper type annotations
126
}
127
128
// Generated TypeScript project includes:
129
// - Full TypeScript compilation pipeline
130
// - Type declaration generation (.d.ts files)
131
// - TypeScript-aware testing setup
132
// - ESLint with TypeScript parser
133
// - Source maps for debugging
134
```
135
136
### Template Variable Usage
137
138
Templates use the provided variables to customize generated content.
139
140
**Common Template Patterns:**
141
142
```javascript
143
// Package.json generation
144
{
145
"name": "<%=npmname%>",
146
"version": "1.0.0",
147
"main": "dist/<%=umdname%>.cjs.js",
148
"module": "dist/<%=umdname%>.esm.js",
149
"browser": "dist/<%=umdname%>.js",
150
"author": "<%=username%>",
151
"repository": {
152
"url": "git://github.com/<%=username%>/<%=name%>.git"
153
}
154
}
155
156
// README generation with conditional content
157
# [<%=name%>](https://github.com/<%=username%>/<%=name%>)
158
159
<% if (type === 'ts') { %>
160
[](https://www.typescriptlang.org/)
161
<% } %>
162
163
## Installation
164
165
```bash
166
npm install <%=npmname%>
167
```
168
169
## Usage
170
171
<% if (type === 'ts') { %>
172
```typescript
173
import <%=umdname%> from '<%=npmname%>';
174
<% } else { %>
175
```javascript
176
const <%=umdname%> = require('<%=npmname%>');
177
<% } %>
178
179
// Your code here
180
```
181
182
// License generation
183
MIT License
184
185
Copyright (c) <%= new Date().getFullYear() %> <%=username%>
186
187
Permission is hereby granted, free of charge, to any person obtaining a copy...
188
```
189
190
### Template Processing Engine
191
192
The template system is built on the `template_js` library providing powerful text processing.
193
194
```javascript { .api }
195
/**
196
* Template processing features:
197
*/
198
interface TemplateEngine {
199
// Variable interpolation
200
variableSubstitution: true; // <%=variable%> syntax
201
htmlEscaping: true; // Automatic HTML escaping
202
rawOutput: true; // <%-variable%> for unescaped output
203
204
// Control structures
205
conditionals: true; // <% if/else/endif %>
206
loops: true; // <% for/while %>
207
javascript: true; // <% arbitrary JavaScript %>
208
209
// Advanced features
210
includes: false; // Template inclusion (not used)
211
filters: false; // Output filters (not used)
212
helpers: false; // Custom helper functions (not used)
213
}
214
215
// Processing workflow:
216
// 1. Read .tmpl file from template directory
217
// 2. Apply variable substitution using provided data
218
// 3. Execute any embedded JavaScript logic
219
// 4. Write processed content to destination file
220
// 5. Remove .tmpl extension from destination filename
221
```
222
223
### Template Customization
224
225
Templates can be extended or modified for specific use cases.
226
227
**Custom Template Variables:**
228
229
```javascript
230
// Extended template data can include:
231
const customTemplateData = {
232
// Standard variables
233
name: 'my-project',
234
npmname: '@company/my-project',
235
umdname: 'MyProject',
236
username: 'johndoe',
237
type: 'ts',
238
version: '3.0.6',
239
240
// Custom additions
241
description: 'My awesome project description',
242
keywords: ['javascript', 'library', 'utility'],
243
license: 'MIT',
244
year: new Date().getFullYear(),
245
dependencies: {
246
'lodash': '^4.17.21'
247
}
248
};
249
```
250
251
**Template File Naming:**
252
253
```bash
254
# Template files must use .tmpl extension
255
package.json.tmpl # Becomes package.json
256
README.md.tmpl # Becomes README.md
257
src/index.js.tmpl # Becomes src/index.js
258
.eslintrc.js.tmpl # Becomes .eslintrc.js
259
260
# Directory structure is preserved
261
template/base/src/index.js.tmpl → project/src/index.js
262
template/base/test/test.js.tmpl → project/test/test.js
263
```
264
265
## Types
266
267
```javascript { .api }
268
// Template data structure passed to all templates
269
interface ProjectTemplateData {
270
pathname: string; // Directory name for the project
271
name: string; // Human-readable project name
272
npmname: string; // NPM package name (may include scope)
273
umdname: string; // Global variable name for UMD builds
274
username: string; // GitHub username for repository URLs
275
type: 'js' | 'ts'; // Template type selection
276
manager: 'npm' | null; // Package manager choice
277
version: string; // CLI version that created the project
278
}
279
280
// Template processing options
281
interface TemplateOptions {
282
cover?: boolean; // Whether to overwrite existing files (default: true)
283
encoding?: string; // File encoding (default: 'utf8')
284
}
285
286
// Template file structure
287
interface TemplateFile {
288
path: string; // Relative path within template directory
289
content: string; // Template content with placeholders
290
destination: string; // Output path (without .tmpl extension)
291
}
292
```