TITLE string const as fallback for meta.title default export

[lunelson]

Since the default export of a non-primitive value breaks react-refresh functionality in Vite, this PR proposes an alternative for providing a Story title that is react-refresh compatible:

Instead of this:

export default { title: "My/Story/Path" }

Do this:

export const TITLE = "My/Story/Path"

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5bda641

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[tajo]

Appreciate the effort but I am not a big fan of adding this:

1. It's a completely new API that we would have to support forever.
2. It conflicts with the existing APIs (what gets the precedence?)
3. There are more things that go into export default like decorators, args and meta.
4. The improvement of user experience is pretty small and you can already avoid export default if you really care about HMR in stories that much. Also you can always keep story files light and do most of the work in the downstream modules.

I wonder if we could fork https://github.com/facebook/react/tree/main/packages/react-refresh instead to keep HMR working for the current API?

[lunelson]

Hey @tajo, thanks for your response and comments. I get that this might seem like a hack (it is); but given that Ladle already implements not-quite-standard CSFv3, I though it might be thinkable to offer a solution to something that is an acknowledged problem with CSF.

The goal in any case, is just to have more control over the story title, (which is to say mainly the nesting pattern of the title), so users can maintain a structured story organization without disabling HMR.

And in my opinion, HMR is not just a "small improvement": being able to refresh without losing state for example, is a big deal in dev efficiency (and I would guess that Ladle's faster DX is one of the reasons for choosing it over Storybook, no?)

Anyway, if there's a better way of doing this, I'm all ears. To your points:

It's a completely new API that we would have to support forever.

Certainly that's true.

It conflicts with the existing APIs (what gets the precedence?)

The way I wrote it so far, it's only a fallback option. So the default export would take precedence.

you can always keep story files light and do most of the work in the downstream modules

This part I don't understand. Could you explain what you mean here? Are there other/better ways of doing what I'm trying to do?

[tajo]

This part I don't understand. Could you explain what you mean here? Are there other/better ways of doing what I'm trying to do?

If you make a code edit in the .stories.tsx file (with an export default), fast refresh doesn't work but if you go a level bellow into your imported components/modules and make a code change there, fast refresh should still work.

[lunelson]

If you make a code edit in the .stories.tsx file (with an export default), fast refresh doesn't work but if you go a level bellow into your imported components/modules and make a code change there, fast refresh should still work.

Ah, OK thanks. Well, I can offer some other things I discovered (at least, working in Ladle 4.x), which are perhaps more sensible solutions to the question of specifying the story title (while maintaining fast-refresh)—although I don't know if these are officially features, or just incidental behaviours? Anyway:

1. double-dashes i.e. -- in the title of the file can be used to create a hierarchy: so a story file name called ui--button.stories.tsx will be the same as if one exported the meta object with { title: 'Ui/Button' }
2. underscores i.e. _ in the story function name also create hierarchy, so you can further nest the story paths within the same file: a story function name like Test_WithIcon exported from the example file I described above would give a final path of 'Ui/Button/Test/With icon'.

What do you think about a PR for adding this information to the docs, instead of the PR I proposed here? It would be very relevant to developers who value the fast-refresh workflow.

[tajo]

It's already documented: https://ladle.dev/docs/stories#navigation-and-routes

[lunelson]

Ah yes I see, the part about file names is documented, although not the part about function names. It's also not indicated anywhere that the meta object disables fast-refresh and this the file/function naming pattern is an alternate solution to setting the title property in meta. Are you not interested in a PR to add this information to the docs? I think it would help a lot of users

[tajo]

Definitely happy to approve any docs improvements.