Replies: 4 comments 9 replies
-
I'd like to put at ease regarding this matter, after what I found during my experiments. While using an upgraded addon to support <Story let:args>
<Button {...args} />
</Story>to this: <Story>
{#snippet children(args)}
<Button {...args} />
{/snippet}
</Story>A little bit more verbose, yeah, but the benefits are that
EDIT. Nope, I was wrong. I get the following error: |
Beta Was this translation helpful? Give feedback.
-
If you mean I haven't fully grasped yet the backward compatibility. As far I can tell from the quick glimpse. If we'd rewrite |
Beta Was this translation helpful? Give feedback.
-
|
What I mean is, the While Svelte 5 itself supports Svelte 4 syntax in general, there are some breaking changes with Svelte 5 that could block project's from upgrading. Hopefully it shouldn't be often though. |
Beta Was this translation helpful? Give feedback.
-
|
I think maintainers of the Svelte can give a better answer than I do. 🙏 |
Beta Was this translation helpful? Give feedback.
-
|
Yes, if you want to use snippets or any new features from Svelte 5 then the user's project will need Svelte 5 installed and Storybook will need to list it as a peerDependency. I think it should be fine to increase the peerDependency version in the next major release of Storybook. It is intended to be fairly straightforward for users to upgrade their projects to Svelte 5. There are some breaking changes, but they're intended to be fairly minimal such that most users won't hit most of them: https://svelte-5-preview.vercel.app/docs/breaking-changes |
Beta Was this translation helpful? Give feedback.
-
|
Great, that matches my mental model.
I think this is the key point. |
Beta Was this translation helpful? Give feedback.
-
|
@shilman, we discussed the idea of Kitbook shifting it's terminology from variants to stories, from import type { Story } from 'kitbook'
import type Component from './Greeting.svelte'
export const Simple: Story<Component> = {
props: { // props is what we call these in Svelte, but Kitbook would also accepts `args` for the same purpose
greeting: 'Hello World',
},
description: 'A simple greeting',
}The comparable version in Storybook CSF (sans description) would look like this: import type { Meta, StoryObj } from '@storybook/svelte'
import Greeting from './Greeting.svelte'
const meta: Meta<typeof Greeting> = {
component: Greeting,
}
export default meta;
type Story = StoryObj<typeof meta>
export const Simple: Story = {
args: {
greeting: 'Hello World',
},
}Both files would be The purpose of all this is to help the wider dev community coalesce around some standards for component development. We want people to easily understand the usefulness of our tools and how they can improve their DX. So my question then is, how much of Storybook's Svelte community actually uses |
Beta Was this translation helpful? Give feedback.
-
|
@jacob-8 Yeah I can see how things are a bit confusing! What's the current status?
Where are we headed?
Given how dynamic this is, we're not trying to make CSF an interoperable standard. Someday maybe, but not in the next 2y. What does this mean for you?We're trying to establish the terminology of "Story = Component + Inputs", which is used by Storybook and similar tools. So if you renamed Kitbook variants to stories, that would align with what we're doing. As for being able to flexibly migrate between the two tools, it sounds great on the surface. Each tool will have its strengths and weaknesses, so being able to flexibly switch back and forth makes it possible to pick and choose (e.g. Kitbook for developing inside your app, storybook for CI). My suggestion would be to wait a month or two for our CSF4 RFC and potentially join in the discussion there. It won't be the last major iteration, but it's a chance to align more closely AND also means that you won't make changes now and then have the rug pulled out from under you in a few months. |
Beta Was this translation helpful? Give feedback.
-
|
Wonderful! That is a very helpful clarification. Yes, I'm game to move forward with aligning terminology but not keeping hopes too high on interopability. And yes, please tag me in the CSF4 conversation as I will be unaware of it otherwise. My main contribution will be this: In React, you can have 10 components in a file, therefore in import type { Story } from '@storybook/svelte'
import type Component from './Greeting.svelte'
export const Simple: Story<Component> = {
args: {
greeting: 'Hello World',
},
}As an aside, I'm sure you aware that Rich is pushing Svelte users towards the practice of everything coming through props (what you call args). Values, events, and snippets. I already commented about snippets (below), but this also makes things like logging events quite easy. If you provide a simple helper (demo) like this: function log_event(event_name) {
return (args) => console.log({ [event_name]: args })
}The users can use it like: import { type Story, log_event } from '@storybook/svelte'
import type Component from './Greeting.svelte'
export const Simple: Story<Component> = {
args: {
greeting: 'Hello World',
say_hello: log_event('say_hello')
},
}With the simplification mentioned at the top of this comment and with Svelte 5's updates, I think standard CSF is looking a lot more attractive for Svelte than it used to be. But that still doesn't solve the use case of component compositions and people who don't want to be bothered by creating a new component just to pass a simple snippet, so Svelte CSF may remain the desire of many. I don't know. Anyhow, keep up the good work and please don't feel the need to reply to any of this. I just wanted to jot down my thoughts. |
Beta Was this translation helpful? Give feedback.
-
@JReinhold, snippets do not have the same limitations as slots. Because snippets are just props, they can now be defined and passed in from a regular typescript file (your CSF, or Kitbook's variants/stories file). As long as Storybook does some checking and conversion when necessary, users can use a regular Svelte component as a snippet OR they can use the I'm still considering how to implement in Kitbook but I will probably end up exposing a function that let's the user explicity do the conversion from Component to snippet. Kitbook would provide an import { createRawSnippet, hydrate } from 'svelte';
import { render } from 'svelte/server';
import { browser } from "$app/environment";
export function as_snippet(component: Component) {
return createRawSnippet((props_function) => {
const props = props_function ? props_function() : {};
return {
render: () => `<div>${browser ? '' : render(component, { props }).body}</div>`,
setup(target) {
hydrate(component, { target, props })
}
}
});
}Then users could do this: import { as_snippet, type Story } from 'kitbook'
import type Component from './Greeting.svelte'
import Greet from './Greet.svelte'; // component created just to be used as a snippet
export const SomethingWithASnippet: Story<Component> = {
props: {
name: 'Michael',
greet: as_snippet(Greet)
},
}Edit: Note that Storybook could ignore the server render part in the |
Beta Was this translation helpful? Give feedback.
-
|
sveltejs/svelte#9774 is worth reading for some background though I think the above is sufficient information for our use case of passing snippets to components. |
Beta Was this translation helpful? Give feedback.
-
|
Have been building with svelte until they introduced mass surveilance tactics ( = known as telemetry ) that cannot be turned off. This was enough for me! What this has to do with this project? You are proposing to support CSF made by them. My question is: why to introduce low quality things (svelte) into product of such high quality as |
Beta Was this translation helpful? Give feedback.
-
Summary
A majority of the Svelte community considers the Svelte CSF as implemented in
@storybook/addon-svelte-csfa better way to write stories than with regular CSF. It’s closer to the syntax for writing regular Svelte components, it supports some features of Svelte that regular CSF doesn’t (such as slots and snippets), but it also comes with its own set of shortcomings.This RFC proposes making Svelte CSF a first-class citizen of Storybook, including making it the official and default way to write stories for Svelte and documenting it in the docs.
As an open-source project, Storybook relies heavily on the community to build great things, and this is no exception. Given Storybook’s current roadmap, the core team can only participate in a guiding capacity, helping the community complete this effort with PR reviews and architectural guidance. This comes with its own set of challenges, but that’s the trade-off we have to make right now.
Problem Statement
Component Story Format (CSF) is a portable standard for capturing UI component examples. It is based on ECMAScript Modules (ESM), where the default export contains metadata about the component being documented, and each named export captures a key state of that component.
This is great for JSX-based frameworks because JSX can be embedded in a regular ESM file and thus you can do everything with JSX components in CSF. However the same isn’t true for template-based frameworks like Svelte and Vue - you can’t define a Svelte component directly in an ESM-file, it has to be its own
.sveltefile. This limits what you can do in CSF without defining multiples of Svelte components in separate files just for the sake of writing stories.Svelte provides a set of APIs for mounting a component on the client - this is the API Storybook uses internally to render CSF-based stories. However this API is limited, you can’t do the same things with root Svelte components as you can with components within other components. In practice, this means that you can’t define slots in regular CSF, because there’s no way to pass a slot to a component when using Svelte’s mounting API, and thus there’s no way for Storybook to take a user’s slot and pass it to the component. The upcoming Svelte 5 introduces snippets as a replacement for slots, which have the same limitations.
@storybook/addon-svelte-csfsolves a majority of these problems by allowing users to write stories with the Svelte language (we call this “Svelte CSF”), that are then compiled behind the scenes to CSF that Storybook can understand. This is great, and even with the current lack of visibility, it’s still used in the majority of Svelte-based Storybooks today.However the addon comes with its own set of shortcomings, such as
Most prominently, there’s no clear guide on when to use Svelte CSF vs CSF, leaving newcomers confused and in the dark.
We want to solve this by making Svelte CSF a default, first-class citizen of Storybook.
Non-goals
@storybook/sveltewithout the addon, we are open to discussing this.Implementation
To solve these problems we propose the following changes:
1. Demo Project
The purpose of this project is to identify and describe the differences between regular CSF and Svelte CSF. Ideally, it should have a set of stories that uses all the features of Storybook with regular CSF, and a companion Svelte CSF version of all stories demonstrating how to do the same with Svelte CSF, or how and why this is not possible at the moment.
This project should be a separate repository in the Storybook GitHub org.
See the Deliverables section for a list of features to demonstrate.
It’s important to re-iterate that the purpose of this is not to show off how great Svelte CSF is, it’s to teach users and maintainers the differences and learn where it falls short. Hopefully, any shortcomings should be addressable in follow-up work improving Svelte CSF.
2. Document addon usage
We need to clearly document how this addon is a special case of Storybook, to not cause any confusion. I’m not sure what shape this takes, it might not be more than a few sentences or paragraph, or something else completely.
3. Convert all relevant code snippets in the docs to Svelte CSF
We have 200+ code snippets in the docs that shows CSF usage, that we should attempt to convert to Svelte CSF. This is a big lift and will happen over a longer period. This is also where the community can help out the most.
As an example, here’s how the first snippet in the Args doc could be converted:
We should incrementally add Svelte CSF code snippets as the main snippets, and remove snippets for regular CSF when they are not needed anymore. There might be specific features where we’ll intentionally keep regular CSF docs around because Svelte CSF doesn’t support them.
4. Install addon by default
This might already be covered by #27070
5. Automigration
If the documentation only documents Svelte CSF, we should write an automigration that
storiesglob to matchIt should only run on projects that don’t already have the addon installed.
6. Expose builder plugin
The Svelte CSF Addon relies on a builder plugin (Webpack and Vite) to compile Svelte CSF files to regular CSF files virtually. Storybook is starting to support non-Storybook environments like Portable Stories, and for that to work with Svelte CSF we’d need to expose this builder plugin from the package so it can be added to any configuration necessary.
7. Add stories and tests
To confidently provide support for Svelte CSF we’d want to have tests and stories in the monorepo that ensures we don’t introduce any regressions. While the addon does have some unit testing and stories, we should be able to expand on those (perhaps based on the demo project described above), but we also want to add stories and tests directly to the Svelte renderer in the monorepo.
Prior Art
No response
Deliverables
Important
If you want to contribute to any of this, just ask questions, start doing the work or open pull requests to the relevant repositories (see How to contribute). There’s no need to “reserve” a task or ask for being assigned to anything specifically before starting work on it. That system doesn’t work, often contributors reserving tasks ends up not doing them.
READMEexplaining the intent of the demo, how to use it and contribute @JReinholdstorybook initCLI: Include@storybook/addon-svelte-csfwhen initializing new projects #27070Risks
Unresolved Questions
Over the past few years, the Svelte community has strongly favoured Vite over Webpack (See npmtrends). Adding official support for Svelte CSF is a major surface area increase, and it would be beneficial to keep that surface area under control by removing support for Svelte+Webpack. However, the Svelte core team still supports Webpack and we can’t ignore that we still have Svelte+Webpack users in Storybook - albeit a very small minority.
At the moment the community is trying to add support for Svelte 5 (here, and here) in the addon. Nothing is set in stone yet but it looks like the best way forward with that would be a breaking change to the addon, only supporting Svelte 5, and using snippets instead of slots for defining stories. Furthermore the new syntax for defining meta (old vs new) is better overall so we could consider removing support for the old syntax in that same major release.
If we did this, it would be best to do this before starting any docs work, given the syntax is slightly different. On the other hand, it would alienate all existing users that can’t/won’t upgrade to Svelte 5 for whatever reason. There isn’t a lot breaking in Svelte 5 and it still supports the Svelte 4 syntax, so requiring users to upgrade might not be the worst.
Alternatives considered / Abandoned Ideas
No response
Beta Was this translation helpful? Give feedback.
All reactions