0
# Ladle React
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @ladle/react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ladle/react`
10

11
## Core Imports
12

13
```typescript
14
import { Story, Meta, useLadleContext, linkTo, ui } from "@ladle/react";
15
```
16

17
For CommonJS (not recommended):
18

19
```javascript
20
const { Story, Meta, useLadleContext, linkTo, ui } = require("@ladle/react");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import type { StoryDefault, Story } from "@ladle/react";
27
import { Button } from "./Button";
28

29
// Story file export
30
export default {
31
  title: "Components/Button",
32
  args: {
33
    children: "Click me",
34
    variant: "primary"
35
  }
36
} satisfies StoryDefault;
37

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

41
Primary.args = {
42
  variant: "primary",
43
  children: "Primary Button"
44
};
45

46
// Story with decorators
47
export const WithDecorator: Story = (args) => <Button {...args} />;
48
WithDecorator.decorators = [
49
  (Story) => (
50
    <div style={{ padding: "20px", backgroundColor: "#f0f0f0" }}>
51
      <Story />
52
    </div>
53
  )
54
];
55
```
56

57
## Architecture
58

59
Ladle is built around several key architectural components:
60

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

68
## Capabilities
69

70
### CLI Commands
71

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

74
```typescript { .api }
75
// Available as binary: ladle <command>
76
serve(options?: CLIOptions): Promise<void>;  // alias: dev
77
build(options?: CLIOptions): Promise<boolean>;
78
preview(options?: CLIOptions): Promise<void>;
79
```
80

81
[CLI Commands](./cli.md)
82

83
### Programmatic API
84

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

87
```typescript { .api }
88
// Import from specific entry points
89
import serve from "@ladle/react/serve";
90
import build from "@ladle/react/build";
91
import preview from "@ladle/react/preview";
92
import meta from "@ladle/react/meta";
93

94
// Function signatures
95
function serve(params?: CLIParams): Promise<void>;
96
function build(params?: CLIParams): Promise<boolean>;
97
function preview(params?: CLIParams): Promise<void>;
98
function meta(): any; // Returns story metadata
99
```
100

101
[Programmatic API](./api.md)
102

103
### React Components and Hooks
104

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

107
```typescript { .api }
108
// Core story components
109
const Story: React.FC<any>;
110
const Meta: React.FC<any>;
111
const Description: React.FC<any>;
112

113
// Context and hooks
114
function useLadleContext(): {
115
  globalState: GlobalState;
116
  dispatch: React.Dispatch<GlobalAction>;
117
};
118

119
// Navigation
120
function linkTo(value: string): () => void;
121
function action(name: string): (event?: any) => void;
122
```
123

124
[React Components](./components.md)
125

126
### Configuration and Types
127

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

130
```typescript { .api }
131
interface UserConfig extends RecursivePartial<Config> {
132
  stories?: string;
133
  defaultStory?: string;
134
  port?: number;
135
  outDir?: string;
136
  // ... extensive configuration options
137
}
138

139
interface StoryDefault<P = {}> {
140
  args?: Args<P>;
141
  argTypes?: ArgTypes<P>;
142
  decorators?: StoryDecorator<P>[];
143
  meta?: Meta;
144
  title?: string;
145
}
146

147
interface Story<P = {}> extends React.FC<P> {
148
  args?: Args<P>;
149
  argTypes?: ArgTypes<P>;
150
  decorators?: StoryDecorator<P>[];
151
  storyName?: string;
152
}
153
```
154

155
[Configuration & Types](./config.md)