What is the extent of requirements of being "statically analyzable" for the v7 store?

[Jamie5]

(inspired by discussions in #9828 )

Is the only thing that matters as far as being "statically analyzable" that you can have the 1 default export, and then the export-per-story?

i.e. if the code for a story file was

export default calculate_something_dynamically()

export Story1 = make_story_dynamically(...)
export Story2 = make_story_dynamically(...)
export Story3 = make_story_dynamically(...)

is that enough? Or does any more of it have to be there directly in the source code at the point of export?

Right now we don't need the v7 store yet, but since future versions will eventually make it required, get rid of storiesOf, etc, it seems worthwhile to understand the requirements a bit more. Right now we're using an API that wraps storiesOf and might move to dynamic CSF exports with commonjs instead of es modules (knowing that it might have to change in the future to get to v7 store), in order to make things like play functions work. So the wrapper is essentially rearranging the arguments into CSF form. And if the above code will work fine, then there might be less reason to move away from such wrappers.

Also what does being statically-analyzable enable, anyways? Why does anything except the default export need to be statically-analyzable, since IIUC it is some sort of perf improvement to not load all stories at once, but one only needs to know the module names (to generate the non-leaves of the tree) right? So why couldn't we have something like

export default { title: 'very static if this is needed' }

const stories = something_something(module);
stories.add(...);
stories.add(...);

to get a convenient API without having to build things for combinatorics, json, etc.

[shilman]

@Jamie5 i don't have a succinct answer and it will probably change, but here's a first attempt.

When Storybook starts it reads in all the story files and analyzes their contents but does not evaluate their contents. Consider a file Button.stories.js. To analyze its contents we just need to read a single file. To evaluate the contents (i.e. execute the JS in the file) we need to read that file, every file that it depends on, and so on, which is much slower. We use that analysis to build a file called stories.json, which is an index of every story/doc in the project. This is used to fill in the sidebar in Storybook's UI. So, for the most part, it's mostly the data in the sidebar that we care about: default export's title, each named export, and potentially the storyName annotation on each named export.

The reason we can't dynamically add stories per your example const stories = something_something(module); is because to know the list of stories we'd need to actually bundle / execute the JS and that's exactly what we're trying to avoid for the sake of performance.

Meta

The default export should be an object expression or a variable that references an object expression. If you use title, it should be a field in that object and the value should be a string literal.

Valid

export default {};

export default { title: 'foo' };

const meta = { title: 'foo' };
export default meta;

Invalid

export default metaFn();

export default { title: `baz` };

const a = { title: 'moo' };
const b = a;
export default b;

Stories

Each story should be a named export that should either be a function or an object. We can probably loosen the requirements on this. If you use the name/storyName field to control the name, it should be set in the exported object.

Valid

export const Foo = () => { /** anything **/ };

export const Bar = { /** anything **/ };

export const Baz = Template.bind({});

const Foo = () => { /** anything **/ };
export const Moo = Foo;

export const Foo = () => { /** anything **/ };
Foo.storyName = 'foo';

export const Bar = { name: 'bar', /** anything **/ };

[tmeasday]

If we are happy with the static generation being "wrong" in some cases, we shoud also ensure we have good tests in the UI side that the subsequent updates when the story loads update the data structure. In particular at the moment the only event we send over is the STORY_PREPARED event which pertains to the current story so we wouldn't update the rest of the stories for the component that just got loaded. We might consider changing that.

@Jamie5 I'd still ask what is the use case here, you haven't really spoken to why you need to programatically generate stories in this way?

[Jamie5]

I'd make an argument that if people use search mainly to find a buggy story to investigate, then search by module name is enough (and reduces the size of the json anyways).

But as for use case - we currently use a wrapper around storiesOf, but are wishing to use that wrapper for CSF, in order to take advantage of the play function (my understanding, which may be wrong (though experiments have not suggested otherwise), is that storiesOf does not work with play, and hence we have a need today to use CSF. However, converting everything to CSF instead of our wrapper seems a bit disadvantageous in that the format that storybook uses historically seems to have changed fairly often, and so having a wrapper has the advantage of being able to e.g. migrate to CSF without updating all of the stories or having multiple story formats at once, which means we get to use the play function without mass migrations immediately.

Now, from what I understand, per #9828, today, there is no easy way to use CSF with combinatoric tests or loading tests from json, which are both use cases that we have. There are proposals to make this possible at some future point before storiesOf is removed, but at the moment we have a need to both use CSF to be able to use play, while also not wanting to do a massive migration to a format that may yet change further in the future, and for which we can't "correctly" use today until the combinatorics and json tests are supported (the temporary workaround is using commonjs modules to have dynamic exports, but of course that won't work with store v7). Also it's unclear at this time if we have things that would have problems for whatever the eventual solution for combinatorics and json are, and it wouldn't be clear until we attempted to fully migrate things over "for real".

I vaguely remember reading somewhere about a "loader" concept where I guess maybe you can define how a module file is processed, which sounds kind of interesting.

[tmeasday]

I would say that we won't change the format of CSF without providing a codemod to convert your code to the new format. We plan to do the same for (supported use cases) of storiesOf also. So I'm not sure the "defensive" approach is required in this case. There is lots of potential for things we can do via static analysis (e.g linting) that you lose by doing so, also.

combinatoric tests or loading tests from json

We have been thinking about this, but I am interested in the actual use case you are interested in for these two? Are you using these features right now? As always there's a tension between giving users power to do things and having to support it in all our tooling.

[Jamie5]

The thing is, we already have the wrapper and it does some stuff (which may have other solutions, but that was how it was written a long time ago). So there will be a cost at some point if we want to discard any idea of a wrapper (and to be clear, a wrapper at some level, even if not the whole thing, is likely to remain useful).

But yes, we currently have tests that load data from a directory of json files and renders each file in a certain way. (you could argue that we should instead of generating json files from a process, generate js modules from that process, but given that we'd need to occasionally upgrade" said tests by transforming the json, parsing js, extracting the json, transforming it, and rewriting the js, seems a lot of work. Or maintaining a process which takes json and writes out js in stories format, yet still seems like a bunch of extra work compared to just doing a loop). And tests that test a certain component with a set of examples per situation, and multiple situations, that just happens. These work fine right now due to the imperative storiesOf API.

[shilman]

As 7.0 draws closer, we're starting to get some clarity on solutions to both JSON fixtures and combinatorial testing.

I'll update the original issue #9828 with a proposal when it's ready. But in short:

• For combinatorial testing, we'll advocate an addon that renders combinatorial variants of a component in a story
• For JSON fixture testing, we'll advocate an addon that transforms JSON to CSF as part of the loading process

We'll be shooting for a solution that satisfies the majority of the community's use cases for storiesOf, hopefully released in 7.0 and refined in 7.x, and then to remove storiesOf entirely in 8.0.