# artifacts-viewer

Monorepo for [`artifacts-viewer`](./packages/artifacts-viewer), a read-only React
repository viewer for [Cloudflare Artifacts](https://developers.cloudflare.com/artifacts/).

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

## Layout

```text
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+](https://viteplus.dev), 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

```bash
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.

```bash
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`.

```bash
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`](./PUBLISH.md) has the full procedure
and the failure modes worth knowing about.

## License

MIT