@temir.ra/create-ts-lib 0.6.3 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +173 -189
- package/buildinfo.txt +1 -1
- package/dist/cli.bundle.js +2 -2
- package/dist/cli.bundle.js.map +3 -3
- package/package.json +12 -7
- package/{template/scripts/build-lib-bundle.ts → scripts/build-bundle.ts} +20 -15
- package/scripts/buildinfo.ts +25 -0
- package/scripts/cdn-rewrite-map.json +1 -0
- package/template/CHANGELOG-template.md +49 -0
- package/template/CHANGELOG.md +1 -1
- package/template/README-template.md +453 -0
- package/template/README.md +12 -18
- package/template/buildinfo-template.txt +1 -0
- package/template/buildinfo.txt +1 -0
- package/template/gitignore +2 -2
- package/template/package.json +13 -9
- package/template/scripts/build-bundle.ts +161 -0
- package/template/{src → scripts}/dev.ts +1 -1
- package/template/tsconfig.json +37 -38
- package/dist/cli.d.ts +0 -3
- package/dist/cli.d.ts.map +0 -1
- package/dist/cli.js +0 -26
- package/dist/constants.d.ts +0 -7
- package/dist/constants.d.ts.map +0 -1
- package/dist/constants.js +0 -8
- package/template/tsconfig.build.json +0 -19
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
# Version 0
|
|
2
2
|
|
|
3
|
+
## 0.7.1
|
|
4
|
+
|
|
5
|
+
1. Updated `template/` files from `@temir.ra/workspace@0.4.1` template.
|
|
6
|
+
|
|
7
|
+
## 0.7.0
|
|
8
|
+
|
|
9
|
+
1. Updated `.gitignore`: added `bun.lock`, `buildinfo-template.txt`, `CHANGELOG-template.md`, `README-template.md`; replaced nested `template/.gitignore` with `template/gitignore` to prevent template files from being excluded during distribution.
|
|
10
|
+
2. Removed `CLAUDE.md`, `AGENTS.md`, and `src/dev.ts` from root and template.
|
|
11
|
+
3. Overhauled the generated `package.json`: added `private: false`; removed `sideEffects: false`; added build scripts to published `files`; updated `clean:tsbuildinfo` to `rm -f *.tsbuildinfo || true`; renamed `build:lib-bundle` to `build:bundle`; removed `build:lib` and `dev` scripts; added `reinstall` script; bumped typescript to `^6.0.2`.
|
|
12
|
+
4. Updated the generated `tsconfig.json`: changed `target` to `ESNext`; removed `DOM` from `lib`; added `types: ["bun"]`.
|
|
13
|
+
5. Removed generated `tsconfig.build.json`; TSC compilation is now opt-in and documented in `README.md`.
|
|
14
|
+
6. Renamed `scripts/build-lib-bundle.ts` to `scripts/build-bundle.ts` in root and template; updated to produce ESM and IIFE browser bundles; added to published `files`; updated CDN rewrite plugin filter.
|
|
15
|
+
7. Extracted path constants from `src/cli.ts` to `src/constants.ts`; CLI now copies `README.md` as `README-template.md` to generated projects; improved error message for missing package name argument; moved `template/src/dev.ts` to `template/scripts/dev.ts`.
|
|
16
|
+
8. Updated `scripts/buildinfo.ts` in root and template: reads version from `package.json` instead of `npm_package_version` env var; handles pre-existing `+` in version string.
|
|
17
|
+
9. Refactored `template/tests/buildinfo.test.ts` to use a proper semver regex.
|
|
18
|
+
10. Overhauled `README.md`: new documentation structure with build strategies overview, `package.json` and `tsconfig.json` sections referencing `create-workspace`, opt-in TSC Compilation section, `bin` field documentation, `scripts/dev.ts` section; removed `CLAUDE.md`/`AGENTS.md` section.
|
|
19
|
+
11. Updated from `@temir.ra/template@0.1.3` template.
|
|
20
|
+
|
|
3
21
|
## 0.6.3
|
|
4
22
|
|
|
5
23
|
1. Cleaned up dormant package scripts.
|
package/README.md
CHANGED
|
@@ -6,12 +6,15 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
|
|
|
6
6
|
|
|
7
7
|
1. [Quick Start](#quick-start)
|
|
8
8
|
2. [Documentation](#documentation)
|
|
9
|
-
1. [`
|
|
10
|
-
2. [`package.json`](#packagejson)
|
|
11
|
-
3. [
|
|
12
|
-
4. [
|
|
13
|
-
5. [
|
|
14
|
-
|
|
9
|
+
1. [`package.json`](#packagejson)
|
|
10
|
+
2. [`"bin"` field in `package.json`](#bin-field-in-packagejson)
|
|
11
|
+
3. [`scripts/dev.ts`](#scriptsdevts)
|
|
12
|
+
4. [`tsconfig.json`](#tsconfigjson)
|
|
13
|
+
5. [TSC Compilation](#tsc-compilation)
|
|
14
|
+
1. [`tsconfig.build.json`](#tsconfigbuildjson)
|
|
15
|
+
2. [`package.json`](#packagejson-1)
|
|
16
|
+
6. [Script `scripts/build-bundle.ts`](#script-scriptsbuild-bundlets)
|
|
17
|
+
1. [CDN Map `scripts/cdn-rewrite-map.json`](#cdn-map-scriptscdn-rewrite-mapjson)
|
|
15
18
|
7. [Asset Resolution](#asset-resolution)
|
|
16
19
|
1. [Externalized - loaded from CDN or `node_modules/`](#externalized---loaded-from-cdn-or-node_modules)
|
|
17
20
|
2. [Bundled - absorbed into the consumer's output](#bundled---absorbed-into-the-consumers-output)
|
|
@@ -20,33 +23,32 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
|
|
|
20
23
|
2. [Accessing assets](#accessing-assets)
|
|
21
24
|
3. [README statement for library consumers](#readme-statement-for-library-consumers)
|
|
22
25
|
4. [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer)
|
|
23
|
-
8. [`src/dev.ts`](#srcdevts)
|
|
24
26
|
3. [DevOps](#devops)
|
|
25
27
|
1. [Change Management](#change-management)
|
|
26
28
|
2. [Publish](#publish)
|
|
27
29
|
|
|
28
30
|
# Quick Start
|
|
29
31
|
|
|
30
|
-
*`bun create` caches the template package - a newer published version will not be picked up automatically. Pin the version or clear the cache to use the latest.*
|
|
31
|
-
|
|
32
32
|
```bash
|
|
33
33
|
# placeholder:
|
|
34
|
+
# <TEMPLATE_PACKAGE: @temir.ra/create-ts-lib
|
|
35
|
+
# <TEMPLATE_NAME: @temir.ra/ts-lib
|
|
34
36
|
# <NEW_PACKAGE: <NEW_PACKAGE>
|
|
37
|
+
# is used as:
|
|
38
|
+
# - the path where the package is created
|
|
39
|
+
# - the "name" field in the generated package.json
|
|
35
40
|
# <@_VERSION: <@_VERSION>
|
|
36
41
|
|
|
37
|
-
#
|
|
42
|
+
# pinned version
|
|
38
43
|
bun info "@temir.ra/create-ts-lib" version
|
|
39
|
-
# create a new library from the template version
|
|
40
44
|
bun create --no-install --no-git "@temir.ra/ts-lib<@_VERSION>" <NEW_PACKAGE>
|
|
41
45
|
|
|
42
|
-
#
|
|
43
|
-
|
|
44
|
-
# clear package manager cache to ensure the latest template version is used
|
|
46
|
+
# latest
|
|
47
|
+
# clear the cache to pick up the latest version
|
|
45
48
|
bun pm cache rm
|
|
46
|
-
# create a new library from the latest template version
|
|
47
49
|
bun create --no-install --no-git "@temir.ra/ts-lib" <NEW_PACKAGE>
|
|
48
50
|
|
|
49
|
-
#
|
|
51
|
+
# templates only copy files, run install and any setup scripts manually
|
|
50
52
|
cd <NEW_PACKAGE>
|
|
51
53
|
bun install
|
|
52
54
|
```
|
|
@@ -55,71 +57,144 @@ bun install
|
|
|
55
57
|
|
|
56
58
|
The following sections explain the configurations and conventions baked into the generated package. Useful when adapting it to fit specific needs.
|
|
57
59
|
|
|
58
|
-
|
|
60
|
+
The central addition over [`create-workspace`](https://www.npmjs.com/package/@temir.ra/create-workspace) is a build pipeline for distributing the library. Two build strategies are supported:
|
|
61
|
+
|
|
62
|
+
- **Bundling** (`scripts/build-bundle.ts`) - generated by default; bundles the library to ESM and IIFE formats.
|
|
63
|
+
- **TSC compilation** (`tsconfig.build.json` + `build:tsc`) - optional, not generated by default; compiles source files one-for-one to ESM JavaScript and declaration files.
|
|
64
|
+
|
|
65
|
+
Both strategies can be combined.
|
|
66
|
+
|
|
67
|
+
## `package.json`
|
|
68
|
+
|
|
69
|
+
Selected fields are documented in the [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-workspace#packagejson).
|
|
70
|
+
|
|
71
|
+
See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
|
|
72
|
+
|
|
73
|
+
The following lists the additions and overrides relative to [`create-workspace`](https://www.npmjs.com/package/@temir.ra/create-workspace#packagejson).
|
|
59
74
|
|
|
60
|
-
|
|
75
|
+
The generated package is pre-configured with `build:bundle` only. See [TSC Compilation](#tsc-compilation) and [`"bin"` field](#bin-field-in-packagejson) for extending it.
|
|
61
76
|
|
|
62
77
|
```json
|
|
63
78
|
{
|
|
64
79
|
|
|
65
|
-
|
|
80
|
+
// ... ,
|
|
81
|
+
|
|
82
|
+
// the package is anticipated to be published
|
|
83
|
+
"private": false,
|
|
84
|
+
|
|
85
|
+
// treats all .js files as ES modules; use .cjs extension for CommonJS files
|
|
86
|
+
"type": "module",
|
|
87
|
+
|
|
88
|
+
// package entry points
|
|
89
|
+
//
|
|
90
|
+
// scripts/build-bundle.ts (non-standard) export condition:
|
|
91
|
+
// "entrypoint" - locates the source entry point for bundling
|
|
92
|
+
//
|
|
93
|
+
// standard export conditions:
|
|
94
|
+
// "types" - TypeScript consumers; resolves to the declaration files;
|
|
95
|
+
// "browser" - browser bundler consumers; resolves to the bundled output
|
|
96
|
+
// "import" - ESM consumers; resolves to the compiled module output
|
|
97
|
+
"exports": {
|
|
98
|
+
".": {
|
|
99
|
+
"entrypoint": "./src/index.ts",
|
|
100
|
+
"types": "./dist/index.d.ts",
|
|
101
|
+
"browser": "./dist/index.bundle.js",
|
|
102
|
+
"import": "./dist/index.js"
|
|
103
|
+
}
|
|
104
|
+
},
|
|
105
|
+
|
|
106
|
+
// convenience alias for source-execution only - does NOT survive transpilation or bundling
|
|
107
|
+
// NOT for use in source files compiled by tsconfig.build.json
|
|
108
|
+
// the .js extension is required in import statements (nodenext compliance)
|
|
109
|
+
"imports": {
|
|
110
|
+
"#src/*.js": "./src/*.ts"
|
|
111
|
+
},
|
|
112
|
+
|
|
113
|
+
// CLI entry point
|
|
114
|
+
"bin": "./dist/cli.bundle.js",
|
|
115
|
+
|
|
116
|
+
// files to include in the published package
|
|
117
|
+
"files": [
|
|
118
|
+
"scripts/buildinfo.ts",
|
|
119
|
+
"scripts/build-bundle.ts",
|
|
120
|
+
"scripts/cdn-rewrite-map.json",
|
|
121
|
+
"dist",
|
|
122
|
+
"CHANGELOG.md",
|
|
123
|
+
"buildinfo.txt"
|
|
124
|
+
],
|
|
125
|
+
|
|
126
|
+
"scripts": {
|
|
127
|
+
|
|
128
|
+
// ... ,
|
|
129
|
+
|
|
130
|
+
// executed before build; generates buildinfo.txt
|
|
131
|
+
"prebuild": "bun run buildinfo",
|
|
132
|
+
|
|
133
|
+
// convenience script to run the build steps in sequence
|
|
134
|
+
"build": "bun run build:tsc && bun run build:bundle && bun run build:cli-bundle",
|
|
135
|
+
|
|
136
|
+
// compiles the library to declaration files and ESM JavaScript in dist/
|
|
137
|
+
"build:tsc": "tsc --project tsconfig.build.json",
|
|
66
138
|
|
|
67
|
-
//
|
|
68
|
-
|
|
69
|
-
|
|
139
|
+
// bundles the library into ESM and IIFE formats for distribution
|
|
140
|
+
"build:bundle": "bun run scripts/build-bundle.ts",
|
|
141
|
+
|
|
142
|
+
// bundles the CLI into a single file for distribution; requires the "bin" field to be set to the bundled output
|
|
143
|
+
"build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
|
|
70
144
|
|
|
71
|
-
|
|
72
|
-
// ES module syntax: import/export statements (as opposed to CommonJS require()/module.exports)
|
|
73
|
-
"module": "ESNext",
|
|
145
|
+
}
|
|
74
146
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## `"bin"` field in `package.json`
|
|
151
|
+
|
|
152
|
+
For CLI packages, add the following to `package.json`:
|
|
80
153
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
154
|
+
```json
|
|
155
|
+
{
|
|
156
|
+
// ... ,
|
|
157
|
+
"bin": "./dist/cli.bundle.js",
|
|
158
|
+
// ... ,
|
|
159
|
+
"scripts": {
|
|
160
|
+
// ... ,
|
|
161
|
+
"build": "... && bun run build:cli-bundle",
|
|
162
|
+
// ... ,
|
|
163
|
+
"build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
84
167
|
|
|
85
|
-
|
|
86
|
-
"strict": true,
|
|
168
|
+
`src/cli.ts` must begin with a hashbang so the OS knows which interpreter to invoke when the binary is executed directly. Bun preserves it in the bundled output.
|
|
87
169
|
|
|
88
|
-
|
|
89
|
-
|
|
170
|
+
```typescript
|
|
171
|
+
#!/usr/bin/env node
|
|
172
|
+
```
|
|
90
173
|
|
|
91
|
-
|
|
92
|
-
"noUncheckedIndexedAccess": true,
|
|
174
|
+
If the package exports a CLI only and is not intended to be imported in other packages, the `exports` field can be omitted.
|
|
93
175
|
|
|
94
|
-
|
|
95
|
-
"exactOptionalPropertyTypes": true,
|
|
176
|
+
## `scripts/dev.ts`
|
|
96
177
|
|
|
97
|
-
|
|
98
|
-
"noImplicitOverride": true,
|
|
178
|
+
Development scratchpad. Execute it manually with `bun run --watch scripts/dev.ts`. Useful to test and explore library code during development.
|
|
99
179
|
|
|
100
|
-
|
|
101
|
-
"isolatedDeclarations": true,
|
|
180
|
+
## `tsconfig.json`
|
|
102
181
|
|
|
103
|
-
|
|
104
|
-
"esModuleInterop": true,
|
|
182
|
+
Selected fields are documented in the [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-workspace#tsconfigjson).
|
|
105
183
|
|
|
106
|
-
|
|
107
|
-
"composite": true,
|
|
184
|
+
See the TypeScript documentation on [tsconfig.json](https://www.typescriptlang.org/tsconfig) for detailed explanations of all options.
|
|
108
185
|
|
|
109
|
-
|
|
110
|
-
"skipLibCheck": true,
|
|
186
|
+
The following lists the additions and overrides relative to [`create-workspace`](https://www.npmjs.com/package/@temir.ra/create-workspace#tsconfigjson).
|
|
111
187
|
|
|
112
|
-
|
|
113
|
-
|
|
188
|
+
```json
|
|
189
|
+
{
|
|
114
190
|
|
|
115
|
-
|
|
116
|
-
"forceConsistentCasingInFileNames": true,
|
|
191
|
+
"compilerOptions": {
|
|
117
192
|
|
|
118
|
-
//
|
|
119
|
-
"resolveJsonModule": true,
|
|
193
|
+
// ... ,
|
|
120
194
|
|
|
121
195
|
// emit .d.ts declaration files
|
|
122
196
|
"declaration": true,
|
|
197
|
+
|
|
123
198
|
// emit .d.ts.map files mapping declarations back to source
|
|
124
199
|
"declarationMap": true,
|
|
125
200
|
|
|
@@ -127,32 +202,40 @@ See the typescriptlang documentation on [tsconfig.json](https://www.typescriptla
|
|
|
127
202
|
"emitDeclarationOnly": true,
|
|
128
203
|
|
|
129
204
|
// output directory for emitted files
|
|
130
|
-
"outDir": "./dist"
|
|
131
|
-
|
|
132
|
-
// root directory mirrored into outDir; set to project root during development, overridden to src/ in tsconfig.build.json (TS6 default — not set in actual config)
|
|
133
|
-
"rootDir": ".",
|
|
205
|
+
"outDir": "./dist"
|
|
134
206
|
|
|
135
207
|
},
|
|
136
208
|
|
|
137
|
-
// includes src/, tests/, and scripts/ for type-checking and IDE support; overridden in tsconfig.build.json
|
|
138
209
|
"include": [
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
"scripts/**/*.
|
|
142
|
-
|
|
210
|
+
// ... ,
|
|
211
|
+
// include `scripts/**/*.json` for script configuration files
|
|
212
|
+
"scripts/**/*.json",
|
|
213
|
+
// include `src/**/*.ts` for source files
|
|
214
|
+
"src/**/*.ts"
|
|
143
215
|
],
|
|
144
216
|
"exclude": [
|
|
145
|
-
|
|
217
|
+
// ... ,
|
|
218
|
+
// exclude `dist/`
|
|
146
219
|
"dist"
|
|
147
220
|
]
|
|
148
221
|
|
|
149
222
|
}
|
|
150
223
|
```
|
|
151
224
|
|
|
152
|
-
`tsconfig.json` is the development configuration. `tsconfig.build.json` extends it, narrowing scope to `src/` and enabling JavaScript output for distribution.
|
|
153
|
-
|
|
154
225
|
`declarationMap: true` enables go-to-definition for npm/bun consumers. For this to work, the original `.ts` source files must be accessible to the consumer. Consider adding `src/` to the `files` field in `package.json`.
|
|
155
226
|
|
|
227
|
+
## TSC Compilation
|
|
228
|
+
|
|
229
|
+
Not generated by default. Enables file-for-file tsc compilation of `src/` to ESM JavaScript and declaration files alongside bundling.
|
|
230
|
+
|
|
231
|
+
### `tsconfig.build.json`
|
|
232
|
+
|
|
233
|
+
Extends `tsconfig.json`, narrowing scope to `src/` only and switching to `nodenext` module resolution for strict ESM compliance.
|
|
234
|
+
|
|
235
|
+
Enables JavaScript output alongside declaration files for distribution.
|
|
236
|
+
|
|
237
|
+
Development files (`dev.ts`, `tests/`, `scripts/`) are excluded.
|
|
238
|
+
|
|
156
239
|
```json
|
|
157
240
|
{
|
|
158
241
|
|
|
@@ -172,11 +255,12 @@ See the typescriptlang documentation on [tsconfig.json](https://www.typescriptla
|
|
|
172
255
|
|
|
173
256
|
},
|
|
174
257
|
|
|
258
|
+
// include only src/ files for distribution
|
|
175
259
|
"include": [
|
|
176
260
|
"src/**/*.ts"
|
|
177
261
|
],
|
|
262
|
+
// exclude development files and directories from distribution
|
|
178
263
|
"exclude": [
|
|
179
|
-
"src/dev.ts",
|
|
180
264
|
"node_modules",
|
|
181
265
|
"dist",
|
|
182
266
|
"tests",
|
|
@@ -186,102 +270,30 @@ See the typescriptlang documentation on [tsconfig.json](https://www.typescriptla
|
|
|
186
270
|
}
|
|
187
271
|
```
|
|
188
272
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
|
|
273
|
+
### `package.json`
|
|
192
274
|
|
|
193
275
|
```json
|
|
194
276
|
{
|
|
195
|
-
|
|
196
|
-
"version": "0.0.0",
|
|
197
|
-
|
|
198
|
-
"description": "",
|
|
199
|
-
"author": "",
|
|
200
|
-
"license": "",
|
|
201
|
-
|
|
202
|
-
"keywords": ["typescript"],
|
|
203
|
-
|
|
204
|
-
"repository": {
|
|
205
|
-
"type": "git",
|
|
206
|
-
"url": ""
|
|
207
|
-
},
|
|
208
|
-
|
|
209
|
-
// treats all .js files as ES modules; use .cjs extension for CommonJS files
|
|
210
|
-
"type": "module",
|
|
211
|
-
|
|
212
|
-
// package entry points by consumer type
|
|
213
|
-
// "entrypoint" - custom condition; used by the bundle script to locate the source entry point
|
|
214
|
-
// "types" - TypeScript consumers; resolves to the declaration files; must precede "import" so TypeScript matches it before the JS condition
|
|
215
|
-
// "browser" - browser bundler consumers; resolves to the bundled output
|
|
216
|
-
// "import" - ESM consumers; resolves to the compiled module output
|
|
217
|
-
"exports": {
|
|
218
|
-
".": {
|
|
219
|
-
"entrypoint": "./src/index.ts",
|
|
220
|
-
"types": "./dist/index.d.ts",
|
|
221
|
-
"browser": "./dist/index.bundle.js",
|
|
222
|
-
"import": "./dist/index.js"
|
|
223
|
-
}
|
|
224
|
-
},
|
|
225
|
-
|
|
226
|
-
// package-internal import alias resolved natively by Node.js and Bun at runtime; key must start with #
|
|
227
|
-
// for use in dev.ts, tests/, and scripts/ only - NOT in library source files compiled by tsconfig.build.json
|
|
228
|
-
// the .js extension is required in import statements (nodenext compliance);
|
|
229
|
-
// the runtime maps it to the actual .ts source file via this field
|
|
230
|
-
"imports": {
|
|
231
|
-
"#src/*.js": "./src/*.ts"
|
|
232
|
-
},
|
|
233
|
-
|
|
234
|
-
// CLI entry point; omit if the package is not a CLI tool
|
|
235
|
-
"bin": "./dist/cli.bundle.js",
|
|
236
|
-
|
|
237
|
-
// files to include in the published package
|
|
238
|
-
"files": [
|
|
239
|
-
"dist",
|
|
240
|
-
"CHANGELOG.md",
|
|
241
|
-
"buildinfo.txt"
|
|
242
|
-
],
|
|
243
|
-
|
|
277
|
+
// ... ,
|
|
244
278
|
"scripts": {
|
|
245
|
-
|
|
246
|
-
"
|
|
247
|
-
"
|
|
248
|
-
"clean": "bun run clean:dist && bun run clean:tsbuildinfo",
|
|
249
|
-
|
|
250
|
-
// lifecycle hook; runs automatically before "build"; generates buildinfo.txt
|
|
251
|
-
"prebuild": "bun run scripts/buildinfo.ts",
|
|
252
|
-
|
|
253
|
-
"tests": "bun test",
|
|
254
|
-
|
|
255
|
-
"build": "bun run build:lib && bun run build:lib-bundle",
|
|
256
|
-
|
|
257
|
-
"build:lib": "tsc --project tsconfig.build.json",
|
|
258
|
-
// bundles the library into ESM and IIFE formats for distribution
|
|
259
|
-
"build:lib-bundle": "bun run scripts/build-lib-bundle.ts",
|
|
260
|
-
|
|
261
|
-
"typecheck": "tsc --noEmit",
|
|
262
|
-
|
|
263
|
-
// runs src/dev.ts in watch mode
|
|
264
|
-
"dev": "bun run --watch src/dev.ts"
|
|
265
|
-
|
|
266
|
-
},
|
|
267
|
-
"devDependencies": {
|
|
268
|
-
"@types/bun": "latest",
|
|
269
|
-
"typescript": "^6.0.2"
|
|
279
|
+
// ... ,
|
|
280
|
+
"build": "bun run build:tsc && bun run build:bundle",
|
|
281
|
+
"build:tsc": "tsc --project tsconfig.build.json"
|
|
270
282
|
}
|
|
271
283
|
}
|
|
272
284
|
```
|
|
273
285
|
|
|
274
|
-
## Script `scripts/
|
|
286
|
+
## Script `scripts/build-bundle.ts`
|
|
275
287
|
|
|
276
|
-
|
|
288
|
+
Bundles the library to ESM and IIFE formats. Entry points are resolved from the `entrypoint` condition in the `exports` field of `package.json`. Note, the `entrypoint` condition is a custom, non-standard export condition used solely for build tooling.
|
|
277
289
|
|
|
278
|
-
|
|
290
|
+
Import specifiers can be rewritten to CDN URLs via `scripts/cdn-rewrite-map.json`.
|
|
279
291
|
|
|
280
|
-
|
|
292
|
+
### CDN Map `scripts/cdn-rewrite-map.json`
|
|
281
293
|
|
|
282
|
-
|
|
294
|
+
Maps import specifiers to CDN URLs. During bundling, matching specifiers in source files are rewritten to their CDN equivalents.
|
|
283
295
|
|
|
284
|
-
|
|
296
|
+
`<VERSION>` in a URL is replaced with the version of the matching package from `package.json`.
|
|
285
297
|
|
|
286
298
|
```json
|
|
287
299
|
{
|
|
@@ -289,25 +301,6 @@ Maps import specifiers to CDN URLs. During bundling, matching specifiers in sour
|
|
|
289
301
|
}
|
|
290
302
|
```
|
|
291
303
|
|
|
292
|
-
## `"bin"` field in `package.json`
|
|
293
|
-
|
|
294
|
-
For CLI packages, add the following to `package.json`:
|
|
295
|
-
|
|
296
|
-
```json
|
|
297
|
-
{
|
|
298
|
-
"exports": ...,
|
|
299
|
-
"bin": "./dist/cli.bundle.js",
|
|
300
|
-
"files": ...,
|
|
301
|
-
"scripts": {
|
|
302
|
-
...,
|
|
303
|
-
"build": "... && bun run build:cli-bundle",
|
|
304
|
-
...,
|
|
305
|
-
"build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external",
|
|
306
|
-
...,
|
|
307
|
-
}
|
|
308
|
-
}
|
|
309
|
-
```
|
|
310
|
-
|
|
311
304
|
## Asset Resolution
|
|
312
305
|
|
|
313
306
|
The key question to ask is: **does my library retain its own URL at runtime?** Everything else follows from it.
|
|
@@ -393,7 +386,7 @@ import { fileURLToPath } from 'url';
|
|
|
393
386
|
const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsUrl)), 'utf-8'));
|
|
394
387
|
```
|
|
395
388
|
|
|
396
|
-
|
|
389
|
+
#### README statement for library consumers
|
|
397
390
|
|
|
398
391
|
```markdown
|
|
399
392
|
## Asset resolution
|
|
@@ -416,27 +409,18 @@ consumer output/
|
|
|
416
409
|
|
|
417
410
|
From the bundle's perspective `assets/<@SCOPE>/<LIB_NAME>/` is at the same directory level as `bundle.js`, so `new URL('assets/<@SCOPE>/<LIB_NAME>/...', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
|
|
418
411
|
|
|
419
|
-
## `src/dev.ts`
|
|
420
|
-
|
|
421
|
-
Development scratchpad - not published, excluded from `tsconfig.build.json`. Run with `bun run dev` in watch mode. Use it to manually test and explore library code during development.
|
|
422
|
-
|
|
423
412
|
# DevOps
|
|
424
413
|
|
|
425
414
|
```bash
|
|
426
|
-
|
|
427
|
-
bun run clean
|
|
428
|
-
|
|
429
|
-
# remove dist/ only
|
|
430
|
-
bun run clean:dist
|
|
431
|
-
|
|
432
|
-
# remove tsconfig.tsbuildinfo and tsconfig.build.tsbuildinfo only
|
|
433
|
-
bun run clean:tsbuildinfo
|
|
415
|
+
bun install
|
|
434
416
|
|
|
435
|
-
|
|
417
|
+
bun run clean
|
|
436
418
|
bun run build
|
|
419
|
+
bun run tests
|
|
420
|
+
|
|
421
|
+
bun run dev
|
|
437
422
|
|
|
438
|
-
#
|
|
439
|
-
bun run dist/cli.bundle.js -- example
|
|
423
|
+
# see publish section for publish instructions
|
|
440
424
|
```
|
|
441
425
|
|
|
442
426
|
## Change Management
|
|
@@ -446,7 +430,7 @@ bun run dist/cli.bundle.js -- example
|
|
|
446
430
|
3. Bump the version in [`package.json`](package.json).
|
|
447
431
|
4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
|
|
448
432
|
5. Pull request the branch.
|
|
449
|
-
6.
|
|
433
|
+
6. Ensure package artifacts are current.
|
|
450
434
|
7. Publish.
|
|
451
435
|
|
|
452
436
|
## Publish
|
package/buildinfo.txt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.7.1+488a0be
|
package/dist/cli.bundle.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import{cpSync as s,readFileSync as f,renameSync as u,writeFileSync as P}from"fs";import{resolve as t}from"path";import{resolve as o}from"path";import{fileURLToPath as h}from"url";var d=new URL("../",import.meta.url),n=o(h(d)),m=o(n,"template/"),p=o(n,"CHANGELOG.md"),g=o(n,"buildinfo.txt"),l=o(n,"README.md");try{let r=process.argv[2];if(!r)throw Error(
|
|
2
|
+
import{cpSync as s,readFileSync as f,renameSync as u,writeFileSync as P}from"fs";import{resolve as t}from"path";import{resolve as o}from"path";import{fileURLToPath as h}from"url";var d=new URL("../",import.meta.url),n=o(h(d)),m=o(n,"template/"),p=o(n,"CHANGELOG.md"),g=o(n,"buildinfo.txt"),l=o(n,"README.md");try{let r=process.argv[2];if(!r)throw Error('First argument must be the package name (e.g. "my-package" or "@my-scope/my-package").');let a=r.replace(/\\/g,"/"),e=t(process.cwd(),a);s(m,e,{recursive:!0}),s(p,t(e,"CHANGELOG-template.md")),s(g,t(e,"buildinfo-template.txt")),s(l,t(e,"README-template.md"));let c=t(e,"package.json"),i=JSON.parse(f(c,"utf-8"));i.name=a,P(c,JSON.stringify(i,null,2)),u(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${a}'.`)}catch(r){let a=r instanceof Error?r:Error(String(r));console.error("Error:",a.message),process.exit(1)}
|
|
3
3
|
|
|
4
|
-
//# debugId=
|
|
4
|
+
//# debugId=C4A0E6EEF1219B4364756E2164756E21
|
package/dist/cli.bundle.js.map
CHANGED
|
@@ -2,10 +2,10 @@
|
|
|
2
2
|
"version": 3,
|
|
3
3
|
"sources": ["..\\src\\cli.ts", "..\\src\\constants.ts"],
|
|
4
4
|
"sourcesContent": [
|
|
5
|
-
"#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve } from 'path';\r\nimport {\r\n templatePath,\r\n changelogPath,\r\n buildinfoPath,\r\n readmePath\r\n} from './constants.js';\r\n\r\n\r\ntry {\r\n\r\n const packageNameArgument = process.argv[2];\r\n if (!packageNameArgument)
|
|
5
|
+
"#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve } from 'path';\r\nimport {\r\n templatePath,\r\n changelogPath,\r\n buildinfoPath,\r\n readmePath\r\n} from './constants.js';\r\n\r\n\r\ntry {\r\n\r\n const packageNameArgument = process.argv[2];\r\n if (!packageNameArgument)\r\n throw new Error('First argument must be the package name (e.g. \"my-package\" or \"@my-scope/my-package\").');\r\n const packageName = packageNameArgument.replace(/\\\\/g, '/');\r\n\r\n const destinationPath = resolve(process.cwd(), packageName);\r\n\r\n cpSync(templatePath, destinationPath, { recursive: true });\r\n cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n cpSync(readmePath, resolve(destinationPath, 'README-template.md'));\r\n\r\n const packageJsonPath = resolve(destinationPath, 'package.json');\r\n const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));\r\n packageJson.name = packageName;\r\n writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));\r\n\r\n renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));\r\n\r\n console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);\r\n\r\n}\r\ncatch (error) {\r\n const err = error instanceof Error ? error : new Error(String(error));\r\n console.error('Error:', err.message);\r\n process.exit(1);\r\n}\r\n",
|
|
6
6
|
"import { resolve } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nexport const packageUrl: URL = new URL('../', import.meta.url);\r\nexport const packagePath: string = resolve(fileURLToPath(packageUrl));\r\n\r\nexport const templatePath: string = resolve(packagePath, 'template/');\r\n\r\nexport const changelogPath: string = resolve(packagePath, 'CHANGELOG.md');\r\nexport const buildinfoPath: string = resolve(packagePath, 'buildinfo.txt');\r\nexport const readmePath: string = resolve(packagePath, 'README.md');\r\n"
|
|
7
7
|
],
|
|
8
|
-
"mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,aCHT,kBAAS,aACT,wBAAS,YAGF,IAAM,EAAkB,IAAI,IAAI,MAAO,YAAY,GAAG,EAChD,EAAsB,EAAQ,EAAc,CAAU,CAAC,EAEvD,EAAuB,EAAQ,EAAa,WAAW,EAEvD,EAAwB,EAAQ,EAAa,cAAc,EAC3D,EAAwB,EAAQ,EAAa,eAAe,EAC5D,EAAqB,EAAQ,EAAa,WAAW,EDClE,GAAI,CAEA,IAAM,EAAsB,QAAQ,KAAK,GACzC,GAAI,CAAC,
|
|
9
|
-
"debugId": "
|
|
8
|
+
"mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,aCHT,kBAAS,aACT,wBAAS,YAGF,IAAM,EAAkB,IAAI,IAAI,MAAO,YAAY,GAAG,EAChD,EAAsB,EAAQ,EAAc,CAAU,CAAC,EAEvD,EAAuB,EAAQ,EAAa,WAAW,EAEvD,EAAwB,EAAQ,EAAa,cAAc,EAC3D,EAAwB,EAAQ,EAAa,eAAe,EAC5D,EAAqB,EAAQ,EAAa,WAAW,EDClE,GAAI,CAEA,IAAM,EAAsB,QAAQ,KAAK,GACzC,GAAI,CAAC,EACD,MAAU,MAAM,wFAAwF,EAC5G,IAAM,EAAc,EAAoB,QAAQ,MAAO,GAAG,EAEpD,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAW,EAE1D,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAe,EAAQ,EAAiB,uBAAuB,CAAC,EACvE,EAAO,EAAe,EAAQ,EAAiB,wBAAwB,CAAC,EACxE,EAAO,EAAY,EAAQ,EAAiB,oBAAoB,CAAC,EAEjE,IAAM,EAAkB,EAAQ,EAAiB,cAAc,EACzD,EAAc,KAAK,MAAM,EAAa,EAAiB,OAAO,CAAC,EACrE,EAAY,KAAO,EACnB,EAAc,EAAiB,KAAK,UAAU,EAAa,KAAM,CAAC,CAAC,EAEnE,EAAW,EAAQ,EAAiB,WAAW,EAAG,EAAQ,EAAiB,YAAY,CAAC,EAExF,QAAQ,IAAI,mDAAmD,yBAAuC,KAAe,EAGzH,MAAO,EAAO,CACV,IAAM,EAAM,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EACpE,QAAQ,MAAM,SAAU,EAAI,OAAO,EACnC,QAAQ,KAAK,CAAC",
|
|
9
|
+
"debugId": "C4A0E6EEF1219B4364756E2164756E21",
|
|
10
10
|
"names": []
|
|
11
11
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@temir.ra/create-ts-lib",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Typescript library template",
|
|
5
5
|
"author": "temir.ra",
|
|
6
6
|
"license": "MIT",
|
|
@@ -14,12 +14,16 @@
|
|
|
14
14
|
"type": "git",
|
|
15
15
|
"url": "https://git.chimps.quest/trs/create-ts-lib.git"
|
|
16
16
|
},
|
|
17
|
+
"private": false,
|
|
17
18
|
"type": "module",
|
|
18
19
|
"imports": {
|
|
19
20
|
"#src/*.js": "./src/*.ts"
|
|
20
21
|
},
|
|
21
22
|
"bin": "./dist/cli.bundle.js",
|
|
22
23
|
"files": [
|
|
24
|
+
"scripts/buildinfo.ts",
|
|
25
|
+
"scripts/build-bundle.ts",
|
|
26
|
+
"scripts/cdn-rewrite-map.json",
|
|
23
27
|
"dist",
|
|
24
28
|
"CHANGELOG.md",
|
|
25
29
|
"buildinfo.txt",
|
|
@@ -27,14 +31,15 @@
|
|
|
27
31
|
],
|
|
28
32
|
"scripts": {
|
|
29
33
|
"clean:dist": "rm -rf dist/",
|
|
30
|
-
"clean:tsbuildinfo": "rm -f
|
|
34
|
+
"clean:tsbuildinfo": "rm -f *.tsbuildinfo || true",
|
|
31
35
|
"clean": "bun run clean:dist && bun run clean:tsbuildinfo",
|
|
32
|
-
"
|
|
36
|
+
"buildinfo": "bun run scripts/buildinfo.ts",
|
|
33
37
|
"tests": "bun test",
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
"
|
|
37
|
-
"
|
|
38
|
+
"typecheck": "tsc --noEmit",
|
|
39
|
+
"reinstall": "rm -rf node_modules && rm -f bun.lock && bun pm cache rm && bun install && bunx tsc --version",
|
|
40
|
+
"prebuild": "bun run buildinfo",
|
|
41
|
+
"build": "bun run build:cli-bundle",
|
|
42
|
+
"build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
|
|
38
43
|
},
|
|
39
44
|
"devDependencies": {
|
|
40
45
|
"@types/bun": "latest",
|