@temir.ra/create-ts-lib 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Version 0
 
+## 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.

package/buildinfo.txt

@@ -1 +1 @@
-0.7.0+b45e7d0
+0.7.1+488a0be

package/package.json

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

package/template/CHANGELOG-template.md

@@ -0,0 +1,49 @@
+# Version 0
+
+## 0.4.1
+
+1. Cleaned up coding-specific aspects.
+2. Updated the description in `package.json`.
+
+## 0.4.0
+
+1. Updated `.gitignore`: added `buildinfo-template.txt`, `CHANGELOG-template.md`, `README-template.md`, `buildinfo.txt`, and `*.tsbuildinfo`; replaced nested `template/.gitignore` with `template/gitignore` to prevent template files from being excluded during distribution.
+2. Overhauled the generated `package.json`: added `keywords`, `repository`, and `devDependencies` fields; fixed recursive script execution; replaced propagating `clean` with `clean:dist` + `clean:tsbuildinfo` sub-scripts; removed `build` and workspace-propagating `tests`/`typecheck` (propagation is now opt-in, documented in the README); added `reinstall` script.
+3. Updated the generated `tsconfig.json`: removed `DOM` from `lib`; added `types: ["bun"]`.
+4. Improved CLI error message for missing package name argument.
+5. Overhauled `README.md`: rewritten intro, added `tsconfig.json` documentation section, updated `package.json` documentation, added Script Propagation section, added `create-doc` to the template family table; removed publishing section from `template/README.md`.
+6. Renamed `scripts/build-lib-bundle.ts` to `scripts/build-bundle.ts`; updated to produce both ESM and IIFE browser bundles; removed `tsconfig.build.json` and `build:lib` step; added build scripts to published `files`; set `private: false`.
+7. Updated from `@temir.ra/template@0.1.3` template.
+
+## 0.3.1
+
+1. Fixed create commands in the **Quick Start** section of the `README.md` to reflect the create-template conventions.
+2. Fixed published package contents.
+
+## 0.3.0
+
+1. Added `create-skill` template as part of the templates ecosystem.
+
+## 0.2.2
+
+1. Updated `README.md` to reflect the change in `create-hono-server@0.3.1` template.
+
+## 0.2.1
+
+1. Updated files from `ts-lib@0.6.3` template.
+
+## 0.2.0
+
+1. Removed **AI Assistant Context** section from the `README.md` files.
+2. Alligned `README.md` with the `ts-lib@0.6.2` template.
+3. Cleaned up **Publish** section in `README.md`.
+4. Rephrased the `README.md` to reflect that the generated package is workspace-aware but not necessarily a root package.
+5. Renamed the package from `create-monorepo` to `create-workspace`.
+
+## 0.1.1
+
+1. Fixed upstream repository URL in package.json.
+
+## 0.1.0
+
+1. First version of the template.

package/template/README-template.md

@@ -0,0 +1,453 @@
+# Introduction
+
+The base template of the family. Scaffolds a Bun package: `package.json`, TypeScript configuration, and conventions for testing, change management, and git versioning. Use it as-is, extend it into a monorepo, or choose a more specific template from the family for common upgrade paths.
+
+For some use cases a purpose-built template already exists and reduces the amount of manual adjustment needed. Use the table to decide whether to start here or with a more specific template.
+
+Templates in this family:
+
+| Template | Purpose |
+|---|---|
+| [`create-workspace`](#packagejson) | Base Bun package; root of the template family *(this template)* |
+| [`create-ts-lib`](#create-ts-lib) | TypeScript library with build pipeline, distributed via registry |
+| [`create-hono-server`](#create-hono-server) | Bun+Hono web server |
+| [`create-hono-spa`](#create-hono-spa) | SPA scaffold, pluggable into a Hono server as a sub-app |
+| [`create-skill`](#create-skill) | LLM skill package |
+| [`create-doc`](#create-doc) | Document as a collection of Markdown sections, compiled to PDF |
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Documentation](#documentation)
+    1. [`package.json`](#packagejson)
+    2. [`Script `scripts/build-bundle.ts`](#script-scriptsbuild-bundlets)
+    3. [`tsconfig.json`](#tsconfigjson)
+    4. [Workspaces](#workspaces)
+      1. [Script Propagation](#script-propagation)
+      2. [Cross-workspace Dependencies](#cross-workspace-dependencies)
+      3. [Scaffolding Patterns](#scaffolding-patterns)
+          1. [Library](#library)
+          2. [Server](#server)
+          3. [Server + SPA](#server--spa)
+          4. [Full-Stack with Shared Types](#full-stack-with-shared-types)
+          5. [Skill](#skill)
+3. [DevOps](#devops)
+    1. [Change Management](#change-management)
+    2. [Publish](#publish)
+
+# Quick Start
+
+```bash
+# placeholder:
+    # <TEMPLATE_PACKAGE: @temir.ra/create-workspace
+    # <TEMPLATE_NAME: @temir.ra/workspace
+    # <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-workspace" version
+bun create --no-install --no-git "@temir.ra/workspace<@_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/workspace" <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.
+
+## `package.json`
+
+See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
+
+```json
+{
+
+  "name": "",
+  "version": "0.0.0",
+
+  "description": "",
+  "author": "",
+  "license": "",
+
+  "keywords": [],
+
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+
+  // controls whether the package can be published to a registry
+  "private": true,
+
+  "scripts": {
+
+    // deletes node_modules and the lockfile, clears the Bun cache, then reinstalls
+    // useful for recovering from a corrupted node_modules or lockfile
+    "reinstall": "rm -rf node_modules && rm -f bun.lock && bun pm cache rm && bun install && bunx tsc --version",
+
+    // type-checks the project without emitting output
+    "typecheck": "tsc --noEmit",
+
+    // generates buildinfo.txt (for use in lifecycle hooks and CI pipelines)
+    "buildinfo": "bun run scripts/buildinfo.ts"
+
+  },
+
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^6.0.2"
+  }
+
+}
+```
+
+## Script `scripts/buildinfo.ts`
+
+Writes `buildinfo.txt` with the package version from `package.json`, appending the git short hash as semver build metadata (`<version>+<hash>`). If the version already contains `+`, the hash is appended as `<version>+<existing>.<hash>` instead. Falls back to the bare version when git is unavailable.
+
+## `tsconfig.json`
+
+See the TypeScript documentation on [tsconfig.json](https://www.typescriptlang.org/tsconfig) for detailed explanations of all options.
+
+```json
+{
+
+  "compilerOptions": {
+
+    // ECMAScript version of emitted output; ESNext targets the latest JS version supported by the TypeScript compiler
+    // if the package must support older runtimes or browsers, pin to a specific year (e.g. "ES2022", "ES2024")
+    "target": "ESNext",
+
+    // output module format; ESNext passes ES module syntax through unchanged
+    // ES module syntax: import/export statements (as opposed to CommonJS require()/module.exports)
+    "module": "ESNext",
+
+    // type definitions for built-in APIs
+    "lib": [
+      "ESNext"  // standard JavaScript runtime APIs
+    ],
+
+    // module resolution strategy; bundler mode allows omitting file extensions in imports
+    "moduleResolution": "bundler",
+
+    // enables all strict type-checking options
+    "strict": true,
+
+    // enforces import type for type-only imports; emitted module syntax matches source exactly
+    "verbatimModuleSyntax": true,
+
+    // array indexing and index signature access returns T | undefined instead of T
+    "noUncheckedIndexedAccess": true,
+
+    // distinguishes absent optional properties from those explicitly set to undefined
+    "exactOptionalPropertyTypes": true,
+
+    // requires explicit override keyword when overriding base class methods
+    "noImplicitOverride": true,
+
+    // requires explicit types on all exported declarations; enables parallel .d.ts generation by external tools
+    "isolatedDeclarations": true,
+
+    // allows default imports from CommonJS modules
+    "esModuleInterop": true,
+
+    // enables project references and incremental builds via *.tsbuildinfo
+    "composite": true,
+
+    // do not type-check `.d.ts` files in `node_modules/`
+    "skipLibCheck": true,
+
+    // TS6 defaults types to [] - @types/* packages must be listed explicitly
+    "types": ["bun"],
+
+    // enforce consistent casing across import statements
+    "forceConsistentCasingInFileNames": true,
+
+    // allows importing JSON files as typed modules
+    "resolveJsonModule": true
+
+  },
+
+  // files matched by include are type-checked and visible to the IDE (IntelliSense, go-to-definition, etc.)
+  "include": [
+    "scripts/**/*.ts"
+  ],
+  // files matched by exclude are hidden from the IDE and excluded from type-checking
+  "exclude": [
+    "node_modules"
+  ]
+
+}
+```
+
+## Workspaces
+
+To extend the package into a monorepo, add a `workspaces` field to `package.json` and run `bun install`:
+
+```json
+{
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+The execution environment installs all workspace dependencies into a single shared `node_modules/` at the root and symlinks each workspace package by its `name` field. Cross-workspace imports resolve by package name without path aliases or module mapping.
+
+```
+<NEW_PACKAGE>/
+├── package.json          ← root
+└── packages/
+    ├── pkg-a/
+    │   ├── package.json
+    │   └── ...
+    └── pkg-b/
+        ├── package.json
+        └── ...
+```
+
+### Script Propagation
+
+Append `&& bun run --filter './*' <script>` to any script to propagate the call to all workspace packages:
+
+```json
+{
+  "scripts": {
+    "clean:dist": "rm -rf dist/ && bun run --filter './*' clean:dist",
+    "clean:tsbuildinfo": "rm -f *.tsbuildinfo && bun run --filter './*' clean:tsbuildinfo",
+    "tests": "bun test && bun run --filter './*' tests",
+    "typecheck": "bun run --filter './*' typecheck"
+  }
+}
+```
+
+`./*` targets all direct workspace packages. Replace with a more specific glob to limit propagation to a subset.
+
+By default packages are run in sequence. Add `--parallel` to run them concurrently, or `--sequential` to make it explicit:
+
+```bash
+bun run --filter './*' --parallel typecheck
+bun run --filter './*' --sequential clean
+```
+
+### Cross-workspace Dependencies
+
+To use one workspace package from another, declare it as a dependency using the `workspace:` protocol:
+
+```json
+// packages/pkg-a/package.json
+{
+  "dependencies": {
+
+    // workspace: resolves to the local package instead of fetching from a registry;
+    // workspace:* tracks the exact local version;
+    // workspace:^ is replaced by ^version on publish, tracking the semver range in the registry
+    "@scope/pkg-b": "workspace:*"
+
+  }
+}
+```
+
+Run `bun install` after adding the entry. The execution environment creates the symlink in `node_modules/` so imports resolve by package name at runtime and at the type level - no path alias or `paths` mapping required.
+
+### Scaffolding Patterns
+
+Scaffold the package first, add `workspaces` to `package.json`, then scaffold workspace packages inside it. After scaffolding each workspace package, update its `package.json` with the correct `name`, `version`, `description`, `author`, `license`, and `repository` fields. To wire cross-workspace dependencies, add the `workspace:*` entry to the consuming package's `package.json` and run `bun install` from the root.
+
+#### Library
+
+```
+<NEW_PACKAGE>/
+└── packages/
+    └── my-lib/        ← create-ts-lib
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <NEW_PACKAGE>
+cd <NEW_PACKAGE>
+bun create --no-install --no-git "@temir.ra/ts-lib" packages/my-lib
+bun install
+```
+
+##### `create-ts-lib`
+
+Starting point for any package distributed via a registry. See the full documentation at [`@temir.ra/create-ts-lib`](https://www.npmjs.com/package/@temir.ra/create-ts-lib).
+
+- Dual `tsconfig`: `tsconfig.json` (dev, `bundler` resolution, includes `tests/` + `scripts/`) and `tsconfig.build.json` (prod, `nodenext`, `src/` only, emits JS + `.d.ts`)
+- `exports` conditions: `entrypoint` (custom, source entry for the bundle script), `types`, `browser` (bundled output), `import` (compiled ESM)
+- `imports` field: `#src/*.js` → `./src/*.ts` - runtime alias for `dev.ts`, `tests/`, `scripts/` only
+- Build metadata: `scripts/buildinfo.ts` generates `buildinfo.txt` (version + git hash) as a `prebuild` hook
+- Bundle script: `scripts/build-lib-bundle.ts` bundles via Bun; supports CDN specifier rewriting via `cdn-rewrite-map.json`
+- Asset resolution contract: assets under `assets/@scope/lib-name/`, accessed via `import.meta.url` + `fetch()`
+- Optional CLI entry point via `bin` field and `build:cli-bundle` script
+
+#### Server
+
+```
+<NEW_PACKAGE>/
+└── packages/
+    └── server/        ← create-hono-server
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <NEW_PACKAGE>
+cd <NEW_PACKAGE>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun install
+```
+
+##### `create-hono-server`
+
+Starting point for any HTTP backend. See the full documentation at [`@temir.ra/create-hono-server`](https://www.npmjs.com/package/@temir.ra/create-hono-server).
+
+- `createAppHost(options)` - configures and returns a `Hono<AppEnv>` instance
+- Built-in middleware pipeline: `Logging`, `requestId`, `RequestLogger`, `compress`, `secureHeaders`
+- Built-in endpoints: `/health`, `/buildinfo`, OpenAPI spec, Scalar UI
+- `endpointGroups` - mounts additional `Hono` sub-apps; integration point for SPA packages
+- `AppEnv` - exported, extensible context type; extend it to carry custom variables through the context
+- `startServerHost(options)` - wraps `Bun.serve()`, graceful shutdown on `SIGINT`/`SIGTERM`
+
+#### Server + SPA
+
+```
+<NEW_PACKAGE>/
+└── packages/
+    ├── server/        ← create-hono-server
+    └── spa/           ← create-hono-spa
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <NEW_PACKAGE>
+cd <NEW_PACKAGE>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun create --no-install --no-git "@temir.ra/hono-spa" packages/spa
+bun install
+```
+
+Add the SPA as a dependency of the server, then reinstall:
+
+```json
+// packages/server/package.json
+{
+  "dependencies": {
+    "@scope/spa": "workspace:*"
+  }
+}
+```
+
+```bash
+bun install
+```
+
+##### `create-hono-spa`
+
+Starting point for a frontend SPA distributed as a Hono sub-app library. See the full documentation at [`@temir.ra/create-hono-spa`](https://www.npmjs.com/package/@temir.ra/create-hono-spa).
+
+- `createSpa(options)` - returns a `Hono` sub-app serving the SPA shell
+- `/app/*` wildcard handles client-side routing; `<base href>` patched at request time from `basePath` and `path`
+- Assets resolved via `import.meta.url`; no file copying or static serving config needed on the consuming server
+- PWA scaffold in `assets/`: `index.html`, `favicon.svg`, `manifest.webmanifest`, screenshots
+- Distributed as a library (`exports` + `dist/` + `assets/`); consumed via `workspace:*` in the server
+
+#### Full-Stack with Shared Types
+
+```
+<NEW_PACKAGE>/
+└── packages/
+    ├── server/        ← create-hono-server
+    ├── spa/           ← create-hono-spa
+    └── types/         ← create-ts-lib
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <NEW_PACKAGE>
+cd <NEW_PACKAGE>
+bun create --no-install --no-git "@temir.ra/hono-server" packages/server
+bun create --no-install --no-git "@temir.ra/hono-spa" packages/spa
+bun create --no-install --no-git "@temir.ra/ts-lib" packages/types
+bun install
+```
+
+Add the types package as a dependency of both the server and the SPA, then reinstall:
+
+```json
+// packages/server/package.json  and  packages/spa/package.json
+{
+  "dependencies": {
+    "@scope/types": "workspace:*"
+  }
+}
+```
+
+```bash
+bun install
+```
+
+#### Skill
+
+```
+<NEW_PACKAGE>/
+└── packages/
+    └── my-skill/      ← create-skill
+```
+
+```bash
+bun create --no-install --no-git "@temir.ra/create-workspace" <NEW_PACKAGE>
+cd <NEW_PACKAGE>
+bun create --no-install --no-git "@temir.ra/skill" packages/my-skill
+bun install
+```
+
+##### `create-skill`
+
+Starting point for any LLM skill package. See the full documentation at [`@temir.ra/create-skill`](https://www.npmjs.com/package/@temir.ra/create-skill).
+
+- `skill/skill.json` — the skill definition: `frontmatter` (slug, description) and `body` (name, purpose, activation conditions, instructions, examples, sections)
+- `skill/` — typed schema, render helpers, and companion files (`assets/`, `references/`)
+- `scripts/` — one build script per target platform; ships builders for Claude and OpenCode
+- `dist/` — generated artifacts, one subdirectory per platform; deploy by copying `dist/<platform>/<slug>/` into the target AI tool's skill directory
+
+# DevOps
+
+```bash
+bun install
+
+bun run clean
+bun run build
+bun run tests
+
+bun run dev
+
+# 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

@@ -0,0 +1 @@
+0.4.1+f472194

package/template/gitignore

@@ -1,7 +1,7 @@
 node_modules
 buildinfo.txt
-*.tsbuildinfo
 buildinfo-template.txt
 CHANGELOG-template.md
 README-template.md
+*.tsbuildinfo
 dist

package/template/package.json

@@ -28,18 +28,18 @@
     "scripts/buildinfo.ts",
     "scripts/build-bundle.ts",
     "scripts/cdn-rewrite-map.json",
-    "dist",
     "CHANGELOG.md",
-    "buildinfo.txt"
+    "buildinfo.txt",
+    "dist"
   ],
   "scripts": {
+    "reinstall": "rm -rf node_modules && rm -f bun.lock && bun pm cache rm && bun install && bunx tsc --version",
+    "typecheck": "tsc --noEmit",
+    "buildinfo": "bun run scripts/buildinfo.ts",
     "clean:dist": "rm -rf dist/",
     "clean:tsbuildinfo": "rm -f *.tsbuildinfo || true",
     "clean": "bun run clean:dist && bun run clean:tsbuildinfo",
-    "buildinfo": "bun run scripts/buildinfo.ts",
     "tests": "bun test",
-    "typecheck": "tsc --noEmit",
-    "reinstall": "rm -rf node_modules && rm -f bun.lock && bun pm cache rm && bun install && bunx tsc --version",
     "prebuild": "bun run buildinfo",
     "build": "bun run build:bundle",
     "build:bundle": "bun run scripts/build-bundle.ts"

package/template/tsconfig.json

@@ -1,38 +1,38 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "lib": [
-      "ESNext"
-    ],
-    "moduleResolution": "bundler",
-    "strict": true,
-    "verbatimModuleSyntax": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "noImplicitOverride": true,
-    "isolatedDeclarations": true,
-    "esModuleInterop": true,
-    "composite": true,
-    "skipLibCheck": true,
-    "types": [
-      "bun"
-    ],
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true,
-    "emitDeclarationOnly": true,
-    "outDir": "./dist"
-  },
-  "include": [
-    "tests/**/*.ts",
-    "scripts/**/*.ts",
-    "scripts/**/*.json",
-    "src/**/*.ts"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": [
+      "ESNext"
+    ],
+    "moduleResolution": "bundler",
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "isolatedDeclarations": true,
+    "esModuleInterop": true,
+    "composite": true,
+    "skipLibCheck": true,
+    "types": [
+      "bun"
+    ],
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist"
+  },
+  "include": [
+    "scripts/**/*.ts",
+    "scripts/**/*.json",
+    "src/**/*.ts",
+    "tests/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
 }