NPM Registry

The @cloudflare/kumo package is published to the public npm registry. No special configuration is required for installation.

Install Package

Install Kumo using your preferred package manager. The current version is vlatest.

npm

npm install @cloudflare/kumo

pnpm

pnpm add @cloudflare/kumo

yarn

yarn add @cloudflare/kumo

Peer Dependencies

Kumo requires the following peer dependencies. Most React projects will already have these installed:

# Required peer dependencies
pnpm add react react-dom @phosphor-icons/react

Import Components

Import components from the main package or use granular imports for better tree-shaking:

Main Package Import

Granular Import (Recommended)

Base UI Primitives

Kumo is built on top of Base UI, a library of unstyled, accessible React components. For advanced use cases where you need access to the underlying primitives, Kumo re-exports all 37 Base UI components with both barrel and granular imports:

Barrel Import (Convenient)

// Import multiple primitives at once

Granular Imports (Recommended for Performance)

// Import individual primitives for better tree-shaking

Granular imports result in smaller bundle sizes by only including the primitives you actually use.

Import Styles

Kumo provides two CSS distribution options depending on your setup:

For Tailwind CSS Users (Recommended)

If your application uses Tailwind CSS, add Kumo's source files to your content configuration and import the styles. Import order matters — Kumo styles must come before @import "tailwindcss" so that Kumo's theme tokens are registered first:

/* app.css or main.css */
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";

/* Your custom styles */

Note: You can also use the default export @cloudflare/kumo/styles which is equivalent to styles/tailwind.

For Non-Tailwind Users (Standalone)

If your application doesn't use Tailwind CSS, use the standalone build which includes all compiled styles:

// In your app entry point (e.g., main.tsx, index.tsx)

The standalone build includes all Tailwind utilities and Kumo component styles pre-compiled. No Tailwind configuration needed!

Usage Example

Here's a complete example of using Kumo components with Tailwind CSS:

CSS File (app.css)

@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";

Note: The @source path is relative to your CSS file. Adjust it based on your project structure.

Component File (App.tsx)

export default function App() {
  return (
    <LayerCard className="rounded-lg p-6">
      <h1 className="mb-4 text-2xl font-bold">Welcome to Kumo</h1>
      <Input placeholder="Enter your name..." className="mb-4" />
      <Button variant="primary">Submit</Button>
    </LayerCard>
  );
}

Blocks vs Components

Kumo provides two types of building blocks for your application:

Components (NPM Exports)

Components are published as NPM exports and can be imported directly from the package. These are the core UI primitives like Button, Input, and Dialog.

Use components when you need consistent, pre-styled UI primitives that integrate seamlessly with your application. Components are versioned, tree-shakeable, and receive automatic updates.

Blocks (CLI Installation)

Blocks are higher-level compositions (like PageHeader and ResourceListPage) that are installed via the Kumo CLI. Blocks give you full ownership of the code, allowing you to customize them to your specific needs.

# Initialize Kumo configuration

npx @cloudflare/kumo init

# List available blocks

npx @cloudflare/kumo blocks

# Install a block

npx @cloudflare/kumo add PageHeader

After installation, blocks live in your project (e.g., src/components/kumo/) and can be customized as needed. The CLI automatically transforms imports from relative paths to @cloudflare/kumo for seamless integration.

Utilities

Kumo also exports utility functions for common tasks:

// Merge class names with Tailwind
const className = cn("base-class", condition && "conditional-class");

// Generate safe random IDs
const id = safeRandomId();

// Configure link component for your framework (maps href to your router)
<LinkProvider component={YourAppLink}>{/* Your app */}</LinkProvider>;