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

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, 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, every backend must expose an object containing:

{
  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 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:

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 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:

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 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:

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 – Complete specification of the backend interface and supported routes.
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}