Installation and Imports

Boreal UI ships two runtime packages and optional documentation metadata:

@boreal-ui/core for standard React apps.
@boreal-ui/next for Next.js apps, including app-router projects.
@boreal-ui/docs for documentation sites, prop tables, and developer tooling.

Install

Choose one runtime package:

npm install @boreal-ui/core
npm install @boreal-ui/next

Component declarations work automatically through the selected runtime package. If application code imports shared declarations directly from @boreal-ui/types, declare it as a dev dependency so strict package managers can resolve that import:

npm install -D @boreal-ui/types

Boreal UI expects these peer dependencies in the consuming app:

npm install react react-dom marked

Next.js apps should also install next.

Install generated prop metadata only when it is needed:

npm install @boreal-ui/docs

React Setup

Import the core stylesheet once near the top of your app.

import "@boreal-ui/core/globals.css";

Then import components from the core build.

import { Button, Card, TextInput } from "@boreal-ui/core";

export function ProjectForm() {
  return (
    <Card title="New project" theme="primary" shadow="medium">
      <TextInput label="Project name" name="projectName" />
      <Button type="submit">Create project</Button>
    </Card>
  );
}

Next.js Setup

Import the Next stylesheet once from app/layout.tsx, pages/_app.tsx, or another global stylesheet loaded by the app.

import "@boreal-ui/next/globals.css";

Next.js starter projects often include this broad reset in the app's default globals.css:

* {
  box-sizing: border-box;
  padding: 0;
  margin: 0;
}

Avoid loading that reset after Boreal styles. The universal padding and margin rules can override spacing that Boreal components and nested content rely on. Prefer a narrower global override that keeps box sizing predictable without removing spacing from every element:

html {
  box-sizing: border-box;
}

*,
*::before,
*::after {
  box-sizing: inherit;
}

body {
  margin: 0;
}

If your app needs additional layout resets, scope them to your own shell classes instead of applying them to every element globally.

Boreal globals leave root scrolling at the browser default (auto) so Next.js can restore scroll position during route transitions without warnings. If your application deliberately sets scroll-behavior: smooth on html, add data-scroll-behavior="smooth" to the root <html> element as described by the Next.js scroll behavior guidance.

The CLI can create or repair that safer baseline for Next.js apps:

npx @boreal-ui/cli@latest init --framework next --recommended-globals

Interactive Next.js setup prompts for this by default. Use --recommended-globals to apply it without the prompt, or --no-recommended-globals to skip it.

For the full command reference, options, prompts, and generated file changes, see the CLI guide.

Use the Next build for components.

"use client";

import { Button, Card, TextInput } from "@boreal-ui/next";

export default function ProjectForm() {
  return (
    <Card title="New project" theme="primary" shadow="medium">
      <TextInput label="Project name" name="projectName" />
      <Button type="submit">Create project</Button>
    </Card>
  );
}

Use "use client" in your own Next.js component when you render Boreal components inside a file that uses browser-only behavior, events, hooks, local state, or context. Boreal's Next entry points preserve their own client boundaries.

Next.js Server Components

Static UI can use the dedicated server barrel or per-component server paths without adding a client boundary:

import {
  BreadCrumbPageHeader,
  Card,
  Container,
  MetricBox,
  Timeline,
} from "@boreal-ui/next/server";
import ValidationSummary from "@boreal-ui/next/server/ValidationSummary";

Normally interactive server entries deliberately omit callbacks and client-managed behavior. See Next.js Server Components for the complete entry list, stripped behavior, and examples.

Standalone Component Imports

Standalone imports are available when you want a narrower import path. Prefer them in bundle-sensitive applications so the build only follows the selected component entry points and their style sidecars.

import Button from "@boreal-ui/core/Button";
import Card from "@boreal-ui/next/Card";

Standalone paths follow the same core/next split:

import DataTable from "@boreal-ui/core/DataTable";
import NextDataTable from "@boreal-ui/next/DataTable";

Public API Entry Points

Entry point	Purpose
`@boreal-ui/core`	React components, theme APIs, style config, and public types.
`@boreal-ui/next`	Next.js wrappers with the same public API shape.
`@boreal-ui/next/server`	Static React Server Component barrel for Next.js.
`@boreal-ui/next/server/MetricBox`	Standalone Next.js server component import.
`@boreal-ui/core/Button`	Standalone core component import.
`@boreal-ui/next/Button`	Standalone Next component import.
`@boreal-ui/core/globals.css`	Core global CSS import.
`@boreal-ui/next/globals.css`	Next global CSS import.
`@boreal-ui/types`	Shared public type declarations.
`@boreal-ui/types/core/Button`	Core component prop declarations.
`@boreal-ui/types/next/Button`	Next component prop declarations.
`@boreal-ui/docs`	Optional generated component prop metadata for docs tools and prop tables.
`@boreal-ui/core/registerColorScheme`	Standalone color-scheme registration helper for React consumers.
`@boreal-ui/next/registerColorScheme`	Standalone color-scheme registration helper for Next consumers.

For a complete list of barrel exports, standalone component paths, and generated prop-doc objects, see Public API Reference.

Choosing Core or Next

Use core when the app is a Vite, CRA, Remix, Astro, or other React application that can consume normal React components and global CSS.

Use next when the app is a Next.js app. The Next wrappers use SCSS Modules internally and preserve client-boundary behavior expected by Next.js.

Do not mix core and next imports in the same component tree unless you have a specific migration reason. Pick one build per app shell so styles, class names, and bundler behavior stay predictable.