@temir.ra/create-ts-lib 0.1.0 → 0.2.1-patch.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Version 0
 
+## 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).
+
+### patch.1
+
+1. Fixed minor documentation issues.
+
+### patch.2
+
+1. Fixed missing `template/` files in the published package.
+
 ## 0.1.0
 
 1. First version of the template.

package/README.md

@@ -11,7 +11,7 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
     3. [Script `scripts/buildinfo.ts`](#script-scriptsbuildinfots)
     4. [Script `scripts/build-lib-bundle.ts`](#script-scriptsbuild-lib-bundlets)
     5. [CDN Map `scripts/cdn-rewrite-map.json`](#cdn-map-scriptscdn-rewrite-mapjson)
-    6. [`src/urls.ts`](#srcurlsts)
+    6. [Asset Resolution](#asset-resolution)
     7. [`src/dev.ts`](#srcdevts)
     8. [`CLAUDE.md` / `AGENTS.md`](#claudemd--agentsmd)
 3. [DevOps](#devops)
@@ -184,10 +184,10 @@ bun install
   "sideEffects": false,
 
   // package entry points by consumer type
-  // "entrypoint" — custom condition; used by the bundle script to locate the source entry point
-  // "types"      — TypeScript consumers; resolves to the declaration files; must precede "import" so TypeScript matches it before the JS condition
-  // "browser"    — browser bundler consumers; resolves to the bundled output
-  // "import"     — ESM consumers; resolves to the compiled module output
+  // "entrypoint" - custom condition; used by the bundle script to locate the source entry point
+  // "types"      - TypeScript consumers; resolves to the declaration files; must precede "import" so TypeScript matches it before the JS condition
+  // "browser"    - browser bundler consumers; resolves to the bundled output
+  // "import"     - ESM consumers; resolves to the compiled module output
   "exports": {
     ".": {
       "entrypoint": "./src/index.ts",
@@ -198,7 +198,7 @@ bun install
   },
 
   // package-internal import alias resolved natively by Node.js and Bun at runtime; key must start with #
-  // for use in dev.ts, tests/, and scripts/ only — NOT in library source files compiled by tsconfig.build.json
+  // for use in dev.ts, tests/, and scripts/ only - NOT in library source files compiled by tsconfig.build.json
   // the .js extension is required in import statements (nodenext compliance);
   // the runtime maps it to the actual .ts source file via this field
   "imports": {
@@ -284,20 +284,149 @@ For CLI packages, add the following to `package.json`:
 }
 ```
 
-## `src/urls.ts`
+## Asset Resolution
 
-Resolves `CHANGELOG.md` and `buildinfo.txt` relative to `dist/` at runtime using `import.meta.url`. Provides stable references to published package assets regardless of install location.
+The key question to ask is: **does my library retain its own URL at runtime?** Module identity is the invariant. Everything else follows from it.
+
+### 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@1.0.0/dist/index.js
+file:///project/node_modules/@scope/lib/dist/index.js
+https://your-own-cdn.com/lib/index.js
+```
+
+`import.meta.url` is reliable in all these cases. Asset paths resolve automatically - the consumer does nothing. `fetch()` is the correct I/O mechanism because it accepts both `https://` and `file://` URLs, making it universally correct for isomorphic (browser + Node) libraries.
+
+### Bundled into the consumer's app
+
+The consumer's bundler absorbs the library into their own output file. Module identity is destroyed - `import.meta.url` now points to the consumer's bundle, not the library's file. 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.
+
+### Scoped asset folder convention
+
+Place all runtime assets under a scoped directory that mirrors the package name:
+
+```
+assets/
+└── @scope/
+    └── lib-name/
+        ├── schema.json
+        └── data.json
+```
+
+This 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 npm publishes it:
+
+```json
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "buildinfo.txt",
+    "assets"
+  ],
+```
+
+### Accessing assets
+
+Construct asset URLs directly from `import.meta.url`. Replace `@scope/lib-name` with your actual package name:
+
+```typescript
+const packageUrl = new URL('../', import.meta.url);
+const assetsUrl  = new URL('assets/@scope/lib-name/', packageUrl);
+
+// isomorphic (browser or Node) - fetch accepts both https:// and file:// URLs
+const schema = await fetch(new URL('schema.json', assetsUrl)).then(r => r.json());
+
+// server-only (Node/Bun)
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'url';
+const data = JSON.parse(await readFile(fileURLToPath(new URL('data.json', assetsUrl)), 'utf-8'));
+```
+
+`fetch()` is the correct I/O primitive for isomorphic libraries: it accepts both `https://` URLs (CDN/production) and `file://` URLs (node_modules/development) without any special handling.
+
+> **Server-only libraries** (no browser target, bundled-into-consumer scenario unlikely): use `readFile` directly - `fetch()` is not required. The scoped asset convention still applies unchanged.
+
+### 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/
+            ├── schema.json         ← copied; relative path preserved
+            └── data.json
+```
+
+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/schema.json', import.meta.url)` resolves correctly. No code configuration is needed - only the file copy.
+
+### Setup
+
+If your library has runtime assets, the steps to wire everything up:
+
+1. **Create the scoped directory** `assets/@scope/lib-name/` and place asset files inside (replace `@scope/lib-name` with your actual package name).
+
+2. **Access assets via `import.meta.url`** - see [Accessing assets](#accessing-assets) above.
+
+3. **Publish the assets** - add `assets/` to the `files` field in `package.json`:
+   ```json
+    "files": [
+      "dist",
+      "CHANGELOG.md",
+      "buildinfo.txt",
+      "assets"
+    ],
+   ```
+
+4. **Document the bundled case** - copy the [README statement](#readme-statement-for-your-consumers) into your library's README.
+
+### Contract
+
+**The library must:**
+- Place assets under `assets/@scope/lib-name/` (mirroring the package name)
+- Resolve asset paths via `import.meta.url` - no shared helper file required
+- Include `assets/` in `package.json` `files`
+- Document the bundled-case copy requirement in its README
+
+**The consumer must, when bundling the library:**
+- Copy `node_modules/@scope/lib-name/assets/` into their build output alongside the bundle
+- Ensure assets are served
+
+**The consumer must do nothing when loading the library externalized.** Asset resolution is automatic.
+
+### Checklist
+
+- [ ] Assets live under `assets/@scope/lib-name/` (matching the package name)
+- [ ] `assets/` is listed in `package.json` `files`
+- [ ] All asset access resolves paths via `import.meta.url` - no hardcoded paths
+- [ ] Library README documents the bundled-case copy requirement (see statement below)
+
+### README statement for your consumers
+
+Copy this into your library's README:
+
+> **Asset resolution**
+>
+> This library resolves assets at runtime using `import.meta.url`. It works automatically when the library is loaded as an external module (from CDN or node_modules).
+>
+> 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. No code configuration is required.
 
 ## `src/dev.ts`
 
-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.
+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.
 
 ## `CLAUDE.md` / `AGENTS.md`
 
 AI assistant context files. Provide project layout, commands, and architecture notes. `AGENTS.md` references `CLAUDE.md`. The template ships two pairs:
 
-- Root pair — describes the template package itself (scaffolding tool, CLI, how `template/` maps to generated projects)
-- `template/` pair — describes the generated library project; update to reflect the specific library being developed
+- Root pair - describes the template package itself (scaffolding tool, CLI, how `template/` maps to generated projects)
+- `template/` pair - describes the generated library project; update to reflect the specific library being developed
 
 # DevOps
 

package/buildinfo.txt

@@ -1 +1 @@
-0.1.0+d78d3df
+0.2.1+5ddcc14

package/dist/cli.bundle.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import{cpSync as o,readFileSync as U,renameSync as f,writeFileSync as d}from"fs";import{resolve as t,basename as u}from"path";import{fileURLToPath as a}from"url";var n=new URL(".",import.meta.url),l=new URL("../CHANGELOG.md",n),p=new URL("../buildinfo.txt",n),m=new URL("../template",n);try{let r=process.argv[2];if(!r)throw Error("Destination path is required. Usage: `bun/npm create <template> <destination>`");let e=t(process.cwd(),r),i=u(e),g=t(a(m));o(g,e,{recursive:!0}),o(t(a(l)),t(e,"CHANGELOG-template.md")),o(t(a(p)),t(e,"buildinfo-template.txt"));let s=t(e,"package.json"),c=JSON.parse(U(s,"utf-8"));c.name=i,d(s,JSON.stringify(c,null,2)),f(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${i}'.`)}catch(r){let e=r instanceof Error?r:Error(String(r));console.error("Error:",e.message),process.exit(1)}
+import{cpSync as r,readFileSync as m,renameSync as p,writeFileSync as g}from"fs";import{resolve as t,basename as f}from"path";import{fileURLToPath as a}from"url";var o=new URL("../template/",import.meta.url),d=new URL("CHANGELOG.md",o),u=new URL("buildinfo.txt",o);try{let n=process.argv[2];if(!n)throw Error("Destination path is required. Usage: `bun/npm create <template> <destination>`");let e=t(process.cwd(),n),s=f(e),l=t(a(o));r(l,e,{recursive:!0}),r(t(a(d)),t(e,"CHANGELOG-template.md")),r(t(a(u)),t(e,"buildinfo-template.txt"));let i=t(e,"package.json"),c=JSON.parse(m(i,"utf-8"));c.name=s,g(i,JSON.stringify(c,null,2)),p(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${s}'.`)}catch(n){let e=n instanceof Error?n:Error(String(n));console.error("Error:",e.message),process.exit(1)}
 
-//# debugId=683E20367A2ED95764756E2164756E21
+//# debugId=4F322049A7A4E1DA64756E2164756E21

package/dist/cli.bundle.js.map

@@ -1,11 +1,10 @@
 {
   "version": 3,
-  "sources": ["..\\src\\cli.ts", "..\\src\\urls.ts"],
+  "sources": ["..\\src\\cli.ts"],
   "sourcesContent": [
-    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport { fileURLToPath } from 'url';\r\nimport { buildinfoUrl, changelogUrl, templateUrl } from '#src/urls.js';\r\n\r\n\r\ntry {\r\n\r\n    const dest = process.argv[2];\r\n    if (!dest) throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');\r\n\r\n    const destinationPath = resolve(process.cwd(), dest);\r\n    const packageName = basename(destinationPath);\r\n\r\n    const templatePath = resolve(fileURLToPath(templateUrl));\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(resolve(fileURLToPath(changelogUrl)), resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(resolve(fileURLToPath(buildinfoUrl)), resolve(destinationPath, 'buildinfo-template.txt'));\r\n\r\n    const packageManifestPath = resolve(destinationPath, 'package.json');\r\n    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));\r\n    packageManifest.name = packageName;\r\n    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, 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",
-    "export const distUrl: URL = new URL('.', import.meta.url);\r\nexport const changelogUrl: URL = new URL('../CHANGELOG.md', distUrl);\r\nexport const buildinfoUrl: URL = new URL('../buildinfo.txt', distUrl);\r\nexport const templateUrl: URL = new URL('../template', distUrl);\r\n"
+    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nconst templateUrl = new URL('../template/', import.meta.url);\r\nconst changelogUrl = new URL('CHANGELOG.md', templateUrl);\r\nconst buildinfoUrl = new URL('buildinfo.txt', templateUrl);\r\n\r\n\r\ntry {\r\n\r\n    const dest = process.argv[2];\r\n    if (!dest) throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');\r\n\r\n    const destinationPath = resolve(process.cwd(), dest);\r\n    const packageName = basename(destinationPath);\r\n\r\n    const templatePath = resolve(fileURLToPath(templateUrl));\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(resolve(fileURLToPath(changelogUrl)), resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(resolve(fileURLToPath(buildinfoUrl)), resolve(destinationPath, 'buildinfo-template.txt'));\r\n\r\n    const packageManifestPath = resolve(destinationPath, 'package.json');\r\n    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));\r\n    packageManifest.name = packageName;\r\n    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, 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"
   ],
-  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,cAAS,aAClB,wBAAS,YCJF,IAAM,EAAe,IAAI,IAAI,IAAK,YAAY,GAAG,EAC3C,EAAoB,IAAI,IAAI,kBAAmB,CAAO,EACtD,EAAoB,IAAI,IAAI,mBAAoB,CAAO,EACvD,EAAmB,IAAI,IAAI,cAAe,CAAO,EDK9D,GAAI,CAEA,IAAM,EAAO,QAAQ,KAAK,GAC1B,GAAI,CAAC,EAAM,MAAU,MAAM,gFAAgF,EAE3G,IAAM,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAI,EAC7C,EAAc,EAAS,CAAe,EAEtC,EAAe,EAAQ,EAAc,CAAW,CAAC,EAEvD,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,uBAAuB,CAAC,EAC9F,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,wBAAwB,CAAC,EAE/F,IAAM,EAAsB,EAAQ,EAAiB,cAAc,EAC7D,EAAkB,KAAK,MAAM,EAAa,EAAqB,OAAO,CAAC,EAC7E,EAAgB,KAAO,EACvB,EAAc,EAAqB,KAAK,UAAU,EAAiB,KAAM,CAAC,CAAC,EAE3E,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",
-  "debugId": "683E20367A2ED95764756E2164756E21",
+  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,cAAS,aAClB,wBAAS,YAGT,IAAM,EAAc,IAAI,IAAI,eAAgB,YAAY,GAAG,EACrD,EAAe,IAAI,IAAI,eAAgB,CAAW,EAClD,EAAe,IAAI,IAAI,gBAAiB,CAAW,EAGzD,GAAI,CAEA,IAAM,EAAO,QAAQ,KAAK,GAC1B,GAAI,CAAC,EAAM,MAAU,MAAM,gFAAgF,EAE3G,IAAM,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAI,EAC7C,EAAc,EAAS,CAAe,EAEtC,EAAe,EAAQ,EAAc,CAAW,CAAC,EAEvD,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,uBAAuB,CAAC,EAC9F,EAAO,EAAQ,EAAc,CAAY,CAAC,EAAG,EAAQ,EAAiB,wBAAwB,CAAC,EAE/F,IAAM,EAAsB,EAAQ,EAAiB,cAAc,EAC7D,EAAkB,KAAK,MAAM,EAAa,EAAqB,OAAO,CAAC,EAC7E,EAAgB,KAAO,EACvB,EAAc,EAAqB,KAAK,UAAU,EAAiB,KAAM,CAAC,CAAC,EAE3E,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",
+  "debugId": "4F322049A7A4E1DA64756E2164756E21",
   "names": []
 }

package/dist/cli.js

@@ -2,7 +2,9 @@
 import { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { resolve, basename } from 'path';
 import { fileURLToPath } from 'url';
-import { buildinfoUrl, changelogUrl, templateUrl } from '#src/urls.js';
+const templateUrl = new URL('../template/', import.meta.url);
+const changelogUrl = new URL('CHANGELOG.md', templateUrl);
+const buildinfoUrl = new URL('buildinfo.txt', templateUrl);
 try {
     const dest = process.argv[2];
     if (!dest)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.1.0",
+  "version": "0.2.1-patch.2",
   "description": "Typescript library template",
   "author": "temir.ra",
   "license": "MIT",

package/template/AGENTS.md

@@ -1 +1 @@
-See [CLAUDE.md](CLAUDE.md).
+See [CLAUDE.md](CLAUDE.md).

package/template/CLAUDE.md

@@ -1,132 +1,158 @@
-# <package-name>
-
-A Bun TypeScript library.
-
-## Project Layout
-
-```
-<package-name>/
-├── src/
-│   ├── index.ts        # Library entry point (public API)
-│   ├── dev.ts          # Development scratchpad — run with `bun run dev`
-│   └── urls.ts         # URL helpers (changelog, buildinfo)
-├── scripts/
-│   ├── buildinfo.ts            # Writes version + git hash to buildinfo.txt
-│   ├── build-lib-bundle.ts     # Bundles the library for ESM + CDN distribution
-│   └── cdn-rewrite-map.json    # CDN import rewrite rules (empty by default)
-├── tests/              # Unit tests (Bun test runner)
-├── dist/               # Build output (gitignored)
-├── buildinfo.txt       # Written during build; included in published package
-├── CHANGELOG.md        # Version history
-├── CLAUDE.md           # This file — AI context for the library project
-└── AGENTS.md           # References CLAUDE.md
-```
-
-## Commands
-
-```bash
-bun install       # Install dependencies
-bun run build     # Compile + bundle the library
-bun run tests     # Run unit tests
-bun run typecheck # Type-check without emitting
-bun run dev       # Run src/dev.ts in watch mode
-bun run clean              # Remove dist/ and tsconfig.build.tsbuildinfo
-bun run clean:dist         # Remove dist/ only
-bun run clean:tsbuildinfo  # Remove tsconfig.build.tsbuildinfo only
-```
-
-## Writing Code
-
-### Where things go
-
-| Path | Purpose |
-|------|---------|
-| `src/index.ts` | Public API — the only entry point consumers see; export everything public from here |
-| `src/*.ts` | Library source modules — add new modules here, re-export from `index.ts` |
-| `src/dev.ts` | Development scratchpad — excluded from build, never published; use for manual testing |
-| `tests/*.test.ts` | Unit tests — Bun test runner |
-
-### Imports within `src/`
-
-`tsconfig.build.json` uses `moduleResolution: nodenext`, so imports between library source files must use explicit `.js` extensions:
-
-```ts
-import { helper } from "./helper.js"  // ✓
-import { helper } from "./helper"     // ✗ — fails under nodenext
-```
-
-The `#src/*.js` package alias is available in `dev.ts`, `tests/`, and `scripts/`, but **not** in library source files — tsc emits the specifier verbatim and it would break in published unbundled output.
-
-### Explicit return types (`isolatedDeclarations`)
-
-All exported declarations require explicit type annotations so tsc can emit `.d.ts` files without cross-file inference:
-
-```ts
-export function greet(name: string): string { ... }  // ✓
-export function greet(name: string) { ... }          // ✗ — implicit return type
-```
-
-### Type-only imports (`verbatimModuleSyntax`)
-
-Use `import type` for imports that are only used as types:
-
-```ts
-import type { Foo } from "./foo.js"       // ✓ — type-only import
-import { type Foo, bar } from "./foo.js"  // ✓ — mixed
-import { Foo } from "./foo.js"            // ✗ — if Foo is only used as a type
-```
-
-### Tests
-
-Tests live in `tests/` and use Bun's built-in runner:
-
-```ts
-import { describe, test, expect } from "bun:test"
-
-describe("greet", () => {
-  test("returns greeting", () => {
-    expect(greet("world")).toBe("hello, world")
-  })
-})
-```
-
-Run with `bun run tests`.
-
-## TypeScript Configuration
-
-Two tsconfig files serve different purposes:
-
-| File | Purpose |
-|------|---------|
-| `tsconfig.json` | Development — no emit, includes `src/`, `tests/`, `scripts/` |
-| `tsconfig.build.json` | Build — emits JS + `.d.ts`, `src/` only (excludes `dev.ts`, tests, scripts) |
-
-`bun run build:lib` uses `tsconfig.build.json`. During development the runtime handles TypeScript directly so no compilation step is needed.
-
-Both configs enable an extended strict type-safety profile beyond `strict`: `verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `isolatedDeclarations`.
-
-## Build Outputs
-
-`bun run build` runs two steps in sequence:
-
-1. **`build:lib`** — `tsc --project tsconfig.build.json` → `dist/*.js` + `dist/*.d.ts`
-2. **`build:lib-bundle`** — `scripts/build-lib-bundle.ts` → `dist/index.bundle.js` (ESM, minified) + `dist/index.iife.js` (IIFE, minified)
-
-The `exports` field in `package.json` maps consumers to the right file:
-
-| Condition | File |
-|-----------|------|
-| `types` | `dist/index.d.ts` |
-| `browser` | `dist/index.bundle.js` |
-| `import` | `dist/index.js` |
-
-## Package Configuration
-
-Key `package.json` fields:
-
-- `"sideEffects": false` — enables full tree-shaking by bundlers
-- `"imports": { "#src/*.js": "./src/*.ts" }` — package-internal alias for `src/`; use as `import { foo } from "#src/module.js"`. **Only for `dev.ts`, `tests/`, and `scripts/`** — not for library source files compiled by `tsconfig.build.json`, as tsc emits the specifier verbatim and it would break in published unbundled output.
-
-## Publishing
-
-See [README.md](README.md) for registry setup and publish commands.
+# <package-name>
+
+A Bun TypeScript library.
+
+## Project Layout
+
+```
+<package-name>/
+├── src/
+│   ├── index.ts        # Library entry point (public API)
+│   └── dev.ts          # Development scratchpad — run with `bun run dev`
+├── scripts/
+│   ├── buildinfo.ts            # Writes version + git hash to buildinfo.txt
+│   ├── build-lib-bundle.ts     # Bundles the library for ESM + CDN distribution
+│   └── cdn-rewrite-map.json    # CDN import rewrite rules (empty by default)
+├── tests/              # Unit tests (Bun test runner)
+├── dist/               # Build output (gitignored)
+├── buildinfo.txt       # Written during build; included in published package
+├── CHANGELOG.md        # Version history
+├── CLAUDE.md           # This file — AI context for the library project
+└── AGENTS.md           # References CLAUDE.md
+```
+
+## Commands
+
+```bash
+bun install       # Install dependencies
+bun run build     # Compile + bundle the library
+bun run tests     # Run unit tests
+bun run typecheck # Type-check without emitting
+bun run dev       # Run src/dev.ts in watch mode
+bun run clean              # Remove dist/ and tsconfig.build.tsbuildinfo
+bun run clean:dist         # Remove dist/ only
+bun run clean:tsbuildinfo  # Remove tsconfig.build.tsbuildinfo only
+```
+
+## Writing Code
+
+### Where things go
+
+| Path | Purpose |
+|------|---------|
+| `src/index.ts` | Public API — the only entry point consumers see; export everything public from here |
+| `src/*.ts` | Library source modules — add new modules here, re-export from `index.ts` |
+| `src/dev.ts` | Development scratchpad — excluded from build, never published; use for manual testing |
+| `tests/*.test.ts` | Unit tests — Bun test runner |
+
+### Imports within `src/`
+
+`tsconfig.build.json` uses `moduleResolution: nodenext`, so imports between library source files must use explicit `.js` extensions:
+
+```ts
+import { helper } from "./helper.js"  // ✓
+import { helper } from "./helper"     // ✗ — fails under nodenext
+```
+
+The `#src/*.js` package alias is available in `dev.ts`, `tests/`, and `scripts/`, but **not** in library source files — tsc emits the specifier verbatim and it would break in published unbundled output.
+
+### Explicit return types (`isolatedDeclarations`)
+
+All exported declarations require explicit type annotations so tsc can emit `.d.ts` files without cross-file inference:
+
+```ts
+export function greet(name: string): string { ... }  // ✓
+export function greet(name: string) { ... }          // ✗ — implicit return type
+```
+
+### Type-only imports (`verbatimModuleSyntax`)
+
+Use `import type` for imports that are only used as types:
+
+```ts
+import type { Foo } from "./foo.js"       // ✓ — type-only import
+import { type Foo, bar } from "./foo.js"  // ✓ — mixed
+import { Foo } from "./foo.js"            // ✗ — if Foo is only used as a type
+```
+
+### Asset Resolution (if the library has runtime assets)
+
+Place runtime assets (JSON data, WASM, binary files, etc.) under a scoped directory that mirrors the package name — this prevents naming collisions when multiple libraries are bundled into the same consumer app:
+
+```
+assets/@scope/lib-name/
+├── data.json
+└── model.wasm
+```
+
+Resolve asset URLs inline from `import.meta.url` — no shared helper file:
+
+```typescript
+const packageUrl = new URL('../', import.meta.url);
+const assetsUrl  = new URL('assets/@scope/lib-name/', packageUrl);
+
+// isomorphic (browser + Node) — fetch() handles both https:// and file:// URLs
+const data = await fetch(new URL('data.json', assetsUrl)).then(r => r.json());
+
+// server-only (Node/Bun)
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'url';
+const raw = await readFile(fileURLToPath(new URL('data.json', assetsUrl)), 'utf-8');
+```
+
+Add `assets/` to `files` in `package.json` so it is included in the published package. See the [create-ts-lib README](../README.md) Asset Resolution section for the full setup guide, checklist, and the README statement to copy for your consumers.
+
+### Tests
+
+Tests live in `tests/` and use Bun's built-in runner:
+
+```ts
+import { describe, test, expect } from "bun:test"
+
+describe("greet", () => {
+  test("returns greeting", () => {
+    expect(greet("world")).toBe("hello, world")
+  })
+})
+```
+
+Run with `bun run tests`.
+
+## TypeScript Configuration
+
+Two tsconfig files serve different purposes:
+
+| File | Purpose |
+|------|---------|
+| `tsconfig.json` | Development — no emit, includes `src/`, `tests/`, `scripts/` |
+| `tsconfig.build.json` | Build — emits JS + `.d.ts`, `src/` only (excludes `dev.ts`, tests, scripts) |
+
+`bun run build:lib` uses `tsconfig.build.json`. During development the runtime handles TypeScript directly so no compilation step is needed.
+
+Both configs enable an extended strict type-safety profile beyond `strict`: `verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `isolatedDeclarations`.
+
+## Build Outputs
+
+`bun run build` runs two steps in sequence:
+
+1. **`build:lib`** — `tsc --project tsconfig.build.json` → `dist/*.js` + `dist/*.d.ts`
+2. **`build:lib-bundle`** — `scripts/build-lib-bundle.ts` → `dist/index.bundle.js` (ESM, minified) + `dist/index.iife.js` (IIFE, minified)
+
+The `exports` field in `package.json` maps consumers to the right file:
+
+| Condition | File |
+|-----------|------|
+| `types` | `dist/index.d.ts` |
+| `browser` | `dist/index.bundle.js` |
+| `import` | `dist/index.js` |
+
+## Package Configuration
+
+Key `package.json` fields:
+
+- `"sideEffects": false` — enables full tree-shaking by bundlers
+- `"imports": { "#src/*.js": "./src/*.ts" }` — package-internal alias for `src/`; use as `import { foo } from "#src/module.js"`. **Only for `dev.ts`, `tests/`, and `scripts/`** — not for library source files compiled by `tsconfig.build.json`, as tsc emits the specifier verbatim and it would break in published unbundled output.
+
+## Publishing
+
+See [README.md](README.md) for registry setup and publish commands.

package/template/README.md

@@ -32,10 +32,12 @@ bun run tests
 bun run dev
 ```
 
-**Publish** — see [Publish](#publish).
+**Publish** - see [Publish](#publish).
 
 # Documentation
 
+> If this library has runtime assets, see the **Asset Resolution** section in the create-ts-lib README for the setup guide, code examples, checklist, and consumer README statement.
+
 *<DOCUMENTATION>*
 
 # DevOps

package/template/src/dev.ts

@@ -1,12 +1,10 @@
-import { buildinfoUrl, changelogUrl, distUrl } from '#src/urls.js';
 import { fileURLToPath } from 'url';
 
 
 const start: number = performance.now();
 
-console.log(`'distPath':`, fileURLToPath(distUrl));
-console.log(`'buildinfoPath':`, fileURLToPath(buildinfoUrl));
-console.log(`'changelogPath':`, fileURLToPath(changelogUrl));
+const packageUrl = new URL('../', import.meta.url);
+console.log(`'packagePath':`, fileURLToPath(packageUrl));
 
 
 // dev code

package/template/tests/buildinfo.test.ts

@@ -1,7 +1,8 @@
 import { describe, it, expect } from 'bun:test';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { buildinfoUrl } from '#src/urls.js';
+
+const buildinfoUrl = new URL('../buildinfo.txt', import.meta.url);
 
 
 describe('buildInfo', () => {

package/dist/urls.d.ts

@@ -1,5 +0,0 @@
-export declare const distUrl: URL;
-export declare const changelogUrl: URL;
-export declare const buildinfoUrl: URL;
-export declare const templateUrl: URL;
-//# sourceMappingURL=urls.d.ts.map

package/dist/urls.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../src/urls.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,EAAE,GAAmC,CAAC;AAC1D,eAAO,MAAM,YAAY,EAAE,GAAyC,CAAC;AACrE,eAAO,MAAM,YAAY,EAAE,GAA0C,CAAC;AACtE,eAAO,MAAM,WAAW,EAAE,GAAqC,CAAC"}

package/dist/urls.js

@@ -1,4 +0,0 @@
-export const distUrl = new URL('.', import.meta.url);
-export const changelogUrl = new URL('../CHANGELOG.md', distUrl);
-export const buildinfoUrl = new URL('../buildinfo.txt', distUrl);
-export const templateUrl = new URL('../template', distUrl);

package/template/src/urls.ts

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