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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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`.

package/README.md

@@ -143,12 +143,12 @@ The generated package is pre-configured with `build:bundle` only. See [TSC Compi
     // convenience script to run the build steps in sequence
     "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",
-
     // 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"
 
@@ -239,7 +239,7 @@ See [`create-workspace` README](https://www.npmjs.com/package/@temir.ra/create-w
 }
 ```
 
-Exports condition `import` may point to the compiled output instead of the bundled output `./dist/index.bundle.js`:
+Exports condition `import` may point to the compiled output instead of the bundled output `./dist/index.bundle.js` if `"emitDeclarationOnly": false`:
 
 ```json
 {
@@ -295,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
 
@@ -312,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
 
@@ -325,35 +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` and `--target node` (isomorphic)
+const assetUrl = new URL('<ASSET>', assetsUrl);
+const asset = await fetch(assetUrl).then(response => response.body);
 
-// for --target browser
-const asset = await fetch(new URL('<ASSET>', assetsUrl)).then(r => r.json());
-
-// 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
@@ -361,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

package/buildinfo.txt

@@ -1 +1 @@
-0.7.6+b2fa591
+0.8.0+545e022

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "A template for a distributable TypeScript library package.",
   "author": "temir.ra",
   "license": "MIT",

package/template/README.md

@@ -67,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

@@ -17,8 +17,15 @@
   "exports": {
     ".": {
       "entrypoint": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "browser": "./dist/index.bundle.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": {
@@ -41,8 +48,9 @@
     "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",

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