@doikayt/typescript-build-config 0.1.27 → 0.1.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +53 -31
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,6 +6,10 @@ Shared build configuration presets for TypeScript-based projects.
6
6
  - [@doikayt/typescript-build-config](#doikayttypescript-build-config)
7
7
  - [Purpose](#purpose)
8
8
  - [Quick start](#quick-start)
9
+ - [1. One-time machine setup (once per machine)](#1-one-time-machine-setup-once-per-machine)
10
+ - [2. Create a new project (repeatable)](#2-create-a-new-project-repeatable)
11
+ - [dk-scaffold](#dk-scaffold)
12
+ - [Run dk-scaffold's steps individually](#run-dk-scaffolds-steps-individually)
9
13
  - [Trying it out](#trying-it-out)
10
14
  - [Design Goals](#design-goals)
11
15
  - [What each component is for](#what-each-component-is-for)
@@ -46,34 +50,44 @@ via the pipeline files it installs into each consumer repo and the canonical rel
46
50
  These steps set up — in a fresh "new-developer" environment — a local git repo
47
51
  with a skeleton demo app plus all the standard Doikayt build configuration:
48
52
  tooling that auto-documents the code in the repo and lets it be pushed to
49
- GitHub, built, and (for a library) published to npm. Steps are minimal here —
50
- each links to the section that explains _what_ and _why_.
53
+ GitHub, built on GitHub's CI servers, and (for a library) published to npm. Steps
54
+ are minimal here — each links to the section that explains _what_ and _why_.
51
55
 
52
- **1. One-time machine setup — once per machine.** Clone this base repo and
53
- install the shared team [shell aliases](#team-shell-aliases). This only sets up
54
- the aliases (`dk-scaffold`, `mkrepo`); it does **not** configure any project:
56
+ ### 1. One-time machine setup (once per machine)
57
+
58
+ Clone this base repo and install the shared team
59
+ [shell aliases](#team-shell-aliases). This only sets up the aliases
60
+ (`dk-scaffold`, `mkrepo`); it does **not** configure any project:
55
61
 
56
62
  ```bash
57
- git clone git@github.com:doikayt/typescript-build-config.git
63
+ git clone https://github.com/doikayt/typescript-build-config.git # HTTPS: no SSH key needed
58
64
  cd typescript-build-config
59
65
  ./assets/shell/install.sh # adds `source assets/shell/aliases.sh` to your rc (idempotent)
60
66
  exec $SHELL # reload
61
67
  ```
62
68
 
63
- **2. Create a new project — once per project.** The two paths below are
64
- **alternatives that reach the same result** — a project wired to this base
65
- package. `dk-scaffold` is the one-command wrapper that *also* creates the GitHub
66
- repo and pushes it; the hand-run steps are what it runs under the hood. It
67
- scaffolds build config + a runnable demo — choose `lib` (published) or `app`
68
- (private, the default); see [library vs app](#usage) and
69
+ ### 2. Create a new project (repeatable)
70
+
71
+ The two paths below are **alternatives that reach the same result** — a project
72
+ wired to this base package.
73
+
74
+ #### dk-scaffold
75
+
76
+ `dk-scaffold` is the one-command wrapper that also (optionally) creates the
77
+ GitHub repo and pushes it. Just run it with a first argument naming your project
78
+ and a second indicating `lib` (a published library) or `app` (a standalone
79
+ app/utility, the default) — see [library vs app](#usage) and
69
80
  [Packaging concepts](docs/packaging-concepts.md):
70
81
 
71
82
  ```bash
72
83
  dk-scaffold my-project lib
73
84
  ```
74
85
 
75
- Or do it by hand / in an **existing** project — the same steps `dk-scaffold`
76
- runs ([Installation](#installation) and [Usage](#usage) explain each):
86
+ #### Run dk-scaffold's steps individually
87
+
88
+ The steps below mirror the work `dk-scaffold` does under the hood — either for a
89
+ brand-new project or to adopt Doikayt standard build config into an existing one.
90
+ ([Installation](#installation) and [Usage](#usage) explain each in detail.)
77
91
 
78
92
  ```bash
79
93
  npx @doikayt/typescript-build-config new # npm init -y + @doikayt scope
@@ -84,39 +98,47 @@ npm install # fetch declared devDe
84
98
 
85
99
  ### Trying it out
86
100
 
87
- One wrapper, three levels — each adds one thing you bring and one thing you see.
88
- Each scaffolds a throwaway **app** (nothing publishes) unless noted. Do the
89
- one-time [Quick start step 1](#quick-start) first so `dk-scaffold` is on your
90
- PATH.
101
+ `dk-scaffold` does a lot under the hood, so the best way to get familiar with it
102
+ is to run it at the three levels it supports — each requiring a little more setup
103
+ than the last, and revealing a little more of the process. Each level scaffolds a
104
+ throwaway **app** (nothing publishes) unless noted. Do the one-time
105
+ [machine setup](#1-one-time-machine-setup-once-per-machine) first so `dk-scaffold`
106
+ is on your PATH.
91
107
 
92
- **Level 0 — local, no accounts.** Scaffold and run the same gate CI runs — no
93
- GitHub repo, no push:
108
+ **Level 0 — local (no external GitHub/npm accounts needed).** Scaffold and run
109
+ the same gate CI runs — no GitHub repo, no push:
94
110
 
95
111
  ```bash
96
112
  dk-scaffold my-demo --local
97
113
  ```
98
114
 
99
- Under the hood it runs `init` (demo=yes, app, no Playwright) then `npm run ci`.
115
+ That single command runs `init` (demo=yes, app, no Playwright) then `npm run ci`.
100
116
  You'll see the vitest demo tests pass, `npm run build` emit `dist/` + type
101
117
  declarations, and `update-all-format` fill the README's TOC + UML markers
102
118
  (mermaid **source** — rendered at Level 1). `npm publish --dry-run` **refuses** —
103
119
  proof the app archetype never publishes.
104
120
 
105
- **Level 1 — push to your own GitHub.** Add a GitHub account and `gh`
106
- (`gh auth login`). Point the wrapper at your account and drop `--local`:
121
+ **Level 1 — push to your own GitHub.** Bring a GitHub account and the `gh` CLI.
122
+ Sign in, point the wrapper at your account, and drop `--local`:
107
123
 
108
124
  ```bash
109
- export DOIKAYT_ORG=<your-github-username> # target owner for the repo
125
+ gh auth login # one-time: sign in to GitHub
126
+ export DOIKAYT_ORG=<your-github-username> # target owner for the repo
110
127
  dk-scaffold my-demo # app (private) — no npm creds
111
128
  ```
112
129
 
113
- It creates the repo and pushes. On GitHub you'll see the **mermaid diagrams
114
- rendered** and the **CI job go green**. Push a follow-up **`feat:`** commit and
115
- the **release job** version-bumps + tags — nothing published (app). (The initial
116
- `chore: scaffold` push releases nothing; `feat:` / `fix:` triggers it.)
117
-
118
- **Level 2 — publish to your own npm.** Scaffold a `lib` and bring your own npm
119
- scope + `NPM` secret to watch `changeset publish` ship a real package. Full
130
+ Now it creates the repo and pushes — and you see what Level 0 couldn't: the
131
+ **mermaid diagrams rendered** (example
132
+ [here](https://github.com/doikayt/build-tools/blob/main/javascript/tooling-core/README.md#package-structure))
133
+ and the **CI job go green** in Actions (example:
134
+ [this project's runs](https://github.com/doikayt/typescript-build-config/actions)).
135
+ Push a follow-up **`feat:`** commit and the **release job** version-bumps + tags —
136
+ nothing published (app). (The initial `chore: scaffold` push releases nothing;
137
+ `feat:` / `fix:` triggers it.)
138
+
139
+ **Level 2 — publish to your own npm.** The last rung swaps the app for a `lib`
140
+ and adds your own npm scope + `NPM` secret — then you see the one thing the other
141
+ levels can't: `changeset publish` shipping a real, dist-only package. Full
120
142
  procedure: [docs/verification-runbook.md](docs/verification-runbook.md);
121
143
  non-`@doikayt`-scope setup:
122
144
  [docs/verification-byo-prerequisites.md](docs/verification-byo-prerequisites.md).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@doikayt/typescript-build-config",
3
- "version": "0.1.27",
3
+ "version": "0.1.28",
4
4
  "description": "Shared build configuration for TypeScript projects — ESLint, Prettier, tsconfig, and Playwright presets",
5
5
  "_comments": {
6
6
  "exports": "This block lists the config files that will be extended by files in in src/toplevel - which are copied to consuming project root folder. An example: eslint.config.js imports from '@doikayt/typescript-build-config/eslint'.",