JSDoc VS storybook

One of the best tools available in Web Component development is the Custom Elements Manifest. It's a JSON representation of all your available components, covering all the attributes, methods, slots and events they support, powered by your JSDoc comments and TypeScript types. You can customize the manifest generation through plugins to support custom JSDoc comments, allowing you to power more pieces of your documentation through code comments; for example, you could set up a comment format to indicate if your component is experimental or stable or provide a way to add a link to your Figma files.

I've seen several ways of annotating Javascript that IDEs seem to understand. They usually involve using comments before fields, classes, or functions.

The most compliant one seems to be using [JSDoc](https://jsdoc.app/). JSDoc is mostly intended for generating documentation. However, the Typescript compiler can validate types (and can even interoperate with Typescript definitions), if you configure it as such.

In scenarios where you HAVE to write raw Javascript but still would like to do some type validation, this is probably the best solution.

It looks a bit like this:

    /**

If you choose to use JSDoc instead of TypeScript, this only con that TypeScript has is gone, but a new one appears: JSDoc doesnt work very well with more complex types if you dont use classes to represent them.

Thanks to JSDoc it's easy to write documentation that is coupled with your code and can be consumed by users in a variety of formats. When combined with a modern publishing flow like JSR, you can easily create comprehensive documentation for your package that not only fits within your workflow, but also integrates directly in the tools your users consume your package with. This blog post aims to cover best practices when writing JSDoc-style comments to get your users up and running as quickly as possible:

Note: For simplicity, I will omit the JavaScript documentation, but for a production grade code you may want to add the documentation (see jsdoc.app website for more).

You may like JSDoc[1] if you just want some type-safety from the IDE without the compilation overhead.

It’s done wonders when I’ve had to wrangle poorly commented legacy JavaScript codebases where most of the overhead is tracing what type the input parameters are.

Personally, I’m impartial to TypeScript or JSDoc at this point. But I’d rather have either over plain JavaScript.

[1] https://jsdoc.app/

I wholeheartedly agree. At most, I introduce JSDoc[1] to newer developers as standardising how parameters and whatnot are commented at least gets you better documentation and _some_ safety without adding any TS knowledge overhead.

[1] https://jsdoc.app/

This is where JSDoc comes to save the day.

The best way to do this, of course, is with JSDoc. But something I always found awkward about jsdoc is defining the object types in the same file. So, after a lot of reading, I found a way to combine JSDoc with declaration type files from Typescript. Let me give you an example:

There is a lot of specific symbols presented on the JSDOC specification that can be found here: https://jsdoc.app

📚 4. Use Storybook (Seriously) If you’re not using Storybook for UI development, now is the time. It isolates your components from the app, which means:

Further Reading Design Systems Repo: https://designsystemsrepo.com/ Tailwind UI: https://designsystemsrepo.com/ Storybook.js: https://designsystemsrepo.com/

Storybook for UI Development

In this tutorial, you'll learn how to build a monorepo using Lerna. We’ll be building a Next.js application which will import components from a separate package. We’ll also be using Storybook to showcase those components.

Dumi. A static site generator specifically designed for component library development. Look at it as something between Storybook and Docusaurus inside the Umi world (but much better integrated between each other, presumably).

import type { Meta, StoryObj } from '@storybook/react'; import { fn } from '@storybook/test'; import { Button } from './Button'; // More on how to set up stories at: https://storybook.js.org/docs/writing-stories#default-export const meta = { title: 'Example/Button', component: Button, parameters: { // Optional parameter to center the component in the Canvas. More info: https://storybook.js.org/docs/configure/story-layout layout: 'centered', }, // This component will have an automatically generated Autodocs entry: https://storybook.js.org/docs/writing-docs/autodocs tags: ['autodocs'], // More on argTypes: https://storybook.js.org/docs/api/argtypes argTypes: { backgroundColor: { control: 'color' }, }, // Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked: https://storybook.js.org/docs/essentials/actions#action-args args: { onClick: fn() }, } satisfies Meta; export default meta; type Story = StoryObj; // More on writing stories with args: https://storybook.js.org/docs/writing-stories/args export const Primary: Story = { args: { primary: true, label: 'Button', }, };

Storybook is an open-source tool for building and testing UI components in isolation. Think of it as a dedicated workshop where you can create, preview, and document components in every possible state without spinning up the full application.

9. Storybook

GitHub Repo: https://github.com/storybookjs/storybook