emdash-plugin-stl-viewer

An EmDash CMS plugin that embeds interactive 3D previews of STL and 3MF files inside Portable Text content. Drop a 3D Model block into any post or page, pick a file (or paste a URL), and get a touch-friendly orbit viewer that loads three.js lazily on viewport entry.

Features

• STL and 3MF — both formats supported. Format is auto-detected from the URL's file extension (.stl / .3mf); set an explicit override in the block form for opaque URLs.
• Lazy three.js — the library (~170 KB gzipped) downloads only when a viewer is scrolled near; pages with no model embeds pay nothing.
• Lazy 3MF decoder — the 3MFLoader (plus the bundled fflate zip decoder) loads on-demand the first time a 3MF URL is encountered. Pages with STL-only content never pay the 3MF cost.
• Shared module — additional viewers on the same page reuse the cached module, only paying for their own scene.
• Five materials — matte plastic, glossy plastic, brushed metal, surface-normal rainbow, unlit clay. The configured material is applied uniformly to 3MF imports (the file's embedded materials are intentionally overridden so blocks render consistently with STL).
• Three sizes — compact / standard / tall, all responsive.
• Auto-rotate on idle — pauses on user input, resumes after a moment.
• Touch support — pinch-zoom, two-finger pan, one-finger orbit.
• Progress UI — bytes/total during model download, indeterminate while three.js loads.
• Auto Z-up detection — many printable STLs and 3MFs ship Z-up; the viewer rotates them so Y is up.
• Auto-framing — the model is recentered around the origin and the camera distance is derived from the bounding sphere and FOV.

Installation

pnpm add emdash-plugin-stl-viewer three
# (peers: astro, emdash, three)

Register it in astro.config.mjs:

import { stlViewerPlugin } from "emdash-plugin-stl-viewer";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [stlViewerPlugin()],
			// ...
		}),
	],
});

That's it. The block type stl-viewer (labeled "3D Model (STL or 3MF)" in the slash menu) is now available in the Portable Text editor.

Authoring

In the editor, type / and pick 3D Model (STL or 3MF). Fill in:

| Field | Description | | --- | --- | | Model file | Opens the EmDash media picker filtered to model/* MIME types. Pick an existing asset, upload a new .stl/.3mf, or paste a URL directly into the input. | | Format | Auto-detect from URL (default) / STL / 3MF. Override when the URL has no extension. | | Title | Optional header text. | | Caption | Optional figcaption below the viewer. | | Material | Matte plastic, glossy plastic, brushed metal, normal map, or unlit clay. | | Color | Hex color for matte/glossy/metal materials. Ignored by normal. | | Viewer height | Compact (320 px), Standard (440 px), Tall (560 px). | | Auto-rotate when idle | Off if you'd rather have a static front view. | | Show ground plane | Subtle grid beneath the model. |

Uploading STL or 3MF files

The block's Model file field uses EmDash's media_picker with mime_type_filter: "model/". In the popup you can:

• Select an existing asset (filtered to model/* MIME types).
• Upload a new .stl or .3mf — the file dialog's accept is scoped to model/, and EmDash's /_emdash/api/media/upload-url endpoint passes the MIME type through to R2 without a global allowlist.
• Paste a URL directly into the input — the field value is a plain string, so external URLs (https://…) work too.

Browsers may not recognise .stl / .3mf from extension alone (the Content-Type arrives as application/octet-stream). EmDash now retains the upload's original Content-Type header, but if you're hosting your own asset server, set Content-Type: model/stl or model/3mf explicitly. The viewer itself does not require a particular MIME type — it sniffs the URL's extension or the explicit format override.

Architecture

The plugin is native format — that's required for Portable Text block types because they need Astro components for site-side rendering.

src/
├── index.ts              # PluginDescriptor + definePlugin() (Native format)
└── astro/
    ├── index.ts          # Exports `blockComponents` map
    ├── StlViewer.astro   # Server-rendered placeholder + scoped CSS
    └── viewer-client.ts  # Lazy three.js + 3MF init, OrbitControls, lifecycle

The Astro component renders a placeholder card with a CSS-animated phantom cube. When the wrapper enters the viewport (IntersectionObserver, 400 px root margin), the client script:

1. Dynamically imports three, three/addons/controls/OrbitControls.js, and three/addons/loaders/STLLoader.js (memoised — one fetch per page).
2. If the URL ends in .3mf (or format === "3mf"), additionally imports three/addons/loaders/3MFLoader.js lazily.
3. Streams the model via fetch with a progress callback so large files show byte counts.
4. STL: parses to a single BufferGeometry, recenters it, computes smooth-shaded normals. 3MF: parses to a Group (potentially multi-mesh), replaces embedded materials with the configured material, repositions the group's centroid to the origin.
5. Mounts a WebGLRenderer canvas inside the stage, attaches OrbitControls.
6. Hooks up ResizeObserver so the renderer follows container resizes, and a second IntersectionObserver to pause the render loop when offscreen.

A note on Astro scoped CSS

The canvas element is injected by three.js at runtime, so it doesn't carry the data-astro-cid-* attribute Astro adds to elements declared inside the component. Any selector targeting the canvas must use :global(canvas), or Astro's scope rewrite will silently leave the runtime element unstyled. The viewer hits this in two places — both are wrapped accordingly in StlViewer.astro.

Bundle layout

Built via Vite (Astro):

| Chunk | Approx size | When loaded | | --- | ---: | --- | | StlViewer.astro_…js | ~7 KB | Eagerly with the page that has a viewer | | three.module.js | ~690 KB | First viewer hits viewport | | OrbitControls.js | ~19 KB | First viewer hits viewport | | STLLoader.js | ~3 KB | First viewer hits viewport | | 3MFLoader.js (+ fflate) | ~50 KB | Only on the first 3MF viewer on a page |

Development

pnpm install
pnpm generate-fixtures   # writes cube.stl / icosahedron.stl / torus.stl / knurled.stl to public/stls/ of the host repo
pnpm typecheck

Compatibility

• Astro >= 6.0
• EmDash >= 0.12 (uses Block Kit's media_picker element with mime_type_filter).
• three ^0.171.0

Changelog

• 0.3.0 — Switch the Model URL field to a media_picker filtered to model/* MIME types. Authors get a unified pick/upload/paste-URL popup in the block form. Bumps the required EmDash version to >= 0.12. Existing content is unchanged — the field value is still a plain URL string.
• 0.2.0 — Add 3MF support alongside STL. 3MFLoader (plus the bundled fflate zip decoder) lazy-loads only when a 3MF URL is encountered.
• 0.1.0 — Initial release. STL viewer block with five materials, three sizes, auto-rotate, touch support, and a lazy three.js bundle.

License

MIT — see LICENSE.