[RFC] defineMeta helper function

[AriPerkkio]

Summary

Add a helper function defineMeta into Storybook that users can use to type the default export of stories. This helper function will provide type-safety for end-users without needing to write any Typescript at all.

import { defineMeta } from "@storybook/react";
import { Button } from "./Button";

// Type-safety out-of-the-box without writing any Typescript!
export default defineMeta({
  title: "Example/Button",
  component: Button,
});

Problem Statement

Typing default exports in Typescript cannot be done in a single line that easy. It requires either type assertion, creating a new variable or use of satisfies keyword. There's open issue on Typescript project for this: microsoft/TypeScript#13626.
On Storybook's side there's an open issue as well: #18228.

import { type Meta } from "@storybook/react";
import { Button } from "./Button";

// 1. Requires additional variable 😕 
const meta: Meta = {
  title: "Example/Button",
  component: Button,
};

export default meta;

// 2. Type assertion - not type safe 😢 
export default {
  title: "Example/Button",
  component: Button,
} as Meta;


// 3. `satisfies` keyword. Works well but requires writing Typescript. 😫 
// As far as I know, this is 100% type-safe (compared to #2 above).
export default {
  title: "Example/Button",
  component: Button,
} satisfies Meta;

Non-goals

• Changing any structure of Meta
• This RFC considers only helper function of Meta typing. In feat: add defineMeta #25069 there's discussion about defineStory and defineConfig as well, but let's leave those for future to keep scope of this RFC small.

Implementation

See #25069.

The defineMeta helper function itself is very simple. It takes Meta as function argument and returns it as is, without changing it at all. In runtime code there should be no difference between using defineMeta or the export default { ... }. This is mostly a change of syntax.

function defineMeta(meta: Meta): Meta {
  return meta;
}

Each framework package of Storybook should export this helper function. By framework packages I mean @storybook/react, @storybook/html and so on. Example usage in React projects:

import { defineMeta } from "@storybook/react";

export default defineMeta({});

Storybook inspects users' stories by static analysis. Making changes to the supported format requires changes in csf-tools. Only the parts where export default AST is traversed requires changes.

storybook/code/lib/csf-tools/src/CsfFile.ts

Lines 249 to 298 in e2c05c6

	ExportDefaultDeclaration: {
	enter({ node, parent }) {
	let metaNode: t.ObjectExpression | undefined;
	const isVariableReference = t.isIdentifier(node.declaration) && t.isProgram(parent);
	let decl;
	if (isVariableReference) {
	// const meta = { ... };
	// export default meta;
	const variableName = (node.declaration as t.Identifier).name;
	const isVariableDeclarator = (declaration: t.VariableDeclarator) =>
	t.isIdentifier(declaration.id) && declaration.id.name === variableName;
	self._metaStatement = self._ast.program.body.find(
	(topLevelNode) =>
	t.isVariableDeclaration(topLevelNode) &&
	topLevelNode.declarations.find(isVariableDeclarator)
	);
	decl = ((self?._metaStatement as t.VariableDeclaration)?.declarations || []).find(
	isVariableDeclarator
	)?.init;
	} else {
	self._metaStatement = node;
	decl = node.declaration;
	}
	if (t.isObjectExpression(decl)) {
	// export default { ... };
	metaNode = decl;
	} else if (
	// export default { ... } as Meta<...>
	(t.isTSAsExpression(decl) || t.isTSSatisfiesExpression(decl)) &&
	t.isObjectExpression(decl.expression)
	) {
	metaNode = decl.expression;
	}
	if (!self._meta && metaNode && t.isProgram(parent)) {
	self._metaNode = metaNode;
	self._parseMeta(metaNode, parent);
	}
	if (self._metaStatement && !self._metaNode) {
	throw new NoMetaError(
	'default export must be an object',
	self._metaStatement,
	self._fileName
	);
	}
	},
	},

In the lines above the analysis is already checking where does the default exported object come from. It accepts the object if it's inlined in export default, or if it's coming from variable that is object. This logic needs to be extended to check if:

• export default contains CallExpression that has name defineMeta
• export default contains variable. Find that variable and check if it was initialized using defineMeta call.

Next analyze the CallExpression:

• Check if the first arguemnt of CallExpression is ObjectExpression
• If it is, use that as Meta in later analysis

Prior Art

The defineMeta is inspired by common conventions used across JS/TS ecosystem. Most modern tools use defineConfig that can be used to write type-safe default exports. For example Vite, Playwright, Cypress and Astro use this convention.

Deliverables

1. Add support to csf-tools
2. Introduce defineMeta helper in framework packages
3. Update documentation

Future: Introduce more define... helper functions.

Risks

No response

Unresolved Questions

• In feat: add defineMeta #25069 (comment) it was proposed that defineMeta would return an object { meta, defineStory }. This would be useful for automatically typing the defineStory part. But it would not solve the original issue I've described, as meta could not be exported in a single line. I'm not yet sure how defineStory could be supported while keeping export default defineMeta({}) working.

Alternatives considered / Abandoned Ideas

No response

[tobiasdiez]

Taking inspiration from how Vue works, one could also remove the requirement that the meta is exposed from export default (and stories have to be exported as well). It would be enough to just look for the defineMeta/defineStory function.

Then the following would work:

import { defineMeta } from '@storybook/react';

import { Button } from './Button';

const { defineStory } = defineMeta({
  component: Button,
});

defineStory({
  name: 'Primary'
  args: {},
});

(or one goes even a step further and removes const { defineStory } as well, at the cost of adding a language server extension for vscode and other IDEs for proper ts support)

A similar proposal came up in the idiomatic vue implementation: tobiasdiez/storybook-vue-addon#73 (comment)