The config

A config file default-exports defineStudioConfig({ ... }). defineStudioConfig returns its argument; it exists so the object is typed. The runtime exports are defineStudioConfig and adoptStylesheet. The types are StudioConfig, StudioCompose, StudioRuntime, StudioTheme, and, for apps, StudioApp, StudioAppPage, StudioAppProps, StudioAppSurface, StudioPreviewProps, StudioSurfaceProps, PreviewZoom and RenderPdf.

import { createIsomerRuntime } from '@elastic/isomer-runtime';
import { defineStudioConfig } from '@elastic/isomer-studio';

import { previewSlide } from './src/examples/preview_slide';
import { slideDeckFrame, slidesPack, slideStylesheet } from './src/index';

export default defineStudioConfig({
  runtime: createIsomerRuntime({
    packs: [slidesPack],
    frames: { slide: slideDeckFrame },
  }),
  stylesheet: slideStylesheet,
  previewExample: previewSlide,
});
		

Examples are nodes, not compositions. Every place the Studio needs a composition, the config's compose, or its previewExample, builds it: the gallery, the docs pages, the editor's preview, the PNGs a static build prerenders and every example check renders. A pack writes the envelope once and every mode agrees on it.

The default fits a pack whose primitives render inside a plain view. A pack whose frame requires a particular root says how one node is shown with previewExample. The slides frame draws exactly one slideFrame, so the slides previewExample wraps a lone node in a preview slide, and passes a node that is already a slideFrame through unwrapped. compose replaces both when a pack needs to shape several nodes too.

compose receives the theme the Studio is showing, light or dark, and puts it on the composition; with previewExample, the Studio does. That theme is the app's color mode, so previews always match the chrome around them. Light and dark are then different compositions, which is how a static build tells their PNGs apart.

images: false keeps the Studio in the browser. Node never loads @elastic/isomer-image-takumi or imageFonts, build writes no PNGs, PNG previews and PDF actions are hidden, and dev answers /png and /pdf with 404. The snapshot surface's markup still renders, and check --png refuses the config.

Toggling it in dev hot-updates in place, keeping the route and the editor's draft. An app that offers PNGs or PDFs should hide those actions when rasterizePng or renderPdf is absent, and fall back when a surface it is showing leaves surfaces, as Decks does.

Home opens with a strip of featured primitives, each with a link to its Reference page and to the Workbench. featured names them by type, in the order they appear:

export default defineStudioConfig({
  runtime,
  featured: ['titleSlide', 'slideBulletList', 'slideSplitLayout'],
});
		

Without featured, Home draws six primitives at random each time it loads, so a pack with no opinion still shows its range. dev, build and check reject a featured entry the runtime has no primitive for, or one listed twice, and name it. A browser hot update with an invalid entry reports it and skips it.

An app is a whole page of the Studio, such as a deck viewer. Each one gets a top-level nav entry beside Gallery, a tile on Home, and a route at #/app/<id>/.

export default defineStudioConfig({
  runtime,
  apps: [
    {
      id: 'decks',
      title: 'Decks',
      description: 'Whole presentations, played one slide at a time.',
      load: () => import('./studio/decks_app'),
    },
  ],
});
		

dev, build and check reject invalid apps and name each one. A hot update with invalid apps keeps the last valid ones and shows why. check counts the apps but never calls load.

An app can list its own pages in the nav, such as one per deck. The nav shows them without loading the app, so a config builds them from data it already imports.

pages: [
  { path: 'isomer', title: 'Isomer', section: 'Decks' },
  { path: 'distillate', title: 'Distillate', section: 'Decks' },
],
		

A page is current when the app's path equals the page's path or starts with it plus /. The longest match wins, so isomer/3 keeps a page at isomer/3 current over one at isomer. While a page is current, the app's own row is not. The collapsed rail shows only the app's row.

dev, build and check reject invalid pages as they do invalid apps, naming the app and the page's index.

The page is a React component, and the Studio hands it StudioAppProps:

Import only types from @elastic/isomer-studio in an app module. The Studio hands the page everything it needs as props.

The page stays mounted when path, the theme or the config changes. When the config changes, the Studio calls the new load and remounts the page only if the module's default export is a different component. Edits to the app module update it in place through React Fast Refresh, as long as the module exports only components. A module that exports anything else re-runs the config instead.

load runs only in the browser. Node imports the config for check and build, but never calls load, so code that must stay off the server belongs behind it.

Apps render under the Studio's own EuiProvider. Use EUI components directly, and nest EuiThemeProvider to change the theme for part of the page. Never mount a second EuiProvider.

EUI's theme and Emotion's cache reach the app only when it imports the same copies the Studio does. When a config with apps resolves @elastic/eui or @emotion/react, it must resolve the Studio's copy, and dev, build and check stop when it does not. A config without apps is not checked. Install the Studio's versions of EUI and its peers beside the config: @elastic/eui, @elastic/eui-theme-borealis, @elastic/datemath, @emotion/react, @emotion/css and moment.

Apps are not inside a shadow root, because EUI's popovers, flyouts, modals and toasts portal to document.body.

In dev, a stylesheet loads when the app first opens. A static build bundles every stylesheet the config imports into assets/app.css, which loads with the page.

The Studio offers the surfaces runtime.surfaces has. A runtime without a frame has no snapshot surface, so it gets no Snapshot or PNG previews, a static build prerenders no PNGs, and check reports those checks as skipped.

PNGs and PDFs are drawn by takumi in Node, which knows no fonts but its own. imageFonts names a module that default-exports the faces to draw with, as FontLoader[] from @elastic/isomer-image-takumi:

// studio/image_fonts.ts
export { slideFonts as default } from '../src/examples/fonts';
		

Node imports it the way it imports the config, the first time it draws, and the browser never does, so it may read font files from disk. dev, build and check --png all draw with it. Without it, PNGs fall back to takumi's built-in face and a PDF cannot draw text.

The config runs in two places: in Node, for check and for the dev server's PNGs, and in the browser, bundled into the app.

In Node, check and build import the config with tsx, which compiles TypeScript and JSX as it loads and leaves resolution to Node. The config, its pack, React and the runtime all resolve from the config's own directory, so they come from the pack's node_modules. tsx applies the tsconfig.json nearest the config, so the pack's jsx setting holds in both ES module and CommonJS projects. Node cannot run ESM built for bundlers, which is what Isomer's own packages ship: an import that lands on such a build, a .js file in a package without "type": "module", takes the package's CommonJS build instead.

dev loads the config through Vite's server-side module graph instead, with the same nearest-tsconfig.json JSX settings. Packages in node_modules load once through Node, except the SDK, the runtime and the Studio, whose ESM builds Vite compiles because Node cannot; an edit re-runs only the files that changed and the modules that import them.

--loader none skips both and imports the config with a plain import(). Use it for a JavaScript config, or to bring another loader through NODE_OPTIONS=--import .... Node caches that import, so under dev the browser picks up edits but PNGs keep the config and pack as they were at startup; restart dev to refresh them.

In the browser, build bundles the config with esbuild and dev serves it through Vite. react, react-dom and their subpaths resolve as if imported from the config, so the Studio's own components, Emotion and the pack share one React, and each package's browser build is the one loaded.

Run with npx, the Studio sits in npm's cache rather than the pack's node_modules. Two rules make that work in Node, Vite and esbuild alike:

• react, react-dom, @elastic/isomer-sdk and zod, imported from outside the project, resolve from the project, so the runtime and the pack share them.
• @elastic/isomer-runtime and @elastic/isomer-studio, when the project does not have them, resolve from the Studio's install. A config can import both without installing either.

The Studio depends on the SDK and runtime at its own version rather than as peers, so a cached npx @elastic/isomer-studio@next upgrades all three together when next moves.

The project is the directory of the package.json nearest the config. In Node the rules cover import and require, which a .ts config in a project that is not "type": "module" loads through.

The Studio, the pack and the runtime must use one copy of React, and it must be React 18, which EUI requires. Before loading the config, the Studio resolves react from the config, stops when it is not 18, then resolves react from the @elastic/isomer-runtime the config sees, and stops when they differ:

The Studio config and @elastic/isomer-runtime resolve different copies of React:
  config:  /work/pack/node_modules/react
  runtime: /work/pack/node_modules/@elastic/isomer-runtime/node_modules/react
Install one React for both, for example by deduplicating your lockfile.