11# Publishing ` @phenotype/* ` npm packages
22
3- These packages are intended to publish to the ** GitHub Packages** npm registry
4- ( ` https://npm.pkg.github.com ` ) — not the public ` npmjs.com ` registry.
3+ These packages publish to ** GitHub Packages** ( ` https:// npm.pkg.github.com ` ),
4+ ** not** the public ` npmjs.com ` registry.
55
6- ** Current honesty (T0):** packages may not yet exist under
7- ` @phenotype ` on GitHub Packages. Until a successful publish lands, consumers
8- must use path or git dependencies (see the root README Install section and
9- each package README). Do not assume ` bun add @phenotype/... ` works.
6+ | Package | Path | Version |
7+ | ---| ---| ---|
8+ | ` @phenotype/journey-viewer ` | ` npm/journey-viewer ` | ` 0.1.0 ` |
9+ | ` @phenotype/journey-playwright ` | ` npm/journey-playwright ` | ` 0.1.0 ` |
10+ | ` @phenotype/playwright-record ` | ` npm/playwright-record ` | ` 0.1.0 ` |
11+
12+ ** Current honesty:** none of these names exist on ` npmjs.com ` . Until a
13+ successful GitHub Packages publish lands, consumers must use ** path** or
14+ ** git** dependencies (see the root README Install section and each package
15+ README). Do not assume ` bun add @phenotype/... ` resolves without a scoped
16+ ` .npmrc ` pointing at GitHub Packages ** and** a published version.
17+
18+ Out of scope for this cut: ` @phenotype/doc-embeds ` under ` remotion/doc-embeds/ `
19+ (separate Remotion pipeline; same registry when published later).
1020
1121## Prerequisites
1222
13- A GitHub personal access token (classic) with the following scopes:
23+ A GitHub personal access token (classic) with:
24+
25+ | Scope | Why |
26+ | ---| ---|
27+ | ` write:packages ` | publish |
28+ | ` read:packages ` | install on consumer side |
29+ | ` repo ` | link package to this private/public source repo |
30+
31+ Fine-grained PATs need Packages write on ` KooshaPari/phenotype-journeys ` .
32+
33+ Export the token (either name works for the helper script):
34+
35+ ``` bash
36+ export NODE_AUTH_TOKEN=ghp_... # preferred for npm
37+ # or
38+ export GITHUB_TOKEN=ghp_...
39+ ```
40+
41+ The ` gh ` CLI token often ** lacks** ` write:packages ` — verify scopes before
42+ publishing (` gh auth status ` ). Do not publish with an underscoped token.
43+
44+ ## Validate / dry-run (no registry write)
45+
46+ From the repo root (Node 18+; uses ` npm ` CLI):
47+
48+ ``` bash
49+ node npm/publish.mjs
50+ # equivalent:
51+ node npm/publish.mjs --dry-run
52+ ```
53+
54+ Or per package:
55+
56+ ``` bash
57+ cd npm/journey-viewer && npm run pack:check
58+ cd ../journey-playwright && npm run pack:check
59+ cd ../playwright-record && npm run pack:check
60+ ```
61+
62+ Task runner:
1463
15- - ` write:packages ` — publish
16- - ` read:packages ` — pull on consumer side
17- - ` repo ` — link to the source repo
64+ ``` bash
65+ task npm:pack
66+ ```
1867
19- Export as ` GITHUB_TOKEN ` (or set in a local ` .npmrc ` ).
68+ ## Publish to GitHub Packages
2069
21- ## Publish
70+ ### Option A — helper script (recommended)
2271
2372``` bash
24- # authenticate to GitHub Packages
25- cat > ~ /.npmrc-ghp << EOF
26- //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
73+ export NODE_AUTH_TOKEN=ghp_... # write:packages + repo
74+ node npm/publish.mjs --publish
75+ ```
76+
77+ ### Option B — npm CLI (exact commands)
78+
79+ ``` bash
80+ # one-time auth file (do not commit)
81+ cat > ~ /.npmrc-ghp << 'EOF '
2782@phenotype:registry=https://npm.pkg.github.com
83+ //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
2884EOF
85+ # expand token into the file if your shell does not expand inside single-quoted heredoc:
86+ # printf '@phenotype:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=%s\n' "$NODE_AUTH_TOKEN" > ~/.npmrc-ghp
2987
30- # publish journey-viewer
3188cd npm/journey-viewer
32- npm --userconfig=$HOME /.npmrc-ghp publish --access restricted
89+ npm --userconfig=" $HOME /.npmrc-ghp"
3390
34- # publish journey-playwright
3591cd ../journey-playwright
36- npm --userconfig=$HOME /.npmrc-ghp publish --access restricted
92+ npm --userconfig=" $HOME /.npmrc-ghp"
93+
94+ cd ../playwright-record
95+ npm --userconfig=" $HOME /.npmrc-ghp"
96+ ```
97+
98+ ### Option C — bun (publish still uses npm registry protocol)
99+
100+ ``` bash
101+ # bun respects .npmrc; use the same ~/.npmrc-ghp or project .npmrc
102+ cd npm/journey-viewer && bun publish --access restricted --registry https://npm.pkg.github.com
103+ cd ../journey-playwright && bun publish --access restricted --registry https://npm.pkg.github.com
104+ cd ../playwright-record && bun publish --access restricted --registry https://npm.pkg.github.com
37105```
38106
39- ## Fallback: tarball
107+ Prefer ** Option A or B** until bun’s GitHub Packages auth is verified in this
108+ environment.
109+
110+ ### Option D — GitHub Actions
111+
112+ Manual workflow: ** Publish npm (GitHub Packages)**
113+ (` .github/workflows/publish-npm.yml ` ), ` workflow_dispatch ` with
114+ ` dry_run=true ` by default. Set ` dry_run=false ` only when ready to write.
115+ Uses ` permissions: packages: write ` and ` GITHUB_TOKEN ` .
40116
41- If you cannot publish to the registry (token missing scopes, etc.), run:
117+ ## Fallback: local tarball
118+
119+ If the registry is unreachable (billing, missing scopes, etc.):
42120
43121``` bash
44- cd npm/journey-viewer && npm pack --pack-destination ../dist
45- cd ../journey-playwright && npm pack --pack-destination ../dist
122+ node npm/publish.mjs --pack
123+ # writes npm/dist/phenotype-*-0.1.0.tgz
46124```
47125
48- Consumers can then depend on the tarball directly :
126+ Consumer ` package.json ` :
49127
50128``` json
51129{
@@ -55,19 +133,31 @@ Consumers can then depend on the tarball directly:
55133}
56134```
57135
58- Current packed tarballs live in ` npm/dist/ ` .
136+ ` npm/dist/ ` is gitignored; regenerate with ` --pack ` as needed .
59137
60- ## Consuming (GitHub Packages )
138+ ## Consuming (after a successful publish )
61139
62- Create ` .npmrc ` in the consumer repo :
140+ Consumer repo ` .npmrc ` :
63141
64142```
65143@phenotype:registry=https://npm.pkg.github.com
66- //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN }
144+ //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN }
67145```
68146
69147Then:
70148
71149``` bash
72- bun add @phenotype/journey-viewer
150+ bun add @phenotype/journey-viewer@0.1.0
151+ bun add -d @phenotype/journey-playwright@0.1.0 @phenotype/playwright-record@0.1.0
152+ # or
153+ npm install @phenotype/journey-viewer@0.1.0 --registry=https://npm.pkg.github.com
73154```
155+
156+ Until publish succeeds, keep using path/git installs from the root README.
157+
158+ ## Checklist before first publish
159+
160+ - [ ] ` node npm/publish.mjs ` exits 0 (version ` 0.1.0 ` , registry, ` files ` , ` repository.directory ` )
161+ - [ ] Token has ` write:packages ` (not only ` repo ` / ` workflow ` )
162+ - [ ] No conflicting version already on GitHub Packages for each name
163+ - [ ] Prefer ` dry_run ` workflow run once before ` dry_run=false `
0 commit comments