artifacts-viewer

Monorepo for artifacts-viewer, a read-only React repository viewer for Cloudflare Artifacts.

For package documentation — installation, API reference, styling, theming — see packages/artifacts-viewer/README.md. For the release procedure, see PUBLISH.md.

Layout

apps/example                 Cloudflare Workers + React app that consumes the package
packages/artifacts-viewer    The published npm package

The package ships four JavaScript entry points, one CSS export, and package metadata, each with a deliberate boundary:

Entry point	Contains	Must not import
artifacts-viewer	routeArtifactRequest, the server-side read-only proxy	React
artifacts-viewer/server/cache	Workers Cache API and KV adapters	React
artifacts-viewer/client	createArtifactsClient, framework-independent	React, Worker globals
artifacts-viewer/react	Hooks and components	The server router
artifacts-viewer/styles.css	Structural CSS only	—

Platform-neutral code shared by both sides (wire types, path helpers, blob classification) lives in packages/artifacts-viewer/src/shared/. The entry points are designed to preserve those boundaries: the server and client builds do not import React, and the React build does not import the server router.

Toolchain

This workspace uses Vite+, which wraps runtime management, package management, and frontend tooling behind a single vp CLI. Run vp help for the command list. Docs are vendored at node_modules/vite-plus/docs.

Dependency versions are centralised in the catalog: block of pnpm-workspace.yaml. Add a version there and reference it as "catalog:" from a package rather than pinning per package.

Development

vp install          # install; run after pulling
vp run dev          # start apps/example with source-level library HMR
vp run ready        # vp check && vp run -r build — the CI gate
vp run -r build     # build every workspace project

There is no test suite. vp check covers formatting, linting, and type checking across all projects.

Running the example app

The example needs credentials for a real Artifacts namespace. The API token lives only in the Worker; the browser never sees it.

cd apps/example
cp .dev.vars.example .dev.vars   # then fill in the three values

wrangler types reads .dev.vars to generate Env, so rerun vp run cf-typegen from apps/example after adding or renaming a variable.

apps/example/wrangler.jsonc sets assets.run_worker_first: ["/api/*"]. Without it, not_found_handling: "single-page-application" would serve index.html for API routes and the Worker would never run.

Releases

Versions and changelogs are generated by pnpm's native release tooling; never hand-edit version or CHANGELOG.md.

pnpm change         # record a change intent, committed with the code
pnpm version -r     # consume intents: bump, write changelogs, update the ledger

Publishing runs on GitHub Actions via npm OIDC trusted publishing, triggered by a published GitHub Release whose tag matches v<version>. No npm token exists anywhere in the repository. PUBLISH.md has the full procedure and the failure modes worth knowing about.