Skip to main content

Config

Ladle does not require any configuration and some features can be controlled through CLI parameters. However, more advanced setups might require some configuration. There are three different files you can create and use:

  • .ladle/components.tsx, used in browser only to enhance your stories or provide them a context
  • .ladle/config.mjs, used in browser and CLI to configure things like the story search pattern or addons visibility
  • vite.config.{js|mjs|ts}, used only by Vite (CLI node environment) to change any parameters of the compilation (things like aliasing, dependency pre-bundling, babel plugins...) and some aspects of the dev server (open browser on start...). You should get familiar with Vite docs!

vite.config.{js|mjs|ts}

  • Documentation.
  • The parameter root is replaced so Ladle can function properly.
  • server.port and build.outDir are overridden by Ladle as well, so they can be configured separately from your main project since you probably don't want them to clash.
  • Vite config assumes that paths are relative to the project root; however, Ladle's root is buried in node_modules. You should always use absolute paths. Ladle tries to resolve relative paths relative to the project root but that doesn't work when configuring custom plugins for example.
  • Ladle adds @vitejs/plugin-react and vite-tsconfig-paths plugins by default. If you need to customize them (for example adding babel presets into the React plugin), you can add them for yourself and Ladle will use yours.

.ladle/config.mjs

stories

We use globby, go there to learn about all possible search patterns. Ladle uses this parameter to find story files in your project.

export default {
stories: "src/**/control.stories.{js,jsx,ts,tsx}",
};

port

Specify the dev server port.

export default {
port: 61000,
};

previewPort

Specify the preview server port.

export default {
previewPort: 8080,
};

outDir

Specify the output directory (relative to the project root).

export default {
outDir: "build",
};

defaultStory

Change which story is loaded when Ladle starts. It's the ?story= portion of URL. The default value is "" - open the first story in alphabetical order.

export default {
defaultStory: "a11y--welcome",
};

viteConfig

Override the path for the Vite config. By default, vite.config.{js|mjs|ts} and vite.config.ts in the project root are being checked.

export default {
viteConfig: process.cwd() + "/ladle-vite.config.ts",
};

base

Base path for building the output; useful for e.g. hosting your project's storybook on GitHub Pages:

export default {
base: "/my-project/",
};

mode

Vite mode. If not set, defaults to development when developing and production for building static output.

This also affects Vite's .env file loading, as well as anything else setting mode affects.

export default {
mode: "my-custom-mode",
};

addons

You can enable or disable all Ladle addons (the buttons in the left bottom corner). You can also control their default state.

export default {
addons: {
a11y: {
enabled: true,
},
control: {
enabled: true,
defaultState: {},
},
ladle: {
enabled: true,
},
mode: {
enabled: true,
defaultState: "full",
},
rtl: {
enabled: true,
defaultState: false,
},
source: {
enabled: true,
defaultState: false,
},
theme: {
enabled: true,
defaultState: "light",
},
width: {
enabled: true,
options: {
xsmall: 414,
small: 640,
medium: 768,
large: 1024,
},
defaultState: 0,
},
},
};

Do you want to work on Ladle and other web tooling? Our team at Uber is hiring!