Configuration

Learn how to configure React Showroom to fit your use case.

Config Format​

You can declare a static object or a function call that return the object.

Config Intellisense​

Use defineConfig identity function which should provide intellisense automatically.

It is also recommended (but not required) to add // @ts-check comment at the top of the file so any misconfiguration will be reported by your editor.

Config Options​

components​

• Type: string
• Default: 'src/components/**/*.{ts,tsx}' if items is not provided.

A glob pattern string to search for all your components.

If you want to organize your components in a nested structure, use items.

imports​

• Type: Array<{ name: string; path: string; } | string>

Modules to be available in examples via import.

Pass name (how it is imported) and path (relative path from project root).

For example, if all your components should be imported with '@/components', which is a file at src/components/index.ts in your project, then add the following configuration:

build.outDir​

• Type: string
• Default: 'showroom'

Output folder for the generated site.

build.prerender​

• Type: boolean
• Default: true

Enable pre-rendering for example.

This is useful to ensure your components are SSR-friendly.

build.basePath​

• Type: string
• Default: '/'
• Example: '/docs'

Set a prefix for the static site if your site is hosted at a subpath.

theme.title​

• Type: string
• Default: 'React Showroom'

Title to be displayed for the site.

devServer.port​

• Type: number
• Default: 6969

Port for the React Showroom Dev Server.

Advanced Config Options​

items​

• Type: Array<ItemConfiguration>

An array of items to be shown on the sidebar, which can be one of the following 5 types.

Component Item​

A group of components.

Example:

Content Item​

A markdown file.

Example:

Link Item​

A link (internal or external).

Example:

Doc Item​

A group of markdown files.

Example:

Group Item​

A grouping of items, which can contain more items.

Example:

assetDir​

• Type: string

Your application static assets folder to be accessible at "/" in the style guide server.

When generate the static site, those files will be copied into the output folder.

require​

• Type: Array<string>

Modules that are required for your style guide. Useful for third-party styles or polyfills.

This is the preferred way to load global CSS, such as TailwindCSS.

wrapper​

• Type: string | undefined

Path to a module/file that export default a React component to wrap the entire showroom.

Use this to render context providers that your application need, e.g. Redux Provider.

cacheDir​

• Type: string | false
• Default: '.showroom_cache'

Cache directory for the build.

Pass false to disable caching.

ignores​

• Type: Array<string>
• Default: ['**/__tests__/**', '**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}','**/*.d.ts']

Patterns to ignore for components.

skipEmptyComponent​

• Type: boolean | undefined

Ignore components that don't have an example file nor props definition other than defined in '@types/react'.

example.dimensions​

• Type: Array<string | { width: number; height: number | '100%'; name?: string; }>
• Default: ['iPhone 6/7/8', 'iPad', 'Macbook Air']

Dimensions for the previews in example standalone view. The value could be an object with width, height, and name properties, or one of the preset device names.

Also will be used to display markers for code examples with frame modifier, like below:

example.showDeviceFrame​

• Type: boolean
• Default: true

Whether the previews in example standalone view should be wrapped with device frame.

example.widths​

• Type: Array<number>

Widths for the preview in example standalone view.

Use example.dimensions instead.

example.placeholder​

• Type: string | undefined

Path to a module/file that export default a React component as placeholder when there is no example file for the component.

The component will receives componentFilePath prop (string).

search.includeHeadings​

• Type: boolean
• Default: true for build, false for dev

Whether the search results should include headings of markdowns.

By default we disable this for dev command to reduce recompilation overhead, but you can force it to be always true.

theme.audienceToggle​

• Type: 'design' | 'code' | false
• Default: 'design'

Default value for the audience toggle.

Set to false if you do not want to show the toggle, which means it will always be 'code'.

theme.serviceWorker​

• Type: boolean
• Default: true

Include a service worker to provide offline fallback.

Disable it if it interferes with other service worker you need, e.g. msw.

theme.favicon​

• Type: string | undefined

Path to your site favicon.

Example, if your favicon is in asset/img/favicon.ico:

theme.codeTheme​

• Default: require('prism-react-renderer/themes/nightOwl')

One of the themes provided by 'prism-react-renderer'.

theme.resetCss​

• Type: boolean
• Default: true

By default we include modern-normalize. You can disable it if you already include your own CSS reset.

theme.colors​

Customize the primary color.

Should be an object with the following shape:

theme.navbar​

An object to customize your navigation bar.

Example: