feat: show nearbuilders.org builders and projects on community pages by adenarc · Pull Request #452 · NEARBuilders/citynode.app

adenarc · 2026-10-26T21:56:55Z

Closes #451, part of NEARBuilders/nearbuilders.org#285

Adds a "Builders and projects" section to the public community page (/n/$slug), read from nearbuilders.org.

The API builds the community path from the node and its parents (illinois/chicago, or illinois for a top-level one) and reads /v1/builders?cityNode= and /v1/projects?cityNode= server-side (new public getCommunityBuilders).
Only items whose cityNode matches the path are kept. Production nearbuilders.org ignores the param today and returns everything, so this keeps the section on the empty state until feat: tag builders and projects with their citynode.app community nearbuilders.org#301 ships.
If nearbuilders.org is down or slow (5s timeout), the section shows a quiet "couldn't load" note and the page still renders. Good results are cached for 2 minutes, the last good result is served for up to an hour during an outage, and failures back off for 30s.
Shows up to 6 builders (name, avatar from their NEAR profile, account) and 6 projects (title, short description, logo), each linking to its nearbuilders.org page, plus "See all on NEAR Builders" when there are more. Empty state links to nearbuilders.org/join.
Base URL is the nearbuildersUrl API variable, default https://nearbuilders.org.
Strings in en/es/fr/zh. Read-only, no auth changes.

No changeset: main no longer has a .changeset folder.

Tested

pnpm run typecheck, pnpm run lint, pnpm run test pass. New API integration tests (nested path, top-level path with the filter ignored, nearbuilders down, unknown node) and UI tests (list + links, empty state, down state), all with made-up data.
Locally in the browser, with a stub of the two nearbuilders endpoints serving made-up builders/projects and three made-up communities in the dev DB: nested community list, empty state, nearbuilders-down state, signed out at desktop and 375px, and signed in. No console errors from this change.
Against live nearbuilders.org (no stub): the API returns ok with no items in ~1s, and the page shows the empty state, signed out, no console errors.
Review follow-ups: outage backoff (30s), shared in-flight request, stale fallback up to an hour, https-only logos, and no path when a community's parent chain is broken. All have unit tests.

Not tested

Against a real nearbuilders.org with tags (fix(auth): swap wallet connector to gas-key-capable @hot-labs fork, drop fastnear patch #301 isn't deployed yet).
"See all" goes to the full nearbuilders.org builders/projects list, since those pages don't filter by community yet.

Screenshots

Adds a Builders and projects section to the public community page. The API builds the community path from the node and its parents, reads nearbuilders.org /v1/builders and /v1/projects with ?cityNode=, keeps only items tagged with that path, and reports nearbuilders.org as unavailable instead of failing. The base URL is the nearbuildersUrl API variable (default https://nearbuilders.org). Closes #451

multi-review · 2026-10-26T21:58:04Z

Multi Review · `ea7b7f6`

The PR adds a public getCommunityBuilders procedure. It builds the community's slug path from the node's parent chain, then fetches builders and projects from nearbuilders.org server-side with a timeout, a TTL cache, a stale fallback, a failure backoff and shared in-flight requests. The UI shows them in a new section on /n/$slug. The change is read-only, failures degrade to an 'unavailable' state, and I found no defects. The earlier finding about missing negative caching no longer applies: the 30s backoff and shared in-flight requests fix it.

No new issues found · 1 resolved

What was checked (10 areas)

getCommunityBuilders handler in api/src/index.ts: path resolution via nodes.getById, null on unknown node or broken chain, Effect.promise around forPath (forPath catches every load error, so it never rejects)
communityPath: cycle and depth guards, lowercasing, root-to-leaf join
createNearbuilders.forPath: fresh cache, stale fallback, failure backoff, pending dedupe, eviction, and how now and cached are captured
matchedPage: schema parse failure goes to the unavailable path; filteredByServer total logic with empty or untagged pages
request(): baseUrl origin normalization, timeout, non-OK handling
Public exposure: getNode is already public, so returning slug paths leaks nothing new
NearbuildersSection UI: loading, unavailable/null, empty and list states; See-all condition; BuilderCard near-profile query matches the existing use-identity and $accountId pattern
nearbuildersUrl config variable and bos.app.ts default
i18n keys used in the component exist in all four locales
UI and API tests match the contract

Resolved since the last review

✅ ~~No negative caching: while nearbuilders.org is down or slow, every community page view waits up to 5s and makes 2 new outbound requests~~ api/src/services/nearbuilders.ts

_{Comment @multi-review to re-review new commits, or @multi-review full for a full review.}

Return no path when a community's ancestor chain doesn't reach a root, keep only https project logos, count totals from raw tags, share one in-flight request per path, prune stale cache entries after an hour, and read the join link from the API base URL.

Use Effect.fn for communityPath, derive the result type from the contract schema, validate nearbuildersUrl in the config schema instead of falling back silently, and tidy names and imports in the section.

…ilders # Conflicts: # api/src/index.ts # bos.app.ts

…ilders # Conflicts: # api/src/discovery-contract.ts

…ilders # Conflicts: # api/src/index.ts # ui/src/routes/_public/n/-node-page.test.tsx

…ilders # Conflicts: # ui/src/routes/_public/n/-node-page.test.tsx

…ilders

…ilders # Conflicts: # ui/src/routes/_public/n/$slug.tsx

itexpert120

LGTM

itexpert120 · 2026-10-31T02:42:35Z

@multi-review full

adenarc · 2026-11-02T00:03:55Z

@elliotBraem approved by @itexpert120, ok to merge when you get a chance