@temir.ra/create-template 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Version 0
 
+## 0.1.10
+
+1. Synced with `ts-lib` template.
+
 ## 0.1.9
 
 1. Fixed template assets paths.

package/buildinfo.txt

@@ -1 +1 @@
-0.1.9+edda801
+0.1.10+55bf9cf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-template",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "A template for a template package.",
   "author": "temir.ra",
   "license": "MIT",

package/scripts/build-bundle.ts

@@ -28,16 +28,14 @@ function getManifest(packageIdentifier?: string): PackageManifest {
 
     const manifestPath = packageIdentifier
         ? join('node_modules', packageIdentifier, 'package.json')
-        : 'package.json';
+        : 'package.json'
+        ;
 
     let manifest: PackageManifest;
     try {
         manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     } catch {
-        if (packageIdentifier)
-            throw new Error(`[scripts/build-bundle.ts] Could not read manifest for '${packageIdentifier}' at '${manifestPath}'.`);
-        else
-            throw new Error(`[scripts/build-bundle.ts] Could not read package manifest at '${manifestPath}'.`);
+        throw new Error(`[scripts/build-bundle.ts] Failed to read package manifest at '${manifestPath}'.`);
     }
 
     return manifest;
@@ -104,7 +102,7 @@ const cdnRewritePlugin = {
             console.log(`[cdn-rewrite] '${importSpecifier}' → '${url}'`);
         }
 
-        build.onResolve({ filter: /\*/ }, (args: any) => {
+        build.onResolve({ filter: /.*/ }, (args: any) => {
             const url = resolved.get(args.path);
             if (url) return { path: url, external: true };
         });
@@ -116,6 +114,8 @@ const cdnRewritePlugin = {
 const entrypoints = getManifestEntrypoints(getManifest());
 console.log('[scripts/build-bundle.ts] Entrypoints:', entrypoints);
 
+const omitIife = process.argv.includes('--omit-iife');
+
 let buildResult;
 
 console.log('[scripts/build-bundle.ts] Starting ESM bundle build...');
@@ -139,23 +139,25 @@ if (!buildResult.success) {
 }
 console.log('[scripts/build-bundle.ts] ESM bundle build completed successfully.');
 
-console.log('[scripts/build-bundle.ts] Starting IIFE bundle build...');
-buildResult = await Bun.build({
-    entrypoints,
-    outdir: 'dist',
-    naming: '[dir]/[name].iife.[ext]',
-    target: 'browser',
-    format: 'iife',
-    minify: true,
-    sourcemap: 'external',
-    plugins: [cdnRewritePlugin],
-});
-
-if (!buildResult.success) {
-    console.error('[scripts/build-bundle.ts] Build failed:');
-    for (const message of buildResult.logs) {
-        console.error(message);
+if (!omitIife) {
+    console.log('[scripts/build-bundle.ts] Starting IIFE bundle build...');
+    buildResult = await Bun.build({
+        entrypoints,
+        outdir: 'dist',
+        naming: '[dir]/[name].iife.[ext]',
+        target: 'browser',
+        format: 'iife',
+        minify: true,
+        sourcemap: 'external',
+        plugins: [cdnRewritePlugin],
+    });
+
+    if (!buildResult.success) {
+        console.error('[scripts/build-bundle.ts] Build failed:');
+        for (const message of buildResult.logs) {
+            console.error(message);
+        }
+        process.exit(1);
     }
-    process.exit(1);
+    console.log('[scripts/build-bundle.ts] IIFE bundle build completed successfully.');
 }
-console.log('[scripts/build-bundle.ts] IIFE bundle build completed successfully.');

package/template/scripts/build-bundle.ts

@@ -28,16 +28,14 @@ function getManifest(packageIdentifier?: string): PackageManifest {
 
     const manifestPath = packageIdentifier
         ? join('node_modules', packageIdentifier, 'package.json')
-        : 'package.json';
+        : 'package.json'
+        ;
 
     let manifest: PackageManifest;
     try {
         manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
     } catch {
-        if (packageIdentifier)
-            throw new Error(`[scripts/build-bundle.ts] Could not read manifest for '${packageIdentifier}' at '${manifestPath}'.`);
-        else
-            throw new Error(`[scripts/build-bundle.ts] Could not read package manifest at '${manifestPath}'.`);
+        throw new Error(`[scripts/build-bundle.ts] Failed to read package manifest at '${manifestPath}'.`);
     }
 
     return manifest;
@@ -104,7 +102,7 @@ const cdnRewritePlugin = {
             console.log(`[cdn-rewrite] '${importSpecifier}' → '${url}'`);
         }
 
-        build.onResolve({ filter: /\*/ }, (args: any) => {
+        build.onResolve({ filter: /.*/ }, (args: any) => {
             const url = resolved.get(args.path);
             if (url) return { path: url, external: true };
         });
@@ -116,6 +114,8 @@ const cdnRewritePlugin = {
 const entrypoints = getManifestEntrypoints(getManifest());
 console.log('[scripts/build-bundle.ts] Entrypoints:', entrypoints);
 
+const omitIife = process.argv.includes('--omit-iife');
+
 let buildResult;
 
 console.log('[scripts/build-bundle.ts] Starting ESM bundle build...');
@@ -139,23 +139,25 @@ if (!buildResult.success) {
 }
 console.log('[scripts/build-bundle.ts] ESM bundle build completed successfully.');
 
-console.log('[scripts/build-bundle.ts] Starting IIFE bundle build...');
-buildResult = await Bun.build({
-    entrypoints,
-    outdir: 'dist',
-    naming: '[dir]/[name].iife.[ext]',
-    target: 'browser',
-    format: 'iife',
-    minify: true,
-    sourcemap: 'external',
-    plugins: [cdnRewritePlugin],
-});
-
-if (!buildResult.success) {
-    console.error('[scripts/build-bundle.ts] Build failed:');
-    for (const message of buildResult.logs) {
-        console.error(message);
+if (!omitIife) {
+    console.log('[scripts/build-bundle.ts] Starting IIFE bundle build...');
+    buildResult = await Bun.build({
+        entrypoints,
+        outdir: 'dist',
+        naming: '[dir]/[name].iife.[ext]',
+        target: 'browser',
+        format: 'iife',
+        minify: true,
+        sourcemap: 'external',
+        plugins: [cdnRewritePlugin],
+    });
+
+    if (!buildResult.success) {
+        console.error('[scripts/build-bundle.ts] Build failed:');
+        for (const message of buildResult.logs) {
+            console.error(message);
+        }
+        process.exit(1);
     }
-    process.exit(1);
+    console.log('[scripts/build-bundle.ts] IIFE bundle build completed successfully.');
 }
-console.log('[scripts/build-bundle.ts] IIFE bundle build completed successfully.');

package/template/tests/buildinfo.test.ts

@@ -14,9 +14,9 @@ function readBuildinfo(): string {
     return readFileSync(fileURLToPath(buildinfoUrl), 'utf-8').trim();
 }
 
-describe('buildInfo', () => {
+describe('buildinfo.txt', () => {
 
-    it('MUST be a valid semver string', () => {
+    it('MUST contain a valid semver string', () => {
         expect(readBuildinfo()).toMatch(SEMVER_REGEX);
     });
 

package/template/CHANGELOG-template.md

@@ -1,157 +0,0 @@
-# Version 0
-
-## 0.8.1
-
-1. Added `DOM` to the `lib` array in the generated `tsconfig.json`.
-
-## 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.
-
-## 0.7.4
-
-1. Updated `keywords` in `template/package.json`.
-2. Restored docs for `build*` and `tests` `package.json` scripts in `README.md`.
-3. Reduced `scripts/dev.ts` section to a DevOps command.
-4. Added clarification on the `files` field recommendation for `tests/` in the README.
-5. Updated from `@temir.ra/template@0.1.5` template.
-
-## 0.7.3
-
-1. Updated from `@temir.ra/template@0.1.4` template.
-
-## 0.7.2
-
-1. Cleaned up `*-template.*` files from the template directory.
-
-## 0.7.1
-
-1. Updated `template/` files from `@temir.ra/workspace@0.4.1` template.
-
-## 0.7.0
-
-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.
-2. Removed `CLAUDE.md`, `AGENTS.md`, and `src/dev.ts` from root and template.
-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`.
-4. Updated the generated `tsconfig.json`: changed `target` to `ESNext`; removed `DOM` from `lib`; added `types: ["bun"]`.
-5. Removed generated `tsconfig.build.json`; TSC compilation is now opt-in and documented in `README.md`.
-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.
-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`.
-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.
-9. Refactored `template/tests/buildinfo.test.ts` to use a proper semver regex.
-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.
-11. Updated from `@temir.ra/template@0.1.3` template.
-
-## 0.6.3
-
-1. Cleaned up dormant package scripts.
-2. Cleaned up minor `README.md` inconsistencies.
-
-## 0.6.2
-
-1. Updated `clean:tsbuildinfo` script to remove both `tsconfig.tsbuildinfo` and `tsconfig.build.tsbuildinfo`.
-
-## 0.6.1
-
-1. Cleaned up dormant imports.
-2. Cleaned up / updated minor `README.md` inconsistencies.
-3. Updated placeholders in `README.md` in the **Asset resolution** section.
-4. Removed **Asset resolution** section from the generated `README.md`, as the operational passage is given in the template `README.md`.
-5. Removed **AI Assistant Context** section from the `README.md` files.
-7. Cleaned up **Publish** section in the `README.md`.
-
-## 0.6.0
-
-1. Updated documentation and configs to TypeScript 6.
-
-## 0.5.0
-
-1. Changed `buildinfo.txt` generation and testing to align with [https://semver.org](https://semver.org).
-
-## 0.4.1
-
-1. Fixed `destinationPath` resolution in `cli.ts` to use the full resolved path instead of just the basename.
-
-## 0.4.0
-
-1. Added support for scoped package names in the CLI argument parsing and asset resolution.
-
-## 0.3.1-pre.1 (unreleased)
-
-1. Removed `dev.ts` file.
-
-## 0.3.0
-
-1. Removed AI Assistant Context files to be generated by the user with the provided prompts in the README.
-
-## 0.2.8 (unreleased)
-
-1. CLI now copies root `README.md` into the generated project as `README-template.md`.
-2. Added `README-template.md` to `template/gitignore`.
-3. Added `# AI Assistant Context` section to root `README.md` and `template/README.md` with prompts for generating AI coding assistant context files.
-4. Revised Change Management step 6 in root `README.md` and `template/README.md`.
-5. `.gitignore`'ing `bun.lock`.
-
-## 0.2.8-pre.2
-
-1. Removed `sideEffects` property from `package.json` as it is not a standard field.
-2. Added references to npmjs and typescriptlang documentation for `package.json` and `tsconfig.json` in the README.
-
-## 0.2.7
-
-1. Changed `filter` property in `cdnRewritePlugin` in `scripts/build-lib-bundle.ts` to take import identifiers into account that do not have file extensions.
-2. Changed `buildinfo.txt` generation in `scripts/buildinfo.ts` to read the version from `package.json` instead of relying on the `npm_package_version` environment variable. Enables correct version capture in monorepo setups.
-
-## 0.2.6
-
-1. Minor ToC and typo fixes in both README.md files (root and template).
-2. Revised the Publish section in both README.md files.
-
-## 0.2.5
-
-1. Minor README updates.
-2. Fixed `buildinfo.txt` in published package.
-3. Fixed `buildinfo.test.ts` regex to accept semver prerelease identifiers.
-
-## 0.2.4
-
-1. Documented template caching in the Quick Start section with commands to pin the version or clear the cache.
-2. Minor README updates: Revised Asset Resolution sections in root and template; Added introductory paragraph to Documentation section;
-3. Moved git-upstream to `https://git.chimps.quest/trs/create-ts-lib.git`.
-
-## 0.2.3
-
-1. Updated change management workflow in `README.md` and `template/README.md`: build step now happens after merge (not before PR), so `buildinfo.txt` captures the correct git hash and artifacts are up to date before publish.
-2. Added Change Management section to root and template `CLAUDE.md`.
-
-## 0.2.2
-
-1. Fixed `CHANGELOG.md` and `buildinfo.txt` copy paths in `cli.ts`: they were resolved relative to `template/` instead of the package root, causing the copy to fail. Refactored URL/path construction to derive all paths from a single `packageUrl`, eliminating redundant `fileURLToPath` calls at each copy site.
-2. Added `buildinfo-template.txt` and `CHANGELOG-template.md` to `template/gitignore` so generated libraries do not track template files.
-3. Added `example/` to the root `.gitignore` to exclude local test scaffold output.
-4. Added a `bun run dist/cli.bundle.js -- example` snippet to the DevOps section of the README for quick local testing.
-
-## 0.2.1
-
-1. Added asset resolution documentation to root README: scoped asset folder convention, inline `import.meta.url` resolution, `fetch()` for isomorphic I/O, setup steps, checklist, and consumer README statement.
-2. Updated template README with a reference to the asset resolution docs in the create-ts-lib README.
-3. Updated both `CLAUDE.md` files.
-4. Updated both `dev.ts` files to use inline `new URL('../', import.meta.url)`.
-5. Removed `src/urls.ts` from root and template (not needed - inline resolution is sufficient).
-
-## 0.1.0
-
-1. First version of the template.

package/template/README-template.md

@@ -1,458 +0,0 @@
-# Introduction
-
-A template for TypeScript libraries distributed via npm-compatible registries. Provides TypeScript configuration, build tooling for ESM and bundled outputs, and build metadata generation.
-
-## Table of Contents
-
-1. [Quick Start](#quick-start)
-2. [Documentation](#documentation)
-    1. [`package.json`](#packagejson)
-    2. [Script `scripts/build-bundle.ts`](#script-scriptsbuild-bundlets)
-        1. [CDN Map `scripts/cdn-rewrite-map.json`](#cdn-map-scriptscdn-rewrite-mapjson)
-    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)
-            1. [Scoped assets directory convention](#scoped-assets-directory-convention)
-            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)
-
-# Quick Start
-
-```bash
-# placeholder:
-    # <TEMPLATE_PACKAGE: @temir.ra/create-ts-lib
-    # <TEMPLATE_NAME: @temir.ra/ts-lib
-    # <NEW_PACKAGE: <NEW_PACKAGE>
-      # is used as:
-      #   - the path where the package is created
-      #   - the "name" field in the generated package.json
-    # <@_VERSION: <@_VERSION>
-
-# pinned version
-bun info "@temir.ra/create-ts-lib" version
-bun create --no-install --no-git "@temir.ra/ts-lib<@_VERSION>" <NEW_PACKAGE>
-
-# latest
-# clear the cache to pick up the latest version
-bun pm cache rm
-bun create --no-install --no-git "@temir.ra/ts-lib" <NEW_PACKAGE>
-
-# templates only copy files, run install and any setup scripts manually
-cd <NEW_PACKAGE>
-bun install
-```
-
-# Documentation
-
-The following sections explain the configurations and conventions baked into the generated package. Useful when adapting it to fit specific needs.
-
-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:
-
-- **Bundling** (`scripts/build-bundle.ts`) - generated by default; bundles the library to ESM and IIFE formats.
-- **TSC compilation** (`tsconfig.build.json` + `build:tsc`) - optional, not generated by default; compiles source files one-for-one to ESM JavaScript and declaration files.
-
-Both strategies can be combined.
-
-## `package.json`
-
-Selected fields are documented in the [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-workspace#packagejson).
-
-See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
-
-The following lists the additions and overrides relative to [`create-workspace`](https://www.npmjs.com/package/@temir.ra/create-workspace#packagejson).
-
-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.
-
-```json
-{
-
-  // ... ,
-
-  // the package is anticipated to be published
-  "private": false,
-
-  // treats all .js files as ES modules; use .cjs extension for CommonJS files
-  "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
-  // 
-  // 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 bundled/compiled output
-  "exports": {
-    ".": {
-      "entrypoint": "./src/index.ts",
-      "types": "./dist/index.d.ts",
-      "browser": "./dist/index.bundle.js",
-      "import": "./dist/index.bundle.js"
-    }
-  },
-
-  // convenience alias for source-execution only - does NOT survive transpilation or bundling
-  // NOT for use in source files compiled by tsconfig.build.json
-  // the .js extension is required in import statements (nodenext compliance)
-  "imports": {
-    "#src/*.js": "./src/*.ts"
-  },
-
-  // CLI entry point
-  "bin": "./dist/cli.bundle.js",
-
-  // files to include in the published package
-  "files": [
-    "scripts/buildinfo.ts",
-    "scripts/build-bundle.ts",
-    "scripts/cdn-rewrite-map.json",
-    "CHANGELOG.md",
-    "buildinfo.txt",
-    "dist/",
-    "tests/"
-  ],
-
-  "scripts": {
-
-    // ... ,
-
-    // removes the dist/ directory generated by the build steps
-    "clean:dist": "rm -rf dist/",
-
-    // removes .tsbuildinfo files generated by TypeScript's incremental build feature
-    "clean:tsbuildinfo": "rm -f *.tsbuildinfo || true",
-
-    // convenience script to run the clean steps in sequence
-    "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
-
-    // discovers and runs test files
-    "tests": "bun test",
-
-    // executed before build; generates buildinfo.txt
-    "prebuild": "bun run buildinfo",
-
-    // convenience script to run the build steps in sequence
-    "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"
-
-  }
-
-}
-```
-
-It is highly recommended to include `tests/` in the `files` field. Note, that `tests/` is not included by default in the generated `package.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`
-
-Maps import specifiers to CDN URLs. During bundling, matching specifiers in source files are rewritten to their CDN equivalents.
-
-`<VERSION>` in a URL is replaced with the version of the matching package from `package.json`.
-
-```json
-{
-  "import-specifier": "https://cdn.jsdelivr.net/npm/package-name@<VERSION>/dist/index.bundle.js"
-}
-```
-
-## `tsconfig.build.json`
-
-`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.
-
-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
-{
-
-  "extends": "./tsconfig.json",
-
-  "compilerOptions": {
-
-    // narrows root to src/ for distribution output
-    "rootDir": "./src/",
-
-    // nodenext enforces strict ESM compliance; imports must use explicit .js file extensions
-    "module": "nodenext",
-    "moduleResolution": "nodenext",
-
-    // 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/"
-
-  },
-
-  // include only src/ files for distribution
-  "include": [
-    "src/**/*.ts"
-  ],
-  // exclude development files and directories from distribution
-  "exclude": [
-    "node_modules/",
-    "dist/",
-    "tests/",
-    "scripts/"
-  ]
-
-}
-```
-
-### `package.json`
-
-```json
-{
-  // ... ,
-  "scripts": {
-    // ... ,
-    "build": "... && bun run build:tsc",
-    "build:tsc": "tsc --project tsconfig.build.json"
-  }
-}
-```
-
-Exports condition `import` may point to the compiled output instead of the bundled output `./dist/index.bundle.js` if `"emitDeclarationOnly": false`:
-
-```json
-{
-  // ... ,
-  "exports": {
-    ".": {
-      // ... ,
-      "import": "./dist/index.js"
-    }
-  },
-  // ... ,
-}
-```
-
-When `"declaration": true`, then exports condition `types` can be added to point to the declaration files:
-
-```json
-{
-  // ... ,
-  "exports": {
-    ".": {
-      // ... ,
-      "types": "./dist/index.d.ts",
-      // ... ,
-    }
-  },
-  // ... ,
-}
-```
-
-## Asset Resolution
-
-The key question to ask is: **does my library retain its own URL at runtime?** Everything else follows from it.
-
-```bash
-# placeholder:
-  # <@SCOPE: <@SCOPE>
-  # <LIB_NAME: <LIB_NAME>
-  # <VERSION: <VERSION>
-```
-
-### Externalized - loaded from CDN or `node_modules/`
-
-The consumer does not bundle the library. It is loaded as a discrete module at runtime. Module identity is preserved regardless of the URL form:
-
-```
-https://cdn.jsdelivr.net/npm/<@SCOPE>/<LIB_NAME>@<VERSION>/dist/index.js
-file:///project/node_modules/<@SCOPE>/<LIB_NAME>/dist/index.js
-https://your-own-cdn.com/<LIB_NAME>/index.js
-```
-
-`import.meta.url` is reliable in all these cases. `fetch()` is the correct I/O mechanism because it accepts both `https://` and `file://` URLs, making it universally correct for isomorphic (`--target node` or `--target browser`) libraries.
-
-### 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 output directory at the same relative path the library expects, `import.meta.url` resolution continues to work correctly.
-
-### Contract
-
-If the library has runtime assets, the following contract applies:
-
-**The library must:**
-1. **Place assets in a scoped assets directory** - see [Scoped assets directory convention](#scoped-assets-directory-convention) below.
-2. **Access assets via `import.meta.url`** - see [Accessing assets](#accessing-assets) below.
-3. **Document the bundled case** - see [README statement for library consumers](#readme-statement-for-library-consumers) below.
-
-**The consumer must,**
-- **when loading the library externalized:** do nothing - the library's `import.meta.url` works as-is, and assets load from their original location (CDN or `node_modules/`).
-- **when bundling the library:**
-    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 output directory
-
-#### Scoped assets directory convention
-
-Place all runtime assets under a scoped directory that mirrors the package name:
-
-```
-assets/
-└── <@SCOPE>/
-    └── <LIB_NAME>/
-        └── ...
-```
-
-Add `assets/` to the `files` field in `package.json` so that the assets are included in the published package:
-
-```json
-{
-  // ... ,
-  "files": [
-    // ... ,
-    "assets/"
-  ],
-  // ... ,
-}
-```
-
-#### Accessing assets
-
-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` and `--target node` (isomorphic)
-const assetUrl = new URL('<ASSET>', assetsUrl);
-const asset = await fetch(assetUrl).then(response => response.body);
-
-// for `--target node` only
-import { readFile } from 'fs/promises';
-import { fileURLToPath } from 'url';
-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
-
-```markdown
-## Asset resolution
-
-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
-
-The consumer must copy the assets into their build output at the same relative path the library expects:
-
-```
-consumer output/
-├── bundle.js               ← import.meta.url points here
-└── assets/
-    └── <@SCOPE>/
-        └── <LIB_NAME>/
-            └── ...         ← copied; relative path preserved
-```
-
-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
-
-# see publish section for publish instructions
-```
-
-## Change Management
-
-1. Create a new branch for the change.
-2. Make the changes and commit.
-3. Bump the version in [`package.json`](package.json).
-4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
-5. Pull request the branch.
-6. Ensure package artifacts are current.
-7. Publish.
-
-## Publish
-
-Publish to the public npm registry.
-
-```powershell
-# authenticate
-npm login
-# publish
-bun publish --registry https://registry.npmjs.org/ --access public
-```

package/template/buildinfo-template.txt

@@ -1 +0,0 @@
-0.8.0+545e022