# How to Configure CAD Viewer Backend Storage Options in text-to-cad

> Configure CAD Viewer backend storage options for text-to-cad. Choose between local filesystem and Vercel Blob using environment variables no code changes needed for seamless integration.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-29

---

**The CAD Viewer supports two backend storage modes—a local filesystem for development and Vercel Blob for production—selected through environment variables without modifying source code.**

The text-to-cad repository (`earthtojake/text-to-cad`) provides a CAD Viewer that decouples frontend browser state from backend asset storage. You can configure CAD Viewer backend storage options to target either a local directory for rapid development or a CDN-backed Vercel Blob store for production deployments. The architecture relies on a common backend interface defined in [`viewer/docs/backend.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/backend.md), enabling seamless switching between implementations by adjusting runtime configuration.

## Understanding the Backend Interface

Both storage backends implement an identical JavaScript contract consumed by the viewer. As documented in [`viewer/docs/backend.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/backend.md), every backend must expose an object containing:

```js
{
  kind,
  readCatalog({ rootDir, fileRef }),
  refreshCatalog({ rootDir, fileRef }),
  resolveFileAssetAccess({ fileRef, asset, catalog })
  // optional writable helpers…
}

```

The factory logic in `viewer/src/server/viewerEnv.mjs` reads environment variables at startup and instantiates the appropriate backend based on the `VIEWER_ASSET_BACKEND` value. This abstraction allows the viewer to remain agnostic of whether assets reside on local disk or remote blob storage.

## Local Filesystem Backend (Development)

For local development, the viewer can serve CAD assets directly from your machine's filesystem using the implementation in `viewer/src/server/localAssetBackend.mjs`.

Key behaviors of the local backend include:

- Scanning the root directory on each request and building an in-memory catalog dynamically
- Supporting read-only operations via `GET /__cad/*` routes
- Writing regenerated STEP/GLB artifacts back to the same source directory
- **Not** exposing a static [`catalog.json`](https://github.com/earthtojake/text-to-cad/blob/main/catalog.json) file (generated on-the-fly per request)

### Configuration and Usage

No environment variables are required for the local backend. Start the development server with the `--dir` flag:

```bash
npm --prefix viewer run dev -- --dir /absolute/path/to/models

```

The viewer will read all assets from the specified directory. If you omit `--dir`, it defaults to the directory where the server was started.

## Vercel Blob Backend (Production)

For production deployments, the viewer supports immutable, CDN-backed storage via Vercel Blob. The implementation in `viewer/src/server/vercelBlobAssetBackend.mjs` treats the Blob store as read-only, fetching [`catalog.json`](https://github.com/earthtojake/text-to-cad/blob/main/catalog.json) and assets from a public URL prefix.

### Required Environment Variables

Configure the Vercel Blob backend by setting these variables before starting the server:

| Variable | Description |
|----------|-------------|
| `VIEWER_ASSET_BACKEND` | Set to `vercel-blob` to activate the Blob backend. |
| `VIEWER_VERCEL_BLOB_PREFIX` | Public URL prefix of your Blob storage, e.g., `https://<store-id>.public.blob.vercel-storage.com/models2`. |
| `VIEWER_VERCEL_BLOB_READ_WRITE_TOKEN` | Required **only** for local upload scripts; unnecessary for read-only viewer deployments. |

### Deploying with Read-Only Access

To run the viewer against hosted Blob storage:

```bash
VIEWER_ASSET_BACKEND=vercel-blob \
VIEWER_VERCEL_BLOB_PREFIX=https://my-store.public.blob.vercel-storage.com/models2 \
npm --prefix viewer run serve

```

In this mode, the viewer fetches [`catalog.json`](https://github.com/earthtojake/text-to-cad/blob/main/catalog.json) from the Blob prefix and ignores local filesystem query parameters like `?dir=`.

## Publishing Assets to Vercel Blob

To populate your Blob storage, use the included upload script with a write token. This is typically run during CI/CD or locally when publishing new models:

```bash
VIEWER_VERCEL_BLOB_READ_WRITE_TOKEN=$MY_BLOB_TOKEN \
VIEWER_VERCEL_BLOB_PREFIX=models2 \
npm --prefix viewer run upload:blob -- models

```

The upload script supports additional options:

- ** `--skip-existing`** – Skips re-uploading assets that already exist in the Blob store
- ** `--fetch-missing-lfs`** – Fetches only required Git-LFS objects for new or changed files

The script respects `.vieweruploadignore` (git-ignore-style patterns) to exclude unwanted paths from publication.

## Backend Selection Reference

The following files handle the configuration logic:

- **`viewer/src/server/viewerEnv.mjs`** – Maps environment variables to backend factories and validates the active configuration.
- **`viewer/src/server/localAssetBackend.mjs`** – Local filesystem implementation; ideal for development workflows.
- **`viewer/src/server/vercelBlobAssetBackend.mjs`** – Vercel Blob adapter; used for production and CI/CD environments.
- **[`viewer/docs/backend.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/backend.md)** – Complete specification of the backend interface and supported routes.
- **[`viewer/docs/storage.md`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/docs/storage.md)** – Documentation for browser-side storage tiers (complementary to backend configuration).

## Summary

- **Use the local backend** (`npm --prefix viewer run dev -- --dir ./models`) for rapid iteration during development; requires no environment variables.
- **Switch to Vercel Blob** by setting `VIEWER_ASSET_BACKEND=vercel-blob` and supplying a `VIEWER_VERCEL_BLOB_PREFIX` URL for production deployments.
- **Upload assets** using `npm run upload:blob` with a `VIEWER_VERCEL_BLOB_READ_WRITE_TOKEN` to publish catalogs to hosted storage.
- **Maintain portability** by keeping backend-specific logic isolated to `viewerEnv.mjs`, ensuring the viewer core remains storage-agnostic.

## Frequently Asked Questions

### Do I need to modify source code to switch between backends?

No. The viewer selects backends strictly through environment variables defined in `viewer/src/server/viewerEnv.mjs`. Set `VIEWER_ASSET_BACKEND` to `vercel-blob` or leave it unset (defaulting to local) to change behavior without touching implementation files.

### Can I use the Vercel Blob backend without a write token?

Yes. The `VIEWER_VERCEL_BLOB_READ_WRITE_TOKEN` is only required for the upload script (`npm run upload:blob`). The viewer itself operates in read-only mode against public Blob URLs and does not need write credentials to serve assets.

### How does the local backend handle the catalog compared to Vercel Blob?

The local filesystem backend generates the catalog dynamically on each request by scanning the directory tree, whereas the Vercel Blob backend fetches a pre-generated [`catalog.json`](https://github.com/earthtojake/text-to-cad/blob/main/catalog.json) file from the Blob store. This distinction means the local backend reflects filesystem changes immediately, while the Blob backend requires re-uploading to update the catalog.

### What file patterns does the upload script ignore?

The upload script respects `.vieweruploadignore` in your project root, using standard git-ignore syntax to exclude paths from being published to Vercel Blob. This is useful for skipping source files, documentation, or temporary build artifacts that should not be served as CAD assets.