chromaui/learnstorybook.com: the source repository behind the Storybook tutorials

What learnstorybook.com actually is, and who should clone it

This is not a package. Nothing here goes into your application's dependency tree. The repository is the source of the Storybook tutorials published at storybook.js.org/tutorials, built as a static site and written as markdown. The README describes the goal plainly: it teaches Storybook and Component-Driven Development, walking through concepts from building and testing to deployment.

The audience is therefore narrow and specific. You clone it if you are writing a chapter, translating an existing guide into another language, or fixing a code snippet in the tutorials. The README lists contributors by name and links to a page inviting you to become an open source contributor. That contributor list is the clearest statement of who the project is for.

If you are an application developer who wants to learn Storybook, you read the deployed site. Cloning this repository gives you the machinery that renders those pages, which is a different job entirely. The distinction matters because the install steps below start a Gatsby development server, not a tutorial you follow in your own project.

Two separate apps in one repository: the Gatsby site and the Storybook

The repository contains two runnable surfaces, and the README keeps them apart on purpose. The Gatsby app generates the static site. A separate Storybook instance, configured under the .storybook directory, contains the UI components used to build that site.

The README is explicit about the order of work: contributors should compose UIs in Storybook before integration with the Gatsby app. That is Component-Driven Development applied to the tutorial site itself, which is a consistent choice given what the site teaches. The scripts in package.json mirror the split: dev runs gatsby develop, storybook starts the component workshop, and build runs gatsby build with the prefix-paths flag.

Content flows through Gatsby's filesystem and markdown plugins. The dependency list includes gatsby-source-filesystem, gatsby-transformer-remark, gatsby-remark-images and gatsby-remark-code-titles, which is the standard chain for turning markdown files into pages with processed images and titled code blocks. A prebuild step runs a script to extract Storybook documentation metadata before the site builds, and a postbuild step moves the output. The build is not a single command underneath; it is a small sequence.

Running the site locally with yarn dev

The README gives two sets of local instructions, one for the Storybook and one for Gatsby. For the Gatsby site, install dependencies first, then fetch the Storybook docs metadata, then create an environment file, then start the development server.

yarn install
yarn extract-sb-docs-metadata

The extraction script lives at scripts/extract-sb-docs-metadata.sh and pulls content from the main Storybook repository, so it needs network access. The README states that the environment file is named .env.development and that it should contain one variable.

SKIP_DX_DATA=true

With that in place, yarn dev starts the Gatsby development server. The README does not print the port for the Gatsby app in the instructions, but it does tell you where to visit a guide once the server is up: http://localhost:8000/:guide, where the slug comes from the directory name you chose under /content.

If you only want the component workshop, the README's Storybook instructions are shorter: yarn install, then yarn storybook, which starts on localhost:6006. That port is stated in the README and is the one to check in a browser when the workshop does not appear.

The content directory is the real interface, and it has rules

Adding a guide means adding a directory under /content and an index.md inside it. The directory name becomes the slug in the browser, so renaming a folder later breaks any link that pointed at it. The README lists required frontmatter fields for a guide: title, heroDescription, description, overview and themeColor. Leaving one out is not a cosmetic problem; the guide page is populated from these fields.

Chapters follow a path pattern the README writes as /content/:guide/:framework?/:language/:chapter.md. The colon-prefixed parts are names you choose, and the question mark marks the framework segment as optional. That optionality is the design decision worth noticing: a guide can be framework-agnostic or framework-specific, and the directory layout encodes which. A React guide and a Vue guide for the same subject can share a guide directory and diverge below it.

After creating a chapter file, the README requires going back to the guide's frontmatter and updating the toc array with the new filename. The table of contents and the chapter order both come from that array, so a chapter that exists on disk but is absent from toc will not appear in navigation. This is a manual step with no build-time error to catch it, and it is the most likely place for a first contribution to go wrong.

Translation work and the getLanguageName helper

Translations are treated as first-class content rather than a separate system. The README says translations are welcome and points to an issue thread for details, and it notes that the Traditional Chinese translation was converted from Simplified Chinese using OpenCC, with an explicit request for help correcting idiomatic errors. That is an honest disclosure about machine-assisted translation rather than a claim of native quality.

Language directories need names consistent with those used in other guides, and there is a helper at src/lib/getLanguageName.js that turns a language directory into a human-readable name. The README states that you must update that helper when adding a language that has not been used before. This is a coupling worth flagging: the directory name is not purely a folder label, it feeds a lookup table in the app, and a missing entry means the language will not render with a proper name.

The README also gives a shortcut for translators: if you are translating a chapter that already exists in another language, skip to the second step of the chapter instructions; if you are writing a new chapter for a language that already exists, skip to the third. The steps are ordered so that translators avoid re-deciding the framework structure.

Where this repository is the wrong tool

The build depends on fetching content from another repository. The extract-sb-docs-metadata script runs as part of yarn install's lifecycle through the prebuild hook, and the README places it before the environment setup. If that external content is unavailable or its shape changes, a local build can fail for reasons that have nothing to do with the chapter you are editing. There is no documented offline mode in the README.

The repository also carries patches under a patches directory and a postinstall step that runs patch-package, which means some dependencies are modified after installation. For a contributor this is mostly invisible, but it does mean the build is sensitive to the exact dependency versions resolved by yarn.lock. Swapping in npm without regenerating a lockfile is not a path the README supports.

Most importantly, this is the wrong repository if you want a reusable documentation framework. There is no published package for the site generator, no plugin API documented in the README, and the content schema is tied to this site's frontmatter fields and its Gatsby plugins. If your goal is to publish your own tutorial series, you would be copying a site, not adopting a tool.

Compare that with Storybook itself, which is the subject the tutorials teach. Storybook is a component workshop you add to an existing project and run alongside your app; this repository is a website that explains how to do that. They share a name and a visual language, and someone searching for how to install Storybook will land on the wrong repository if they start here. The tutorials are the entry point; this codebase is the publishing machinery behind them.

Maintenance, licensing and what a chapter costs to keep

The repository is not archived, and the last push was on 2026-09-03, within the last month. That is the only maintenance signal available here; there are no retrieved releases, so there is no version history to reason about. For a content repository, that is less alarming than it would be for a library, because the artifact users consume is the deployed site rather than a tagged package.

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. MIT is permissive, and it covers the code and the text as distributed in this repository. It does not automatically grant rights over third-party assets referenced by the tutorials, and it says nothing about the Storybook project's own licensing, which is separate. That is a boundary to check with whoever owns the assets you plan to reuse, not a conclusion this article can draw for you.

The ongoing cost of a contribution is the coupling described above. A chapter is a markdown file plus a toc entry plus, for a new language, a helper update. When the tutorials track a new Storybook release, someone has to revisit the affected chapters, and the README offers no versioning scheme for chapters that describe older Storybook versions. The guides are written as current practice, which means they age with each Storybook release rather than being pinned.

Editorial conclusion

Adopt this repository only if your goal is to write or translate Storybook tutorial chapters, since the content directory and its frontmatter are the actual product. Do not clone it expecting a reusable tutorial framework or a component library for your own app. Before opening a pull request, verify that your chapter path matches /content/:guide/:framework?/:language/:chapter.md, that the guide's toc frontmatter lists your new filename, and that any new language has an entry in src/lib/getLanguageName.js.

Frequently asked questions

Official sources

1. chromaui/learnstorybook.com on GitHub
2. Issues
3. License: MIT
4. Project website
5. README