GETTING STARTED

Installation

Assisted or manual installation in React with Next.js.

kivoraWe provide the pieces.
The idea is still yours.

Choose how to get started

This page explains web installation with Next.js. Use the assistant or follow the manual steps. React without Next.js and React Native have separate guides.

Terminal

1npx @kivora/init --framework nextjs

Before you begin

Manual installation requires a Next.js project with React and React DOM 18 or later. Kivora includes compiled CSS, so this approach does not require Tailwind or PostCSS. The @kivora/init 0.1.1 assistant configures Tailwind 4.1–4.x and requires Node.js 20.19+ and Next.js 13+.

The following steps assume app/ is at the root. Preserve your existing plugins, styles and providers when integrating the configuration.

1. Install manually from npm

You can also use npx @kivora/init for assisted installation. Add --dry-run to review proposed changes before applying them. @kivora/theme is a transitive dependency; declare it as a direct dependency too if you import it in your code.

Terminal

1npm install @kivora/nextjs

2. Add the styles

The stylesheet includes component classes, tokens, base styles and bundled assets. Import it once. It needs no @source or PostCSS configuration. Use CSS or style for custom styles; new Tailwind classes need your own compiler.

app/globals.css

1@import "@kivora/nextjs/styles.css";

Optional: if your application already uses Tailwind

Use this entry instead of styles.css if you already have Tailwind 4.1+ and its compiler configured. It generates your own utilities and detects Kivora classes automatically. Do not import both entries.

app/globals.css

1@import "@kivora/nextjs/tailwind.css";

3. Configure Next.js

next.config.ts

1import type { NextConfig } from "next";
2
3const config: NextConfig = {
4  transpilePackages: ["@kivora/nextjs", "@kivora/theme"],
5};
6
7export default config;

4. Mount the provider

app/providers.tsx

1"use client";
2
3import type { ReactNode } from "react";
4import { KivoraProvider } from "@kivora/nextjs";
5
6export default function Providers({ children }: { children: ReactNode }) {
7  return <KivoraProvider colorMode="system">{children}</KivoraProvider>;
8}

5. Connect the layout

The layout can remain a Server Component. Use "use client" in components that manage state, events or browser APIs. You can now import Button and start composing.

app/layout.tsx

1import type { ReactNode } from "react";
2import Providers from "./providers";
3import "./globals.css";
4
5export default function RootLayout({ children }: { children: ReactNode }) {
6  return (
7    <html lang="es" suppressHydrationWarning>
8      <body><Providers>{children}</Providers></body>
9    </html>
10  );
11}

If you use Pages Router

Keep your existing Next.js configuration. Import @kivora/nextjs/styles.css and mount KivoraProvider in pages/_app.tsx. You do not need Tailwind, PostCSS or @source.

Continue with Button or explore the web component catalog.