How to Use the CAD Viewer in Text-to-CAD for 3D Previews: A Complete Guide

The CAD viewer in text-to-cad runs as a lightweight HTTP server that serves a React-based 3D interface; launch it with npm run serve, then open http://localhost:4178?dir=<path>&file=<model> to view interactive STEP or GLB files.

The earthtojake/text-to-cad repository includes a built-in CAD viewer that enables interactive 3D preview of generated models directly in your browser. This React-based viewer uses WebGL for rendering and provides orbit, pan, zoom, and exploded view controls for inspecting CAD geometry. Whether you are working with local STEP files or hosted assets on Vercel Blob, the viewer operates through a consistent HTTP interface that automatically handles asset resolution.

Building the Viewer Frontend

Before launching previews, you must generate the static assets that power the 3D interface.

Generating Static Assets

The viewer’s frontend is built using standard npm tooling. According to viewer/docs/backend.md#L94-L99, run the build command from the repository root:

npm run build

This command compiles the React application and outputs static files to viewer/dist, which the HTTP server will serve alongside your CAD models.

Starting the CAD Viewer Server

The viewer supports two operational modes: a local filesystem backend for development and a Vercel Blob backend for production. Both modes use the same HTTP interface and query parameter structure.

Development Mode with Local Filesystem

For local development, start the server using the built-in npm script. As implemented in viewer/src/server/localAssetBackend.mjs, this mode reads CAD files directly from your disk:

npm run serve

By default, the server binds to port 4178. If this port is unavailable, the server automatically increments the port number and prints the actual URL in the console output.

Production Mode with Vercel Blob

To serve models from a hosted Vercel Blob store, set the appropriate environment variables before starting the server. As documented in viewer/docs/backend.md#L49-L55:

export VIEWER_ASSET_BACKEND=vercel-blob
export VIEWER_VERCEL_BLOB_PREFIX=https://mystore.public.blob.vercel-storage.com/models
npm run serve

In this configuration, the viewer resolves ?dir= and ?file= parameters against the public Blob storage rather than the local filesystem, enabling read-only access to published model catalogs.

Skill Wrapper Launch Method

For reproducible launches within automation workflows, use the skill wrapper script referenced in skills/cad-viewer/SKILL.md (lines 64-71). This method explicitly configures the host, root directory, and automatic shutdown:

npm --prefix scripts/viewer run serve \
  -- --host 127.0.0.1 \
  --dir /home/user/models \
  --shutdown-after 12h \
  --json

When invoked with the --json flag, the server outputs a JSON line containing the accessible URL (e.g., {"url":"http://127.0.0.1:4178"}) before handling requests.

Accessing 3D Previews via URL Parameters

Once the server is running, construct URLs using two required query parameters to load specific models.

Required Query Parameters

The viewer recognizes two query parameters that work identically across both backend modes:

• ?dir=: The absolute path to the directory containing your CAD files. If omitted, it defaults to the --dir value passed at startup. When provided as a relative path, it resolves against the viewer’s launch directory.
• ?file=: The filename of the CAD model, specified as a path relative to the active ?dir= directory.

As specified in viewer/docs/backend.md#L56-L57, a complete preview URL follows this structure:

http://localhost:4178?dir=/absolute/path/to/models&file=example.step

Port Configuration and Auto-Increment

The server attempts to bind port 4178 by default. If this port is occupied, the system automatically selects the next available port and communicates the actual endpoint through the startup log or JSON output when using --json. This ensures collision-free operation when running multiple viewer instances or when port 4178 is reserved by another service.

Backend Architecture and Asset Resolution

The viewer’s modular backend architecture supports multiple storage strategies while presenting a unified interface.

Local Asset Backend: Implemented in viewer/src/server/localAssetBackend.mjs, this backend streams files directly from the host filesystem, making it ideal for iterative development and private model inspection.

Vercel Blob Integration: For sharing models publicly, the repository includes scripts/viewer/upload-viewer-models-catalog.sh, which automates the upload of model catalogs to Vercel Blob storage. Once uploaded, set VIEWER_ASSET_BACKEND=vercel-blob to switch the viewer to read-only mode against these hosted assets without modifying any client-side code.

Summary

• Build first: Run npm run build to generate the React frontend assets in viewer/dist.
• Launch the server: Use npm run serve for standard operation, or the skill wrapper (npm --prefix scripts/viewer run serve) for automated workflows with specific host and shutdown parameters.
• Construct URLs: Append ?dir=<absolute-path> and ?file=<relative-filename> to the server endpoint (default http://localhost:4178) to load specific STEP or GLB files.
• Switch backends: Set VIEWER_ASSET_BACKEND=vercel-blob and VIEWER_VERCEL_BLOB_PREFIX to serve production assets from cloud storage instead of the local filesystem.
• Port flexibility: The server defaults to port 4178 but automatically increments if unavailable, reporting the actual address via console output or JSON.

Frequently Asked Questions

What file formats does the text-to-cad viewer support?

The viewer supports standard CAD interchange formats including STEP (.step, .stp) and GLB (glTF Binary) files. The React-based WebGL renderer handles the geometry conversion and provides interactive controls for orbit, pan, zoom, and exploded views regardless of the source format.

How do I switch between local filesystem and Vercel Blob backends?

Set the VIEWER_ASSET_BACKEND environment variable to vercel-blob and define VIEWER_VERCEL_BLOB_PREFIX with your storage URL before running npm run serve. Without these variables, the server defaults to the local filesystem backend implemented in viewer/src/server/localAssetBackend.mjs.

Why does the viewer change ports from the default 4178?

If port 4178 is already in use by another process, the server automatically increments to the next available port to prevent binding conflicts. When launched with the --json flag, the server prints the actual URL in a JSON line ({"url":...}), ensuring you can always locate the correct endpoint.

Can I use the viewer without building the frontend first?

No. You must run npm run build at least once to generate the static assets in viewer/dist that the HTTP server serves. The server relies on these pre-built React components to render the 3D interface and WebGL canvas; attempting to start the server without building first will result in missing UI assets or 404 errors.

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