[Svelte] Storybook autodocs + svelte 5

[tobiasBora]

Summary

I feel really dumb but I can't find where to write the documentation for my svelte 5 (sveltekit) components so that it is picked by autodocs in storybook. I tried for instance to write:

<!--
     @component This is a very quick component description.
-->

at the top of my component but it is not recognized since I can still only read "More on writing stories with args: https://storybook.js.org/docs/writing-stories/args" at the top of my component. I also tried:

  /**
                  @component This is a very quick component description
   */

in the typescript block without luck. Similarly, how am I supposed to document $props? Can I write some doc in the typescript type and make it visible in the doc itself? It seems like storybook can't infer the type from the typescript itself.

I tried to go in https://github.com/storybookjs/storybook/tree/next/code/addons/docs/docs/frameworks but svelte is not listed there in the list of frameworks.

Additional information

No response

Create a reproduction

No response

[dosubot[bot]]

Hi @tobiasBora! I'm Dosu and I’m helping the storybook team.

Storybook does support Svelte 5 autodocs, but there's an important limitation: @component tags for component-level descriptions are not currently supported. The docgen system focuses on prop-level documentation only. Component-level descriptions are planned for the community-driven svelte-docgen project.

For documenting $props, use JSDoc or TypeScript comments on your props interface:

interface Props {
  /** The name of the user */
  name: string;
  /** The user's age (optional) */
  age?: number;
}

let { name, age = 25 }: Props = $props();

This will generate an args table showing types, descriptions, and default values. Type inference from TypeScript is supported and enabled by default in @storybook/svelte-vite and @storybook/sveltekit.

Make sure you're on Storybook 8.4+ which introduced improved Svelte TypeScript support.

Could you share:

1. What Storybook version you're using?
2. A minimal reproduction showing how your component and story are set up?

This will help determine if there's a configuration issue or a specific bug at play.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[tobiasBora]

Ok thanks, the props work, but indeed I can't find a way to recognize the description of the whole component, I'll create a bug report then. Also, is it possible to "unfold" the typescript type? For now it prints DiagramConf, but this is itself a complex object-like structure that I'd like to document in storybookjs.

[dosubot[bot]]

Unfortunately, Storybook cannot automatically unfold complex TypeScript types like DiagramConf to show their nested properties in the args table. This is a requested feature but not yet available.

The workaround is to manually define argTypes for complex object props:

argTypes: {
  diagramConf: {
    description: 'Configuration object for the diagram',
    control: 'object',
    table: {
      type: { summary: 'DiagramConf', detail: '{ width: number; height: number; ... }' },
    },
  },
}

You can use the table.type.detail field to provide a longer type description that appears on hover/expand. For richer documentation of nested structures, you may want to consider supplementing with an MDX docs page.

The svelte-docgen project is working on improved type extraction, but expanded nested types aren't part of the current scope.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[aniruddhaadak80]

@tobiasBora Svelte 5 support is still maturing in Storybook.
For autodocs to pick up descriptions:

1. Ensure you are using the latest @storybook/svelte-vite (8.x).
2. For runes mode, Storybook currently relies on svelte-docgen or react-docgen analysis which might lag behind the new syntax.
3. Try adding JSDoc comments directly above the $props() text or the interface definition if you are using TS.

/**
 * My component description
 */
<script lang="ts">
  interface Props {
    /** Prop description */
    foo: string;
  }
  let { foo }: Props = $props();
</script>

If that fails, using tags: ['autodocs'] in the story file usually forces the page generation, but extracting the text content from Svelte 5 source might need the very latest prerelease of the adapter.

[tobiasBora]

Thanks for your answer. So with this the props description does work, but not the component description. Worse, if I put it as you do it have issues because then it is not recognized as a comment (this is in the html part, not js) so it ends up in the page when rendering! I also tried to put it inside the <script> without much success. You also mention I should have the latest @storybook/svelte-vite which is 8.x… but I have an even more recent one "@storybook/svelte-vite": "10.2.17". You also mention svelte-docgen but I don't have it installed (while props do work), should I manually install it, and if so what do I need to do to configure it properly? (it seems like this project is not maintained anymore no?)