Installation

Kuma UI is compatible with React 18 and above. If you're using an older version of React, you'll need to upgrade first (opens in a new tab).

Install packages

To install Kuma UI in your project, run one of the following commands in your terminal:

npm install @kuma-ui/core

Once the @kuma-ui/core package is successfully installed, you can proceed to install a plugin for your specific framework (Next.js or Vite) as below.

pnpm install -D @kuma-ui/next-plugin

Setting Up Kuma UI

Once you've installed the plugin, you need to configure it in your configuration file.

next.config.js

const { withKumaUI } = require("@kuma-ui/next-plugin");
 
/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};
 
module.exports = withKumaUI(nextConfig, {
  // The destination to emit an actual CSS file. If not provided, the CSS will be injected via virtual modules.
   outputDir: "./.kuma" // Optional
   // Enable WebAssembly support for Kuma UI. Default is false and will use Babel to transpile the code.
   wasm: true // Optional
});

Server Side Rendering

If you are using Kuma UI with Next.js, setting up Server Side Rendering (SSR) isn't mandatory. However, without this setup, you may experience a Flash Of Unstyled Content (FOUC). We highly recommend setting up SSR to prevent this from happening.

app/layout.tsx

import { KumaRegistry } from "@kuma-ui/next-plugin/registry"
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <KumaRegistry>{children}</KumaRegistry>
      </body>
    </html>
  );
}

Integrate with Storybook

For those looking to integrate Kuma UI with Storybook, the process will vary depending on the Storybook builder (opens in a new tab) you are using. Here's how you can set it up:

If your project uses Storybook Webpack builder (including @storybook/nextjs), you can use "@kuma-ui/webpack-plugin".

// .storybook/main.ts
 
import KumaUIWebpackPlugin from "@kuma-ui/webpack-plugin";
 
// ...
 
const config: StorybookConfig = {
  // ...
  webpackFinal: (config) => {
    config.plugins = [...(config.plugins ?? []), new KumaUIWebpackPlugin()];
 
    return config;
  },
  // ...
};
 
// ...

For more information, refer to the Working with Webpack plugins (opens in a new tab) section in the Storybook documentation.

Overview Utility First