or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

api.mdcli.mdcomponents.mdconfig.mdindex.md
tile.json

tessl/npm-ladle--react

A fast and lightweight React component development environment for building and sharing components.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@ladle/react@5.0.x

To install, run

npx @tessl/cli install tessl/npm-ladle--react@5.0.0

index.mddocs/

Ladle React

Ladle is a fast and lightweight React component development environment that serves as a modern alternative to Storybook. It provides a streamlined way to develop, test, and share React components with built-in support for hot reloading, accessibility testing, MSW mocking, and comprehensive TypeScript integration.

Package Information

  • Package Name: @ladle/react
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @ladle/react

Core Imports

import { Story, Meta, useLadleContext, linkTo, ui } from "@ladle/react";

For CommonJS (not recommended):

const { Story, Meta, useLadleContext, linkTo, ui } = require("@ladle/react");

Basic Usage

import type { StoryDefault, Story } from "@ladle/react";
import { Button } from "./Button";

// Story file export
export default {
  title: "Components/Button",
  args: {
    children: "Click me",
    variant: "primary"
  }
} satisfies StoryDefault;

// Individual story
export const Primary: Story = (args) => <Button {...args} />;

Primary.args = {
  variant: "primary",
  children: "Primary Button"
};

// Story with decorators
export const WithDecorator: Story = (args) => <Button {...args} />;
WithDecorator.decorators = [
  (Story) => (
    <div style={{ padding: "20px", backgroundColor: "#f0f0f0" }}>
      <Story />
    </div>
  )
];

Architecture

Ladle is built around several key architectural components:

  • Story System: File-based story organization with default exports for metadata and named exports for individual stories
  • CLI Interface: Command-line tools for serving, building, and previewing component libraries
  • Programmatic API: Node.js functions for integrating Ladle into build pipelines and custom workflows
  • React Components: Built-in UI components and hooks for story enhancement and interaction
  • Configuration System: Flexible configuration via .ladle/config.mjs files
  • Build System: Vite-powered fast development and production builds with hot module replacement

Capabilities

CLI Commands

Command-line interface for development, building, and deployment workflows. Includes serve, build, and preview commands with extensive configuration options.

// Available as binary: ladle <command>
serve(options?: CLIOptions): Promise<void>;  // alias: dev
build(options?: CLIOptions): Promise<boolean>;
preview(options?: CLIOptions): Promise<void>;

CLI Commands

Programmatic API

Node.js API for integrating Ladle functionality into custom build processes and development workflows.

// Import from specific entry points
import serve from "@ladle/react/serve";
import build from "@ladle/react/build";
import preview from "@ladle/react/preview";
import meta from "@ladle/react/meta";

// Function signatures
function serve(params?: CLIParams): Promise<void>;
function build(params?: CLIParams): Promise<boolean>;
function preview(params?: CLIParams): Promise<void>;
function meta(): any; // Returns story metadata

Programmatic API

React Components and Hooks

Story components, context providers, navigation hooks, and built-in UI components for creating interactive component documentation.

// Core story components
const Story: React.FC<any>;
const Meta: React.FC<any>;
const Description: React.FC<any>;

// Context and hooks
function useLadleContext(): {
  globalState: GlobalState;
  dispatch: React.Dispatch<GlobalAction>;
};

// Navigation
function linkTo(value: string): () => void;
function action(name: string): (event?: any) => void;

React Components

Configuration and Types

Comprehensive configuration system with TypeScript types for stories, arguments, metadata, and global configuration.

interface UserConfig extends RecursivePartial<Config> {
  stories?: string;
  defaultStory?: string;
  port?: number;
  outDir?: string;
  // ... extensive configuration options
}

interface StoryDefault<P = {}> {
  args?: Args<P>;
  argTypes?: ArgTypes<P>;
  decorators?: StoryDecorator<P>[];
  meta?: Meta;
  title?: string;
}

interface Story<P = {}> extends React.FC<P> {
  args?: Args<P>;
  argTypes?: ArgTypes<P>;
  decorators?: StoryDecorator<P>[];
  storyName?: string;
}

Configuration & Types