@temir.ra/create-ts-lib 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Version 0
 
+## 0.8.0
+
+1. Updated wording in the Publish section of the generated README.
+2. `build:tsc` step is now generated per default.
+3. Added `./constants` entrypoint to `package.json`.
+
+## 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.

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,14 +141,14 @@ 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",
-
-    // compiles the library to declaration files and ESM JavaScript in dist/
-    "build:tsc": "tsc --project tsconfig.build.json",
+    "build": "bun run build:bundle && bun run build:tsc && bun run build:cli-bundle",
 
     // bundles the library into ESM and IIFE formats for distribution
     "build:bundle": "bun run scripts/build-bundle.ts",
 
+    // compiles the library to declaration files and ESM JavaScript in dist/
+    "build:tsc": "tsc --project tsconfig.build.json",
+
     // bundles the CLI into a single file for distribution; requires the "bin" field to be set to the bundled output
     "build:cli-bundle": "bun build src/cli.ts --entry-naming \"[dir]/[name].bundle.[ext]\" --outdir dist --target node --format esm --minify --sourcemap=external"
 
@@ -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`.
-
-## TSC Compilation
-
-Not generated by default. Enables file-for-file tsc compilation of `src/` to ESM JavaScript and declaration files alongside bundling.
-
-### `tsconfig.build.json`
+## `tsconfig.build.json`
 
-Extends `tsconfig.json`, narrowing scope to `src/` only and switching to `nodenext` module resolution for strict ESM compliance.
+`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.
 
-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`.
+Exports condition `import` may point to the compiled output instead of the bundled output `./dist/index.bundle.js` if `"emitDeclarationOnly": false`:
 
-### CDN Map `scripts/cdn-rewrite-map.json`
-
-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",
+      // ... ,
+    }
+  },
+  // ... ,
 }
 ```
 
@@ -335,7 +295,7 @@ https://your-own-cdn.com/<LIB_NAME>/index.js
 
 ### Bundled - absorbed into the consumer's output
 
-The consumer's bundler absorbs the library into their own output. Module identity is destroyed - `import.meta.url` now points to the consumer's bundle, not the library's. However, **the path relationship can be preserved by convention**: if the consumer copies the library's assets into their build output at the same relative path the library expects, `import.meta.url` resolution continues to work correctly.
+The consumer's bundler absorbs the library into their own output. Module identity is destroyed - `import.meta.url` now points to the consumer's bundle, not the library's. However, **the path relationship can be preserved by convention**: if the consumer copies the library's assets into their output directory at the same relative path the library expects, `import.meta.url` resolution continues to work correctly.
 
 ### Contract
 
@@ -352,7 +312,7 @@ If the library has runtime assets, the following contract applies:
     1. **Copy the assets** - see [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer) below.
     2. **Ensure the assets are served**
         - if the consumer is a web server, ensure the copied assets are served as static files
-        - if the consumer is a bundler, ensure the copied assets are included in the bundle output
+        - if the consumer is a bundler, ensure the copied assets are included in the output directory
 
 #### Scoped assets directory convention
 
@@ -365,34 +325,55 @@ assets/
         └── ...
 ```
 
-This also prevents naming collisions when multiple libraries are bundled into the same consumer app. Each library's assets live under their own namespace; no library can shadow another's files.
-
 Add `assets/` to the `files` field in `package.json` so that the assets are included in the published package:
 
 ```json
+{
+  // ... ,
   "files": [
-    "dist",
-    "CHANGELOG.md",
-    "buildinfo.txt",
-    "assets"
+    // ... ,
+    "assets/"
   ],
+  // ... ,
+}
 ```
 
 #### Accessing assets
 
-Construct asset URLs directly from `import.meta.url`.
+Construct asset URLs directly from `import.meta.url`:
 
 ```typescript
 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());
+// for `--target browser` and `--target node` (isomorphic)
+const assetUrl = new URL('<ASSET>', assetsUrl);
+const asset = await fetch(assetUrl).then(response => response.body);
 
-// for --target node
+// for `--target node` only
 import { readFile } from 'fs/promises';
 import { fileURLToPath } from 'url';
-const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsUrl)), 'utf-8'));
+const assetUrl = new URL('<ASSET>', assetsUrl);
+const assetPath = fileURLToPath(assetUrl);
+const asset = await readFile(assetPath);
+```
+
+The generated `./src/constants.ts` scaffolds the isomorphic approach and `./constants` is configured as an additional entry point in `package.json` for direct imports:
+
+```json
+{
+  // ... ,
+  "exports": {
+    // ... ,
+    "./constants": {
+      "entrypoint": "./src/constants.ts",
+      "types": "./dist/constants.d.ts",
+      "browser": "./dist/constants.bundle.js",
+      "import": "./dist/constants.bundle.js"
+    }
+  },
+  // ... ,
+}
 ```
 
 #### README statement for library consumers
@@ -400,7 +381,7 @@ const asset = JSON.parse(await readFile(fileURLToPath(new URL('<ASSET>', assetsU
 ```markdown
 ## Asset resolution
 
-This library resolves assets at runtime using `import.meta.url`. If you bundle this library into your application, copy `node_modules/<@SCOPE>/<LIB_NAME>/assets/<@SCOPE>/<LIB_NAME>/` into your build output directory alongside your bundle.
+This library resolves assets at runtime using `import.meta.url`. If you include this library into your bundle, copy `node_modules/<@SCOPE>/<LIB_NAME>/assets/<@SCOPE>/<LIB_NAME>/` to your output directory as `assets/<@SCOPE>/<LIB_NAME>/`.
 ```
 
 #### When the library is bundled by the consumer
@@ -418,9 +399,34 @@ 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

package/buildinfo.txt

@@ -1 +1 @@
-0.7.5+df15511
+0.8.0+545e022

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "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
@@ -66,6 +67,8 @@ bun publish --registry https://registry.npmjs.org/ --access public
 
 ### Custom registry
 
+Publish to a custom registry.
+
 ```bash
 # placeholder:
   # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>

package/template/package.json

@@ -19,7 +19,13 @@
       "entrypoint": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.bundle.js",
-      "import": "./dist/index.js"
+      "import": "./dist/index.bundle.js"
+    },
+    "./constants": {
+      "entrypoint": "./src/constants.ts",
+      "types": "./dist/constants.d.ts",
+      "browser": "./dist/constants.bundle.js",
+      "import": "./dist/constants.bundle.js"
     }
   },
   "imports": {
@@ -42,11 +48,12 @@
     "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
     "tests": "bun test",
     "prebuild": "bun run buildinfo",
-    "build": "bun run build:bundle",
-    "build:bundle": "bun run scripts/build-bundle.ts"
+    "build": "bun run build:bundle && bun run build:tsc",
+    "build:bundle": "bun run scripts/build-bundle.ts",
+    "build:tsc": "tsc --project tsconfig.build.json"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

package/template/src/constants.ts

@@ -0,0 +1,3 @@
+export const packageUrl: URL = new URL('../', import.meta.url);
+export const buildinfoUrl: URL = new URL('buildinfo.txt', packageUrl);
+export const distUrl: URL = new URL('dist/', packageUrl);

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.build.json

@@ -0,0 +1,21 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist/"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules/",
+    "dist/",
+    "tests/",
+    "scripts/"
+  ]
+}

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/"
   ]
 }