@temir.ra/create-test115 0.0.12

package/README.md

@@ -0,0 +1,289 @@
+# Introduction
+
+This package serves as a template for creating Bun libraries. It includes a basic setup with TypeScript, build scripts, and versioning information.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+    1. [`tsconfig.json` and `tsconfig.build.json`](#tsconfigjson-and-tsconfigbuildjson)
+    2. [`package.json`](#packagejson)
+    3. [Script `scripts/buildinfo.ts`](#script-scriptsbuildinfots)
+    4. [Script `scripts/build-cdn.ts`](#script-scriptsbuild-cdn-ts)
+    5. [CDN Map `scripts/build-cdn-map.json`](#cdn-map-scriptsbuild-cdn-mapjson)
+3. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+
+# Quick Start
+
+```bash
+# placeholder:
+    # <PACKAGE: <PACKAGE>
+
+bun create temir-ra/bun-lib-template --no-install --no-git <PACKAGE>
+cd <PACKAGE>
+bun install
+
+bun run dev
+bun run test
+
+bun run build
+
+bun publish
+```
+
+# Documentation
+
+`README-template.md` and `CHANGELOG-template.md` are the actual documentation files for this template package. Whereas `README.md` and `CHANGELOG.md` are copied as part of the package creation process and should be modified by the user to reflect the specifics of their library.
+
+## `tsconfig.json` and `tsconfig.build.json`
+
+```json
+{
+
+  "compilerOptions": {
+
+    // supported JavaScript features and syntax in the emitted JavaScript files
+    // ES2022 is a reasonable modern baseline
+    "target": "ES2022",
+    
+    // how import and export statements are written in the emitted JavaScript files
+    // ESNext emits standard ES module syntax unchanged
+    "module": "ESNext",
+    
+    // available built-in types
+    "lib": [
+      "ES2022", // standard JavaScript runtime APIs
+      "DOM"     // browser globals or import.meta.url
+    ],
+
+    // permissive about file extensions in import statements
+    // `tsconfig.build.json` switches to a stricter resolution mode
+    "moduleResolution": "bundler",
+
+    // collection of type-safety checks
+    "strict": true,
+
+    // compatibility shims that make it easier to import CommonJS modules as if they were ES modules
+    "esModuleInterop": true,
+
+    // do not type-check `.d.ts` files in `node_modules/`
+    "skipLibCheck": true,
+
+    // enforce consistent casing across import statements
+    "forceConsistentCasingInFileNames": true,
+
+    // allow importing JSON files as modules and infer the full type of the JSON structure
+    "resolveJsonModule": true,
+
+    // generate .d.ts type declaration files alongside the JavaScript output
+    "declaration": true,
+    // allow a consumer's editor to "go to definition" on something from the library
+    "declarationMap": true,
+
+    // prevents tsc from emitting any JavaScript files
+    // during development, rely on executing environment to handle TypeScript directly
+    // during build, use `tsconfig.build.json` to override this setting and emit JavaScript files for distribution
+    "emitDeclarationOnly": true,
+
+    // the directory where the emitted JavaScript and declaration files will be placed when building the library for distribution
+    // matches the `files` field in `package.json` that determines what gets published
+    "outDir": "./dist",
+
+    // the base directory to resolve non-relative module imports
+    "baseUrl": ".",
+
+    // a mapping of module import paths to physical paths in the project
+    // `paths` is a TypeScript-only feature - it must not be used in import statements in `src/` files
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+
+  },
+
+  // files to be included/excluded by the TypeScript compiler and the development environment
+  // `tsconfig.build.json` overrides these settings to include only `src/` files
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "scripts/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+
+}
+```
+
+During development, the `tsconfig.json` configuration prevents emitting JavaScript files and relies on the executing environment to handle TypeScript directly. The `include` and `exclude` settings ensure that all relevant TypeScript files are included in the development environment.
+
+When building the library for distribution, the `tsconfig.build.json` configuration overrides the settings to emit JavaScript files and include only the `src/` files.
+
+```json
+{
+
+  "extends": "./tsconfig.json",
+
+  "compilerOptions": {
+
+    // `nodenext` is the strictest and most forward-compatible ESM mode
+    // imports must include explicit `.js` file extensions
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+
+    // emit both JavaScript files and declaration files for distribution
+    "emitDeclarationOnly": false,
+
+  },
+
+  // include only the source files for the build, excluding tests and scripts
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "tests",
+    "scripts"
+  ]
+
+}
+```
+
+## `package.json`
+
+```json
+{
+  "name": "package",
+  "version": "0.0.0",
+  "description": "",
+
+  // "module" makes every `.js` file in the package to be treated as an ES module unless explicitly named `.cjs`
+  "type": "module",
+
+  // runtime consults "exports" to find the actual file to load
+  // "import" condition is used by ESM consumers
+  // "types" condition is used by TypeScript to find the declaration files
+  // "browser" condition is used by CDN infrastructure
+  // "entrypoint" is a custom condition used by the build script to find the entry point for the CDN build
+  "exports": {
+    ".": {
+      "entrypoint": "./src/index.ts",
+      "browser": "./dist/index.bundle.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+
+  // files to include in the published package
+  "files": [
+    "dist"
+  ],
+
+  "scripts": {
+
+    // cleans the `dist/` directory before building
+    "clean": "rm -rf dist/",
+
+    // overwrites `src/buildinfo.ts` with the current version and git hash (if available)
+    "prebuild": "bun run scripts/buildinfo.ts",
+
+    // runs all tests
+    "test": "bun test",
+
+    // runs all build steps in sequence
+    "build": "bun run build:lib && bun run build:cdn && bun run build:assets",
+
+    // uses `tsconfig.build.json` to compile the TypeScript source files
+    "build:lib": "tsc --project tsconfig.build.json",
+
+    // bundles the library for CDN distribution in both ESM and IIFE formats
+    "build:cdn": "bun run scripts/build-cdn.ts",
+
+    // placeholder for any asset build steps (e.g. copying static files, generating documentation, etc.)
+    "build:assets": "echo 'no assets to build'",
+
+    // type checks the TypeScript source files without emitting any output
+    "typecheck": "tsc --noEmit",
+
+    // runs the development file
+    "dev": "bun run --watch src/dev.ts"
+
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}
+```
+
+## Script `scripts/buildinfo.ts`
+
+This script overwrites `src/buildinfo.ts` with the current version from `package.json` and the current git hash (if available).
+
+## Script `scripts/build-cdn.ts`
+
+This script bundles the library for CDN distribution in both ESM and IIFE formats. It reads the `exports` field from `package.json` to determine the entry points for the library and generates bundled files in the `dist/` directory. A custom condition `entrypoint` is used in the `exports` field to specify the entry point for the CDN build.
+
+During the bundling process, the import paths in the source files can be rewritten to point to a CDN URL of a package, instead of using the package name that would be resolved from `node_modules/`.
+
+The list of import paths to rewrite and their corresponding CDN URLs can be configured in the `scripts/build-cdn-map.json` file.
+
+## CDN Map `scripts/build-cdn-map.json`
+
+This JSON file contains a mapping of module import paths to their corresponding CDN URLs. During the CDN build process, if an import path in the source files matches a key in this map, it will be replaced with the corresponding CDN URL in the bundled output.
+
+The URL can contain the placeholder `<VERSION>` which will be replaced with the current version of that package from `package.json`.
+
+```json
+{
+    "package-name": "https://cdn.jsdelivr.net/npm/package-name@<VERSION>/dist/index.bundle.js"
+}
+```
+
+- Keys are the import specifiers as they appear in source code.
+- Values are CDN URLs. The URL can contain the placeholder `<VERSION>` which will be replaced with the current version of that package from `package.json`.
+
+# DevOps
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit them to the branch.
+3. Add an entry for the new version in [`CHANGELOG-template.md`](CHANGELOG-template.md).
+4. Pull & publish request the branch.
+
+## Publish
+
+### `npmjs.org`
+
+⚠️ Either run `npm login` or set up `~/.npmrc` or `bunfig.toml` with the appropriate auth token before running the publish command.
+
+```powershell
+bun publish --registry https://registry.npmjs.org/ --access public
+```
+
+### Custom registry with `bun`
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`bunfig.toml`:
+
+```toml
+[install.scopes]
+<SCOPE_WITHOUT_AT> = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+bun publish
+```

package/README.md.template

@@ -0,0 +1,59 @@
+# Introduction
+
+*<INTRO TEXT>*
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+3. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+
+# Quick Start
+
+*<QUICK START INSTRUCTIONS>*
+
+# Documentation
+
+*<DOCUMENTATION>*
+
+# DevOps
+
+## Change Management
+
+1. Create a new branch for the change.
+2. Make the changes and commit them to the branch.
+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.
+
+## Publish
+
+### bun
+
+```bash
+# placeholder:
+    # <SCOPE_WITHOUT_AT: <SCOPE_WITHOUT_AT>
+    # <REGISTRY_URL: <REGISTRY_URL>
+    # <BUN_PUBLISH_AUTH_TOKEN: <BUN_PUBLISH_AUTH_TOKEN>
+```
+
+`bunfig.toml`:
+
+```toml
+[install.scopes]
+<SCOPE_WITHOUT_AT> = { url = "<REGISTRY_URL>", token = "$BUN_PUBLISH_AUTH_TOKEN" }
+```
+
+```powershell
+$env:BUN_PUBLISH_AUTH_TOKEN = "<BUN_PUBLISH_AUTH_TOKEN>"
+bun publish
+```
+
+### npm
+
+```powershell
+npm login --registry https://registry.npmjs.org/
+npm publish --registry https://registry.npmjs.org/ --access public
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@temir.ra/create-test115",
+  "version": "0.0.12",
+  "description": "",
+  "type": "module",
+  "exports": {
+    ".": {
+      "entrypoint": "./src/index.ts",
+      "browser": "./dist/index.bundle.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "bun-create": {
+    "preinstall": [
+      "mv README.md README-template.md",
+      "mv README.md.template README.md",
+      "mv CHANGELOG.md CHANGELOG-template.md",
+      "mv CHANGELOG.md.template CHANGELOG.md"
+    ]
+  },
+  "scripts": {
+    "clean": "rm -rf dist/",
+    "prebuild": "bun run scripts/buildinfo.ts",
+    "test": "bun test",
+    "build": "bun run build:lib && bun run build:cdn && bun run build:assets",
+    "build:lib": "tsc --project tsconfig.build.json",
+    "build:cdn": "bun run scripts/build-cdn.ts",
+    "build:assets": "echo 'no assets to build'",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run --watch src/dev.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}