How do you use Storybook to render via a Node.js server?

[kleinfreund]

Summary

I can't find current/working documentation on how to use storybook with a Node.js-based render server.

Some articles online reference https://www.npmjs.com/package/@storybook/server but that's undocumented and I can't get it to work. Even a basic setup with only { framework: '@storybook/server' } in the .storybook/main.js fails with Invalid value of '@storybook/server' in the 'framework' field of Storybook config and the suggested command to auto-migrate doesn't do anything. I assume this package is deprecated on account of it not being documented anywhere on https://storybook.js.org/ in contrast to what its package readme says.

So, how do I create a Storybook setup without any framework that let's me render HTML via a Node.js server? My goal is to render .twig files but I intentionally want to keep this agnostic from any particular templating language or framework so I'm free to choose something other than Twig.

More precisely, how do I make storybook render a story using the HTML returned from a server via a request of roughly the form GET http://localhost:3000/render/button--default?label=Submit? The only thing included in the request that's strictly required is the story ID so I can find the relevant template file on disk. Other data like the story variant or args is useful and would allow me to extend this further.

Additional information

No response

Create a reproduction

I can get a basic setup working because the @storybook/server-webpack5 happens to allow using a Node.js server like so:

.storybook/main.js:

export default {
	stories: ['../components/**/*.stories.js'],
	framework: '@storybook/server-webpack5',
}

.storybook/preview.js:

export const parameters = {
	server: {
		url: `http://localhost:3000/render`,
	},
}

However, I'd like to learn how I can write the storybook framework myself because I don't really need all that webpack stuff. The only thing I need is the ability to define the render server URL.

[dosubot[bot]]

@storybook/server is not deprecated — it's actively maintained but has very limited public documentation, which understandably causes confusion.

The error you're hitting (Invalid value of '@storybook/server' in the 'framework' field) is because the framework package is @storybook/server-webpack5, not @storybook/server (the latter is the renderer) [1].

Here's a working setup:

.storybook/main.ts

import type { StorybookConfig } from '@storybook/server-webpack5';

const config: StorybookConfig = {
  stories: ['../stories/**/*.stories.@(json|yaml|yml)'],
  framework: '@storybook/server-webpack5',
};

export default config;

.storybook/preview.ts

export const parameters = {
  server: {
    url: 'http://localhost:3000/storybook_preview',
  },
};

Stories are defined in JSON (not JS) — e.g. stories/button.stories.json [2]:

{
  "title": "Button",
  "parameters": {
    "server": { "id": "demo/button" }
  }
}

Your Node.js server then needs a route that maps the story id to a template render [3]:

app.get(/storybook_preview\/(.*)/, (req, res) => {
  // req.params[0] = "demo/button"
  // req.query = story args passed as query params
  res.render(req.params[0], req.query); // render your .twig file here
});

Storybook fetches HTML from http://localhost:3000/storybook_preview/demo/button?arg1=value1 and displays it in the canvas [4]. This works with any templating engine (Twig, Pug, etc.) as long as your server returns HTML.

There's a complete working example in the repo at test-storybooks/server-kitchen-sink using Express + Pug that you can reference [5].

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[kleinfreund]

Docs are dead. Just use Dosu.

What the, and I say this with the least amount of respect I can muster, fuck.

[UnknownHawkins]

Provide guidance on creating a custom framework that sets server URL. Possibly mention that @storybook/server is not a framework; you need to use @storybook/server-webpack5 or create custom framework using @storybook/framework. Provide steps: create a folder my-framework with package.json, index.js exporting framework name, and using addons: maybe use @storybook/manager-api etc. There's @storybook/server which is a preview framework for static rendering? The error indicates that framework field expects a preset name that resolves to a framework package; @storybook/server is not a framework but a preview. So answer: you need to use @storybook/server-webpack5 or create your own framework that extends @storybook/framework and uses the server addon. Thus final answer: explain that you cannot set framework to @storybook/server; you need to use a framework like @storybook/server-webpack5 or @storybook/html etc. If you want just server rendering, you can use the static Storybook build and serve via your own Node server, or use Storybook's built-in static mode. Or you can create a custom framework that simply sets the preview parameters. } using addons: maybe use @storybook/addon-essential

[MILLERMARRU]

The exact error points at the framework value used in main.js, @storybook/server on its own isn't a valid framework package, the real one is @storybook/server-webpack5. Confirmed against the actual working example in the storybook monorepo itself (test-storybooks/server-kitchen-sink), which is the closest thing to a canonical reference for this setup:

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/server-webpack5'

const mainConfig: StorybookConfig = {
  stories: ['../stories/**/*.stories.@(json|yaml|yml)'],
  addons: ['@storybook/addon-docs', '@storybook/addon-a11y', '@storybook/addon-links'],
  framework: '@storybook/server-webpack5',
}

export default mainConfig

The rest of the setup, per @storybook/server-webpack5's own README:

// .storybook/preview.js
export const parameters = {
  server: {
    url: `http://localhost:${port}/storybook_preview`,
  },
}

Stories are plain JSON (or YAML) files rather than CSF, since there's no client-side render function, Storybook just does a GET to ${parameters.server.url}/${parameters.server.id} and shows whatever HTML comes back:

{
  "title": "Component",
  "stories": [
    {
      "name": "Default",
      "parameters": {
        "server": { "id": "path/of/your/story" }
      }
    }
  ]
}

Running npx storybook@latest init -t server scaffolds exactly this (framework field included), which is probably the fastest way to get a known-working baseline before adapting it to an existing project.