Skip to content

Commit d605785

Browse files
ThatGuySamThatGuySam
committed
docs(research): capture search migration findings
Save the Ubuntu 24 Stork migration notes and the Pagefind viability assessment so the production decision and source trail live in the repo.
1 parent 1c2ce65 commit d605785

2 files changed

Lines changed: 195 additions & 0 deletions

File tree

‎docs/research/netlify-ubuntu-24-stork-2026-03-15.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Netlify Ubuntu 24 Stork Migration
2+
3+
Date: 2026-03-15
4+
5+
## Scope
6+
7+
Investigate why `doesitarm` fails on Netlify's Noble/Ubuntu 24 image and
8+
identify whether the fix belongs in this repo or `../doesitarm-functions/`.
9+
10+
## Short Answer
11+
12+
The failing production build is blocked in the Stork setup stage, not in Astro
13+
or the companion functions repo.
14+
15+
The immediate break is that `doesitarm` downloads Stork's
16+
`stork-ubuntu-20-04` binary, which is linked against `libssl.so.1.1`. Netlify's
17+
Noble/Ubuntu 24 image no longer ships that library, so the binary exits before
18+
Astro starts building.
19+
20+
There is also a separate Node 22 regression in this repo: `isBrowserContext()`
21+
uses `navigator` to detect browsers, but Node 22 exposes a global
22+
`navigator`. That causes Node processes on macOS to be misdetected as browser
23+
contexts and pushes local Stork downloads onto the Linux binary path.
24+
25+
## What The Evidence Says
26+
27+
- Confirmed from the user-provided Netlify build log:
28+
`./stork-executable: error while loading shared libraries: libssl.so.1.1`
29+
- Confirmed from the latest Stork release metadata:
30+
`v1.6.0` ships both `stork-ubuntu-20-04` and `stork-ubuntu-22-04`.
31+
- Confirmed from local binary inspection:
32+
`stork-ubuntu-20-04` references `libssl.so.1.1` and `libcrypto.so.1.1`
33+
while `stork-ubuntu-22-04` references `libssl.so.3` and `libcrypto.so.3`.
34+
- Confirmed from Node 22 docs and local runtime checks:
35+
Node 22 exposes a global `navigator`, so `typeof navigator !== 'undefined'`
36+
is no longer a safe browser-only check.
37+
- Confirmed locally on 2026-03-15:
38+
`CI=1 mise exec node@22 -- pnpm run netlify-build` succeeds after switching
39+
the Stork target and fixing runtime detection.
40+
41+
## What Works
42+
43+
- Use Stork's `stork-ubuntu-22-04` binary on Linux/Netlify.
44+
- Use `stork-macos-13-arm` on Apple Silicon Macs.
45+
- Detect browser context with `window` and `document`, not `navigator`.
46+
- Keep the fix in `doesitarm`; `../doesitarm-functions/` is an external API
47+
dependency referenced via `VFUNCTIONS_URL` and `PUBLIC_API_DOMAIN`, not part
48+
of the failing Netlify build path.
49+
50+
## What To Avoid
51+
52+
- Do not keep using `stork-ubuntu-20-04` on Noble/Ubuntu 24.
53+
- Do not use the `stork-amazon-linux` artifact as a Netlify fallback; its
54+
binary references `libssl.so.10`, which is also not a fit for Ubuntu 24.
55+
- Do not use `navigator` as the only browser-runtime signal in Node 22+ code.
56+
57+
## Recommendation
58+
59+
Keep the Stork fix minimal and repo-local:
60+
61+
1. Detect the Stork binary target from `process.platform` and `process.arch`.
62+
2. Use `stork-ubuntu-22-04` for Linux builds.
63+
3. Use `stork-macos-13-arm` for Apple Silicon.
64+
4. Add tests for runtime detection and Stork target selection.
65+
5. Leave `../doesitarm-functions/` unchanged unless its own deployment starts
66+
failing independently.
67+
68+
## Source Links
69+
70+
- Stork latest release metadata:
71+
https://api.github.com/repos/jameslittle230/stork/releases/latest
72+
- Stork install docs:
73+
https://stork-search.net/docs/install
74+
- Stork CI/Netlify guide:
75+
https://stork-search.net/docs/stork-and-netlify
76+
- Node 22 globals docs:
77+
https://nodejs.org/dist/latest-v22.x/docs/api/globals.html

‎docs/research/pagefind-viability-2026-03-15.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Pagefind Viability For doesitarm
2+
3+
Date: 2026-03-15
4+
5+
## Scope
6+
7+
Investigate whether Pagefind is a good replacement for Stork in `doesitarm`,
8+
given the current Astro 2 + Netlify server build and the existing custom search
9+
pipeline.
10+
11+
## Short Answer
12+
13+
Pagefind is viable for this repo, but not as a drop-in replacement.
14+
15+
The lowest-risk production path today is to keep the Stork fix and ship it.
16+
If `doesitarm` later moves to Pagefind, the right migration path is a
17+
behind-feature-flag prototype using Pagefind's Node API with
18+
`addCustomRecord()`, not a simple `pagefind --site dist` crawl.
19+
20+
## What The Evidence Says
21+
22+
- Current repo shape:
23+
`doesitarm` builds with `output: "server"` in Astro and only prerenders a
24+
small subset of routes (`/`, `/categories`, `/games`). Most searchable
25+
listing pages are SSR routes, not static HTML files in `dist/`.
26+
- Current Stork shape:
27+
[helpers/stork/toml.js](/Users/athena/Code/doesitarm/helpers/stork/toml.js)
28+
generates a structured index from sitemap payloads, and
29+
[components/search-stork.vue](/Users/athena/Code/doesitarm/components/search-stork.vue)
30+
renders a custom search UI over those records.
31+
- Pagefind official docs:
32+
the Node API supports `addDirectory()`, `addHTMLFile()`, and
33+
`addCustomRecord()`. The docs explicitly describe `addCustomRecord()` as a
34+
way to build an index from non-HTML content.
35+
- Pagefind browser API:
36+
supports custom JS search UIs, per-result lazy loading with `result.data()`,
37+
excerpts, filters, and sorting.
38+
- Pagefind latest release:
39+
`v1.4.0`, published 2025-09-01.
40+
- Relevant GitHub issues:
41+
`#163` shows Astro + Netlify usage is workable but can need selector/root
42+
troubleshooting.
43+
`#198` and `#277` show demand for indexing non-HTML/custom data, which is now
44+
covered by the Node API docs.
45+
`#574` remains open for an `npx` wrapper failure on `ubuntu-latest`, which is
46+
a reason to prefer a pinned dependency and explicit integration over a casual
47+
CLI-only swap.
48+
49+
## What Works
50+
51+
- Pagefind can support this repo's filters and sorts.
52+
- Pagefind can support a custom UI instead of the stock widget.
53+
- Pagefind can index structured records directly with `addCustomRecord()`,
54+
which matches `doesitarm` better than crawling built HTML.
55+
- A feature-flagged migration is feasible:
56+
1. build Pagefind assets from the existing sitemap payload data
57+
2. expose them under `/pagefind/`
58+
3. add a Pagefind-backed client alongside the existing Stork component
59+
4. switch between them with a runtime/build flag
60+
61+
## What To Avoid
62+
63+
- Do not treat Pagefind as a trivial `postbuild` swap in this repo.
64+
A plain HTML crawl would miss most of the real searchable surface because the
65+
site is primarily SSR on Netlify.
66+
- Do not attempt the production migration by replacing Stork first and figuring
67+
out the UI later.
68+
- Do not rely on `npx pagefind` alone in CI without pinning and testing the
69+
binary/package path on the target image.
70+
71+
## Recommendation
72+
73+
For production now:
74+
75+
1. Ship the Stork Ubuntu 24 fix.
76+
2. Merge that branch to `master`.
77+
3. verify the Netlify deploy is green.
78+
79+
For a Pagefind migration later:
80+
81+
1. Add `pagefind` as a pinned dependency.
82+
2. Create a build script that maps the same sitemap payloads into
83+
`addCustomRecord()` calls.
84+
3. Write Pagefind output to `static/pagefind/` or `dist/pagefind/`.
85+
4. Add a feature flag that swaps the current Stork client for a Pagefind
86+
adapter in the search UI.
87+
5. Only remove Stork after the Pagefind path has parity on excerpts, filters,
88+
and result URLs.
89+
90+
Inference:
91+
Pagefind is probably the cleaner long-term search engine here, but because this
92+
repo already has a data-first indexing pipeline, the migration cost is more
93+
about adapter work than about search quality.
94+
95+
## Source Links
96+
97+
- Pagefind repo:
98+
https://github.com/Pagefind/pagefind
99+
- Pagefind latest release:
100+
https://github.com/Pagefind/pagefind/releases/tag/v1.4.0
101+
- Pagefind Node API docs:
102+
https://pagefind.app/docs/node-api/
103+
- Pagefind browser API docs:
104+
https://pagefind.app/docs/api/
105+
- Pagefind filtering docs:
106+
https://pagefind.app/docs/filtering/
107+
- Pagefind sorts docs:
108+
https://pagefind.app/docs/sorts/
109+
- Pagefind issue `#163`:
110+
https://github.com/Pagefind/pagefind/issues/163
111+
- Pagefind issue `#198`:
112+
https://github.com/Pagefind/pagefind/issues/198
113+
- Pagefind issue `#277`:
114+
https://github.com/Pagefind/pagefind/issues/277
115+
- Pagefind issue `#574`:
116+
https://github.com/Pagefind/pagefind/issues/574
117+
- HN result set for Pagefind launches:
118+
https://hn.algolia.com/?q=Pagefind

0 commit comments

Comments
 (0)