Ladle: three copies of the same quick start, thirteen end-to-end fixture projects, and tests that run one at a time

Three copies of the same quick start, differing in one flag and one invocation

The README is short, and most of it is the quick start written three times. Each block creates a directory, changes into it, initialises a package, adds the component package alongside React and its renderer, creates a source directory, writes one story file with an echo command, and then starts the development server. The Here is the pnpm form, which is the shortest of the three:

mkdir my-ladle
cd my-ladle
pnpm init
pnpm add @ladle/react react react-dom
mkdir src
echo "export const World = () => <p>Hey</p>;" > src/hello.stories.tsx
pnpm ladle serve

The three blocks differ in exactly two places: the initialise step, where the yarn and npm forms pass a flag to skip the interactive prompt and the pnpm form does not, and the last line, where the package runner executes the serve command directly under yarn, under the pnpm runner, and through a one-off execution under npm. It is the clearest possible demonstration that the tool is package manager agnostic, and it is also three blocks that have to be edited together when the command changes.

The PowerShell path writes your story file as ASCII

The last thing the README does is solve a problem the other two blocks create. Writing a JavaScript file containing JSX with echo works in a POSIX shell and fails in PowerShell, where the redirection syntax differs and the quoting rules are stricter. The fix given is a here-string piped into an output-file command with an explicit encoding of ASCII. The workaround is correct and the side effect is worth noticing: the file you create on Windows is written as ASCII, so any non ASCII character in that first component, an accented label, a quotation mark, an emoji in a string, becomes a question mark or a replacement. Nothing in the README mentions this, and the file in question is the entry point most people copy verbatim. Writing the file with an editor instead would avoid it.

Thirteen fixture projects are the real configuration documentation

The workspace list in the repository manifest is the most informative page in the project. Alongside the three packages that do the real work, an example, the published package and the website, there are thirteen end-to-end projects, each isolating one configuration dimension: a Babel setup, a CommonJS setup, a configuration file, a TypeScript configuration file, CSS handling, decorators, two Playwright setups covering a plain one and a configured one, programmatic use, a provider, a design system integration, and mock service worker handling. Each is a separate workspace with its own dependency set, which means each one is installed, built and tested on every run. Read as documentation, that list is the project's answer to which setups are supported, and it is far more precise than the README.

The test script runs every project one at a time

The root test script hands off to the task runner and then immediately constrains it, asking for a concurrency of one. That single flag is the clearest statement of intent in the whole manifest. Thirteen fixture projects, several of which start development servers, cannot safely share ports, and parallelising them would produce a suite whose failures depend on scheduling. The cost is that the end-to-end suite runs strictly in sequence, so a change to one fixture cannot be checked in parallel with another. The build script has no such constraint, so the same split applies: compilation is parallel, verification is serial. The type check is a separate plain command run at the root rather than through the task runner, and the lint script targets the library, source and test directories of every workspace with warnings treated as errors.

Releases go through a shell script while the root manifest sits at version zero

The versioning model is worth understanding before you depend on the package. The root manifest is private and versioned zero, which is normal for a workspace root, and the published releases are tagged per scoped package rather than once for the repository. The release itself is a shell script: the manifest's release entry runs a script in the repository root, and the repository carries a changesets directory, which is the mechanism that turns conventional commits into version bumps and a changelog. So nothing about the release process is visible in the manifest beyond the name of a script, and the two most recent releases visible are a month and then half a year apart, while the default branch's last commit is more recent than the newest tag. That gap is normal for a repository using changesets, and it is the reason you pin a package version rather than a branch.

Node is pinned in three places, and the floor is recent

The engine requirement in the manifest asks for Node 22.12 or newer, which is a floor rather than a suggestion. Two other files at the repository root reinforce it: a Node version file, which tools read to pick an interpreter, and a dev container configuration, which is how the maintainers expect contributors to get a matching environment. A fourth pin sits in the package manager field, which names an exact release of the package manager rather than a range. None of this is unusual for a tool that has to drive a bundler, a test runner and a browser automation stack, but together they mean the project is opinionated about its toolchain in a way that will show up the first time someone tries to run it on a distribution's default Node. The type system and the linter are pinned to recent major versions for the same reason.

The demo is hosted on someone else's pages domain

The link row at the top of the README points at the documentation site, a demo, a social account, a StackBlitz link that opens a new project, and a chat invite. The demo is the interesting one, because its address is not on the project's own domain: it points at a pages subdomain belonging to a component library called react-movable. So the one thing a visitor is invited to click to see the tool running is hosted by a third party, which means the demo can be out of date, can move, or can disappear without the repository changing. The StackBlitz link is the more durable of the two, since it creates a live project from the repository itself. The rest of the repository root is conventional: hook and staged-file configuration, a commit message linter configuration, a security policy, a declaration file for stylesheet imports and a directory of type level tests.

Editorial conclusion

Ladle fits a team that wants a lightweight component playground without adopting a full storybook toolchain, and that keeps its e2e matrix honest. Four things to know before you commit. The supported configuration surface is not in the documentation, it is in the thirteen fixture projects in the repository, so read those before assuming your Babel, TypeScript or CSS setup works. The test script runs every project with a concurrency of one, so the suite is serialized and slow by design. Your Node version is pinned in three separate places and the engine requirement is recent. And the Windows quick start writes your first source file as ASCII, which will not survive a component with a non ASCII string in it.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tajo/ladle on GitHub