Appearance
The Vite plugin
A Gesso application is three files either side of a thread barrier, and until recently the barrier cost you four incantations in two of them:
ts
// main.ts, before
const app = createApp({
renderWorker: () => new Worker(new URL('./RenderWorker.ts', import.meta.url), { type: 'module' }),
appLogicWorker: () => new Worker(new URL('./AppWorker.ts', import.meta.url), { type: 'module' })
});ts
// RenderWorker.ts, before
const app = renderRoot(AppRoot).useService(Feed);
import.meta.hot?.accept('./AppRoot', module => {
app.reload(module.AppRoot, [module.Feed]);
});Not one of those is a decision. Every application writes them the same way, each of them fails silently when it is wrong, and the second pair is written from scratch every time because there is nothing to copy from except another application. gesso-vite-plugin writes all of them.
ts
// vite.config.ts
import { gesso } from 'gesso-vite-plugin';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [gesso()]
});ts
// main.ts, after
createApp({ history: { mode: 'path' } }).mount('#app');ts
// RenderWorker.ts, after
renderRoot(AppRoot).useService(Feed);The three-file shape is unchanged, and it is not going anywhere: a component cannot cross a postMessage, so the root has to be named on the worker's side of the barrier. What the plugin removes is the ceremony around that fact.
How it finds the entries
The shell is the module that calls createApp imported from gesso-framework. Beside it, the plugin asks the bundler's own resolver for the first of these that resolves:
| Entry | Names tried, in order |
|---|---|
| Render worker | RenderWorker.ts, RenderWorker.tsx, render.worker.ts, app.render.worker.ts, worker.ts |
| Application worker | AppWorker.ts, AppWorker.tsx, app.worker.ts, app.logic.worker.ts |
The specific names beat the generic one, so an application with both RenderWorker.ts and worker.ts gets the first, and the scaffold, which has only worker.ts, still resolves. An application with no application worker gets no appLogicWorker, which is the shape the scaffold produces.
Adding one later needs no restart. When a file under one of these names appears beside the shell, or goes, while the dev server runs, the server drops the shell it had transformed and reloads the page, so an AppWorker.ts written halfway through a session serves its channels on the next load.
If your files are called something else, say so:
ts
gesso({ renderWorker: './ui/paint.worker.ts', appLogicWorker: false });The resolution goes through the bundler rather than the filesystem, so your aliases and your extensions apply, and a name that would not have resolved is an error at startup rather than a worker that never starts.
What it writes
Into the shell module, on the same line as your call, so no line number moves:
ts
const app = createApp(__gessoOptions({ history: { mode: 'path' } }));and below it a function that merges the factories under the options you wrote:
ts
function __gessoOptions(options = {}) {
return {
renderWorker: () =>
new Worker(new URL('./RenderWorker.ts', import.meta.url), { type: 'module', name: options.workerName }),
appLogicWorker: () =>
new Worker(new URL('./AppWorker.ts', import.meta.url), { type: 'module', name: options.workerName }),
onError: __gessoReportError,
...options
};
}Your spread comes last, so anything you wrote wins. Writing the construction by hand is still supported and still correct; the plugin sees a renderWorker in your options and leaves the construction alone.
new Worker(new URL(...), { type: 'module' }) is written out literally because that is the only form a bundler emits a chunk for. It cannot see through a variable holding the URL, which is exactly why this text has to be emitted into your module rather than living inside the framework.
workerName is passed through to both workers. It is how a worker reads a flag that only the page's URL carries: Segue's ?still mode and the playground's are the same trick, and the worker asks its own name.
Into the render worker entry, in development only:
ts
import * as __gessoImported0 from './AppRoot';
const __gessoLatest = [__gessoImported0];
if (import.meta.hot) {
import.meta.hot.accept(['./AppRoot'], replaced => {
replaced.forEach((module, index) => {
if (module !== undefined) {
__gessoLatest[index] = module;
}
});
__gessoRenderRoot.app.reload(__gessoLatest[0].AppRoot, [__gessoLatest[0].Feed]);
});
}The modules it accepts are the one the root component was imported from and the one each useService argument came from, because a registry is keyed by the class object and a replacement has to be handed over. A service declared beside the root, which is what most applications do, needs no second dependency.
Two things it deliberately does not wire. useRoutes is read once when the runtime is built, so a change to a route table is a full reload rather than a replacement that would leave the old routes resolving. And a renderRoot(<App />) whose argument is not a plain name gets no wiring at all, with a message saying so: a replacement has to be looked up by name in the module that changed.
The error overlay, by default
While the dev server is running, onError is wired to a reporter that loads gesso-devtools the first time something throws and draws the overlay over the application. It is lazy in both directions: a page that never throws never fetches the package, and a production build contains no reference to it, because the plugin emits none of this outside a dev server.
An onError the application passes to createApp is kept: in a dev server the plugin calls the overlay's reporter first and then the application's, so an application that records its own failures records them in development too, and still gets the overlay.
The overlay covers the element the application was mounted into, found as the canvas's parent. A page hosting several applications should turn this off and mount its own, since one canvas is a guess:
ts
gesso({ overlay: false });What a shipped application wants instead is its own reporter.
The warning that saves an afternoon
The failure that looks like a bug in the framework: you save a component, the page reloads instead of replacing the tree, and nothing anywhere says why.
The cause is almost always that the module is reachable from the main thread as well as from the render worker. A bundler propagates an invalidation up the import graph until it finds a module that accepts; your main thread accepts nothing, so the whole page goes. The plugin knows both ends of that graph, so it walks the importers and says so:
text
[gesso] src/App.tsx is imported by the main thread as well as by the
render worker, so saving it reloads the page instead of replacing the
tree. Reach it only from the render worker's own graph to get hot
replacement back.Once per file per session, in the dev server's own output. gesso({ diagnostics: false }) turns it off.
Dependencies with a worker build
Your application's code runs in workers, and Vite resolves every dependency for a page: with the browser export condition. A package's browser build may reach for document, which a worker doesn't have. Every markdown parser built on micromark imports decode-named-character-reference, whose browser build does exactly that, and a render worker that imports one dies on start with "document is not defined".
Packages like that usually publish a worker build too, so the plugin adds the worker condition ahead of Vite's defaults. A package's own export order decides between worker and browser, and the packages that ship both list worker first. The main thread resolves the same way: a worker build runs in a page as well. To resolve as Vite does by default, pass workerConditions: false.
Workers are built as modules
The workers the plugin constructs are module workers, so it builds them as ES modules too, and a worker can load a chunk when it needs one:
ts
const { htmlToMarkdown } = await import('./htmlMarkdown');Vite builds workers as IIFE unless told otherwise, and an IIFE cannot be split, so before this a dynamic import in a worker was inlined into it and its module went into every page load. An application that sets worker.format itself keeps its choice.
Channels, described
A channel's contract is types and comments, and both are gone once the module runs. The plugin reads each contract with TypeScript's checker and puts them back: it appends a describeChannel call to the module, so the token carries a JSON Schema of its view and of every command wherever it is imported.
ts
import { channelSchema } from 'gesso-framework';
channelSchema(Notes);
// {
// description: 'The notes the person has written.',
// view: { type: 'object', properties: { rows: { type: 'array', ... } } },
// commands: {
// remove: {
// description: 'Deletes a note for good.',
// parameters: ['id'],
// input: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
// destructive: true,
// confirm: true
// }
// }
// }That is what an AI agent driving the application reads to know what it can see and what it can ask for, and it is written from what the author already wrote. The JSDoc on the token, on a view key and on a command becomes its description; @param describes a parameter; and four tags annotate a command:
| Tag | Means |
|---|---|
@destructive | What it does cannot be undone |
@idempotent | Sending it twice changes nothing the first did not |
@confirm | A person should approve it before anything else sends it |
@hidden | For the application's own components, not for an agent |
@hidden on a view key is read too: the key stays in the schema, and ChannelSchema.hidden lists it, so an agent is given the view without it. On the exported token it marks the whole channel (ChannelSchema.internal), and an agent is offered nothing of it.
So write those comments for a reader who has never seen the code. A comment explaining why two keys are separate is useful to a maintainer and noise to an agent deciding what to send.
A value that cannot cross a channel cannot be described either. A Date, a Map, a class instance or a function in a contract is reported as a build warning naming its path, and so is an empty array literal with no type, [], which is never[] until it says what it holds. Bytes are the exception in a command: an ArrayBuffer or a typed array there crosses as itself and is described as a base64 string tagged x-gesso-binary, which the agent surface decodes. In a view key they are still a warning.
It needs TypeScript 7 in the project, which is what reads the types. Without it the plugin says so once and the application runs undescribed. A build reads each worker's contracts too, through worker.plugins, which Vite adds to rather than replaces.
Describing a bundle Vite does not build
An Electrobun main process is bundled by Electrobun, which takes no plugins, so the plugin never describes the contracts it imports. The package's gesso-channels command describes them ahead of time, by writing a module the main process imports once:
bash
gesso-channels src/shared/Counter.ts --out src/shared/channels.described.ts--check fails instead of writing when the module is out of date. On the desktop has the rest.
An endpoint for agents
While the dev server runs, the plugin serves MCP at /__gesso/mcp, so an AI agent can read the open page's channels and send their commands, and prints the lines to connect Claude Code, Codex and Gemini CLI when the server starts, under agentName (the root folder's name unless given). Agents and MCP has how it reaches the workers and what the agent sees. agent: false turns it off. agentPath serves it at a path of the application's own, such as /__my-app/mcp; /__gesso/mcp keeps answering too, so an agent connected before still reaches it.
The same endpoint offers the project's own components, read by the checker from the files its tsconfig includes, so an agent designing a screen uses what is there instead of drawing it again from boxes. Designing with what the project has has the tools. A library joins them only when named:
ts
gesso({ catalog: { libraries: ['gesso-components'] } });catalog: false leaves them out, catalog: { tsconfig } names a tsconfig other than the root's, and catalog: { root } reads another project's components, for an application that designs one, such as a design editor serving the project it works on from another folder. A host that is not a dev server, such as a desktop app's main process, opens the same catalog from gesso-vite-plugin/catalog, which imports nothing from Vite: on the desktop.
Options
| Option | Default | What it does |
|---|---|---|
renderWorker | discovered | The render worker entry, as a specifier beside the shell |
appLogicWorker | discovered | The application worker entry, or false for an app with none |
overlay | true | Wire the error overlay into onError while the dev server is running |
hmr | true | Emit the import.meta.hot.accept wiring |
diagnostics | true | Report a save that will reload the page |
workerConditions | true | Resolve a dependency's worker build ahead of its browser one |
channelSchemas | true | Describe each channel as JSON Schema, from its types and JSDoc |
agent | true | Serve MCP at /__gesso/mcp in the dev server, for AI agents |
agentPath | /__gesso/mcp | The path MCP is served at; the default keeps answering too |
agentName | root folder | The name the printed lines add the endpoint under |
agentInstructions | none | What an agent is told when it connects, after what the catalog says |
agentPrompts | none | Prompts the person runs in their agent, as slash commands |
catalog | true | Offer the project's components on that endpoint, and any libraries named |
Is it required?
No, and that is deliberate. The framework imports no bundler, and nothing in gesso-core or gesso-framework mentions Vite. The plugin is the supported path for development because it is the one that gets the wiring right on your behalf; the literal construction is the documented fallback, it is what the plugin emits, and an application that would rather say it out loud loses nothing but the overlay and the hot replacement it would then wire itself.
Next
Hot module replacement: what a reload keeps, what it costs, and the one thing you still have to hand over.