@temir.ra/create-ts-lib 0.7.4 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Version 0
 
+## 0.7.6
+
+1. Updated `typescript` to `6.0.3`.
+2. Cleaned up minor `README.md` inconsistencies.
+3. Aligned wording with [`RFC 2119`](https://datatracker.ietf.org/doc/html/rfc2119).
+4. Updated files from `template` template.
+
+## 0.7.5
+
+1. Updated files from `@temir.ra/template@0.1.6` template.
+
 ## 0.7.4
 
 1. Updated `keywords` in `template/package.json`.

package/README.md

@@ -7,14 +7,10 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
 1. [Quick Start](#quick-start)
 2. [Documentation](#documentation)
     1. [`package.json`](#packagejson)
-    2. [`"bin"` field in `package.json`](#bin-field-in-packagejson)
-    3. [`tsconfig.json`](#tsconfigjson)
-    4. [TSC Compilation](#tsc-compilation)
-        1. [`tsconfig.build.json`](#tsconfigbuildjson)
-        2. [`package.json`](#packagejson-1)
-    5. [Script `scripts/build-bundle.ts`](#script-scriptsbuild-bundlets)
+    2. [Script `scripts/build-bundle.ts`](#script-scriptsbuild-bundlets)
         1. [CDN Map `scripts/cdn-rewrite-map.json`](#cdn-map-scriptscdn-rewrite-mapjson)
-    6. [Asset Resolution](#asset-resolution)
+    3. [`tsconfig.build.json`](#tsconfigbuildjson)
+    4. [Asset Resolution](#asset-resolution)
         1. [Externalized - loaded from CDN or `node_modules/`](#externalized---loaded-from-cdn-or-node_modules)
         2. [Bundled - absorbed into the consumer's output](#bundled---absorbed-into-the-consumers-output)
         3. [Contract](#contract)
@@ -22,6 +18,7 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
             2. [Accessing assets](#accessing-assets)
             3. [README statement for library consumers](#readme-statement-for-library-consumers)
             4. [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer)
+    5. [`"bin"` field in `package.json`](#bin-field-in-packagejson)
 3. [DevOps](#devops)
     1. [Change Management](#change-management)
     2. [Publish](#publish)
@@ -85,6 +82,7 @@ The generated package is pre-configured with `build:bundle` only. See [TSC Compi
   "type": "module",
 
   // package entry points
+  // multiple entry points can be configured (".", "./module/", etc.)
   // 
   // scripts/build-bundle.ts (non-standard) export condition:
   // "entrypoint" - locates the source entry point for bundling
@@ -92,13 +90,13 @@ The generated package is pre-configured with `build:bundle` only. See [TSC Compi
   // standard export conditions:
   // "types"      - TypeScript consumers; resolves to the declaration files;
   // "browser"    - browser bundler consumers; resolves to the bundled output
-  // "import"     - ESM consumers; resolves to the compiled module output
+  // "import"     - ESM consumers; resolves to the bundled/compiled output
   "exports": {
     ".": {
       "entrypoint": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.bundle.js",
-      "import": "./dist/index.js"
+      "import": "./dist/index.bundle.js"
     }
   },
 
@@ -143,7 +141,7 @@ The generated package is pre-configured with `build:bundle` only. See [TSC Compi
     "prebuild": "bun run buildinfo",
 
     // convenience script to run the build steps in sequence
-    "build": "bun run build:tsc && bun run build:bundle && bun run build:cli-bundle",
+    "build": "bun run build:bundle && bun run build:tsc && bun run build:cli-bundle",
 
     // compiles the library to declaration files and ESM JavaScript in dist/
     "build:tsc": "tsc --project tsconfig.build.json",
@@ -161,89 +159,29 @@ The generated package is pre-configured with `build:bundle` only. See [TSC Compi
 
 It is highly recommended to include `tests/` in the `files` field. Note, that `tests/` is not included by default in the generated `package.json`.
 
-## `"bin"` field in `package.json`
-
-For CLI packages, add the following to `package.json`:
-
-```json
-{
-  // ... ,
-  "bin": "./dist/cli.bundle.js",
-  "scripts": {
-    // ... ,
-    "build": "... && bun run build:cli-bundle",
-    // ... ,
-    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
-  }
-}
-```
-
-`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.
-
-```typescript
-#!/usr/bin/env node
-```
+## Script `scripts/build-bundle.ts`
 
-If the package exports a CLI only and is not intended to be imported in other packages, the `exports` field can be omitted.
+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.
 
-## `tsconfig.json`
+Import specifiers can be rewritten to CDN URLs via `scripts/cdn-rewrite-map.json`.
 
-Selected fields are documented in the [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-workspace#tsconfigjson).
+### CDN Map `scripts/cdn-rewrite-map.json`
 
-See the TypeScript documentation on [tsconfig.json](https://www.typescriptlang.org/tsconfig) for detailed explanations of all options.
+Maps import specifiers to CDN URLs. During bundling, matching specifiers in source files are rewritten to their CDN equivalents.
 
-The following lists the additions and overrides relative to [`create-workspace`](https://www.npmjs.com/package/@temir.ra/create-workspace#tsconfigjson).
+`<VERSION>` in a URL is replaced with the version of the matching package from `package.json`.
 
 ```json
 {
-
-  "compilerOptions": {
-
-    // ... ,
-
-    // emit .d.ts declaration files
-    "declaration": true,
-
-    // emit .d.ts.map files mapping declarations back to source
-    "declarationMap": true,
-
-    // emit only .d.ts files, no JavaScript; overridden in tsconfig.build.json
-    "emitDeclarationOnly": true,
-
-    // output directory for emitted files
-    "outDir": "./dist"
-
-  },
-
-  "include": [
-    // ... ,
-    // include `scripts/**/*.json` for script configuration files
-    "scripts/**/*.json",
-    // include `src/**/*.ts` for source files
-    "src/**/*.ts"
-  ],
-  "exclude": [
-    // ... ,
-    // exclude `dist/`
-    "dist"
-  ]
-
+  "import-specifier": "https://cdn.jsdelivr.net/npm/package-name@<VERSION>/dist/index.bundle.js"
 }
 ```
 
-`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`.
+## `tsconfig.build.json`
 
-## TSC Compilation
+`tsconfig.json` provided by [`workspace` template](https://www.npmjs.com/package/@temir.ra/create-workspace) is intended for development only. `tsconfig.build.json` extends it with settings for compiling the source files for distribution.
 
-Not generated by default. Enables file-for-file tsc compilation of `src/` to ESM JavaScript and declaration files alongside bundling.
-
-### `tsconfig.build.json`
-
-Extends `tsconfig.json`, narrowing scope to `src/` only and switching to `nodenext` module resolution for strict ESM compliance.
-
-Enables JavaScript output alongside declaration files for distribution.
-
-Development files (`dev.ts`, `tests/`, `scripts/`) are excluded.
+See [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-workspace#tsconfigjson) and [tsconfig.json](https://www.typescriptlang.org/tsconfig) for detailed explanations of all options.
 
 ```json
 {
@@ -253,14 +191,23 @@ Development files (`dev.ts`, `tests/`, `scripts/`) are excluded.
   "compilerOptions": {
 
     // narrows root to src/ for distribution output
-    "rootDir": "./src",
+    "rootDir": "./src/",
 
     // nodenext enforces strict ESM compliance; imports must use explicit .js file extensions
     "module": "nodenext",
     "moduleResolution": "nodenext",
 
-    // emit both JavaScript files and declaration files for distribution
-    "emitDeclarationOnly": false,
+    // emit .d.ts declaration files
+    "declaration": true,
+
+    // emit .d.ts.map files mapping declarations back to source
+    "declarationMap": true,
+
+    // emit only .d.ts files, no JavaScript
+    "emitDeclarationOnly": true,
+
+    // output directory for emitted files
+    "outDir": "./dist/"
 
   },
 
@@ -270,10 +217,10 @@ Development files (`dev.ts`, `tests/`, `scripts/`) are excluded.
   ],
   // exclude development files and directories from distribution
   "exclude": [
-    "node_modules",
-    "dist",
-    "tests",
-    "scripts"
+    "node_modules/",
+    "dist/",
+    "tests/",
+    "scripts/"
   ]
 
 }
@@ -286,27 +233,40 @@ Development files (`dev.ts`, `tests/`, `scripts/`) are excluded.
   // ... ,
   "scripts": {
     // ... ,
-    "build": "bun run build:tsc && bun run build:bundle",
+    "build": "... && bun run build:tsc",
     "build:tsc": "tsc --project tsconfig.build.json"
   }
 }
 ```
 
-## Script `scripts/build-bundle.ts`
-
-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.
-
-Import specifiers can be rewritten to CDN URLs via `scripts/cdn-rewrite-map.json`.
-
-### CDN Map `scripts/cdn-rewrite-map.json`
+Exports condition `import` may point to the compiled output instead of the bundled output `./dist/index.bundle.js`:
 
-Maps import specifiers to CDN URLs. During bundling, matching specifiers in source files are rewritten to their CDN equivalents.
+```json
+{
+  // ... ,
+  "exports": {
+    ".": {
+      // ... ,
+      "import": "./dist/index.js"
+    }
+  },
+  // ... ,
+}
+```
 
-`<VERSION>` in a URL is replaced with the version of the matching package from `package.json`.
+When `"declaration": true`, then exports condition `types` can be added to point to the declaration files:
 
 ```json
 {
-  "import-specifier": "https://cdn.jsdelivr.net/npm/package-name@<VERSION>/dist/index.bundle.js"
+  // ... ,
+  "exports": {
+    ".": {
+      // ... ,
+      "types": "./dist/index.d.ts",
+      // ... ,
+    }
+  },
+  // ... ,
 }
 ```
 
@@ -386,6 +346,7 @@ Construct asset URLs directly from `import.meta.url`.
 const packageUrl = new URL('../', import.meta.url);
 const assetsUrl  = new URL('assets/<@SCOPE>/<LIB_NAME>/', packageUrl);
 
+
 // for --target browser
 const asset = await fetch(new URL('<ASSET>', assetsUrl)).then(r => r.json());
 
@@ -418,17 +379,40 @@ consumer output/
 
 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.
 
+## `"bin"` field in `package.json`
+
+For CLI packages, add the following to `package.json`:
+
+```json
+{
+  // ... ,
+  "bin": "./dist/cli.bundle.js",
+  "scripts": {
+    // ... ,
+    "build": "... && bun run build:cli-bundle",
+    "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
+  }
+}
+```
+
+`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.
+
+```typescript
+#!/usr/bin/env node
+```
+
+If the package exports a CLI only and is not intended to be imported in other packages, the `exports` field can be omitted.
+
 # DevOps
 
 ```bash
+bun update
 bun install
 
 bun run clean
 bun run build
 bun run tests
 
-bun run --watch scripts/dev.ts
-
 # see publish section for publish instructions
 ```
 

package/buildinfo.txt

@@ -1 +1 @@
-0.7.4+443a662
+0.7.6+b2fa591

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "A template for a distributable TypeScript library package.",
   "author": "temir.ra",
   "license": "MIT",
@@ -43,6 +43,6 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

package/template/README.md

@@ -23,6 +23,7 @@
 # DevOps
 
 ```bash
+bun update
 bun install
 
 bun run clean

package/template/package.json

@@ -17,9 +17,8 @@
   "exports": {
     ".": {
       "entrypoint": "./src/index.ts",
-      "types": "./dist/index.d.ts",
       "browser": "./dist/index.bundle.js",
-      "import": "./dist/index.js"
+      "import": "./dist/index.bundle.js"
     }
   },
   "imports": {
@@ -47,6 +46,6 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

package/template/tests/buildinfo.test.ts

@@ -16,7 +16,7 @@ function readBuildinfo(): string {
 
 describe('buildInfo', () => {
 
-    it('should be a valid semver string', () => {
+    it('MUST be a valid semver string', () => {
         expect(readBuildinfo()).toMatch(SEMVER_REGEX);
     });
 

package/template/tsconfig.json

@@ -19,11 +19,7 @@
       "bun"
     ],
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true,
-    "emitDeclarationOnly": true,
-    "outDir": "./dist"
+    "resolveJsonModule": true
   },
   "include": [
     "scripts/**/*.ts",
@@ -32,7 +28,7 @@
     "tests/**/*.ts"
   ],
   "exclude": [
-    "node_modules",
-    "dist"
+    "node_modules/",
+    "dist/"
   ]
 }