Use Middleware

Add caching, coordinate transforms, and edge detection to your kernel pipeline. Middleware intercepts kernel operations and transforms results without modifying kernel code.

Prerequisites

• Install @taucad/runtime
• Completed the Quick Start

Goal

Configure a runtime client with middleware plugins to cache geometry and parameters, transform glTF coordinates, and add edge detection for sharp-edge rendering.

Steps

1. Import Middleware from @taucad/runtime/middleware

All built-in middleware is exported from the @taucad/runtime/middleware subpath:

import { geometryCache, parameterCache, gltfCoordinateTransform, gltfEdgeDetection } from '@taucad/runtime/middleware';

2. Add Middleware to createRuntimeClient

Pass the middleware array to the middleware option. Order matters: middleware runs in onion-model order (first registered = outermost layer):

import { createRuntimeClient, fromMemoryFS } from '@taucad/runtime';
import { replicad } from '@taucad/runtime/kernels';
import { esbuild } from '@taucad/runtime/bundler';
import { geometryCache, parameterCache, gltfCoordinateTransform, gltfEdgeDetection } from '@taucad/runtime/middleware';

const client = createRuntimeClient({
  kernels: [replicad()],
  bundlers: [esbuild()],
  fileSystem: fromMemoryFS(),
  middleware: [parameterCache(), geometryCache(), gltfCoordinateTransform(), gltfEdgeDetection()],
});

3. Understand Each Middleware

parameterCache() -- Caches getParameters results. Avoids redundant parameter parsing when the same file is analyzed multiple times. Uses the dependency hash as the cache key and stores results under .tau/cache/parameters/.

geometryCache() -- Caches createGeometry results. Skips kernel computation when code and parameters are unchanged. Stores MessagePack-serialized geometry under .tau/cache/geometry/. Requires a filesystem that supports writing (e.g., fromNodeFS, not fromMemoryFS for persistent cache).

gltfCoordinateTransform() -- Transforms glTF from Y-up/meters (common in CAD) to Z-up/millimeters for web viewers like Three.js. Applies to geometry produced by createGeometry.

gltfEdgeDetection() -- Adds edge primitives to glTF meshes for sharp-edge rendering. Improves visual quality when displaying CAD models with hard edges.

4. Use a Writable Filesystem for Caching

Geometry and parameter caches require a writable filesystem. Use fromNodeFS in Node.js or a writable filesystem in the browser:

import { createRuntimeClient } from '@taucad/runtime';
import { fromNodeFS } from '@taucad/runtime/filesystem/node';
import { replicad } from '@taucad/runtime/kernels';
import { esbuild } from '@taucad/runtime/bundler';
import { geometryCache, parameterCache } from '@taucad/runtime/middleware';

const client = createRuntimeClient({
  kernels: [replicad()],
  bundlers: [esbuild()],
  fileSystem: fromNodeFS('/path/to/project'),
  middleware: [parameterCache(), geometryCache()],
});

With fromMemoryFS(), caches are not persisted; geometry and parameter caches will still run but will not survive across sessions.

5. Render with Middleware Active

Render as usual. Middleware runs automatically:

const result = await client.render({
  code: {
    'main.ts': `
      import { drawRoundedRectangle } from 'replicad';
      export default function main() {
        return drawRoundedRectangle(30, 50, 5).sketchOnPlane('XY').extrude(10);
      }
    `,
  },
});

if (result.success) {
  console.log(`Rendered ${result.data.length} geometries`);
}

Variations

• Preset with all middleware: Use presets.all() from @taucad/runtime to get all kernels, middleware, and bundlers. The preset returns { kernels, middleware, bundlers } which you pass directly to createRuntimeClient. Add fileSystem separately:

import { createRuntimeClient, presets } from '@taucad/runtime';
import { fromNodeFS } from '@taucad/runtime/filesystem/node';

const client = createRuntimeClient({
  ...presets.all(),
  fileSystem: fromNodeFS('/path/to/project'),
});

• Selective middleware: Omit middleware you do not need. For example, skip gltfEdgeDetection() if your viewer does not use edge rendering.
• Middleware order: Place caches (parameterCache, geometryCache) before transforms (gltfCoordinateTransform, gltfEdgeDetection) so cached results still flow through transforms on the return path.

Related

• Middleware Model -- How the onion model works
• Create Custom Middleware -- Build your own middleware
• API Reference: Middleware -- Middleware types and factories
• API Reference: Client -- createRuntimeClient options