v1.0.0-beta.1
GitHub

Start

Getting started

Use Nerio through package entrypoints while building the foundation, or install editable source components into an application through the registry CLI.

Install

Nerio Core 1.0.0-beta.1 is the current public beta. Unqualified installs and the beta dist-tag both resolve to this coordinated version.

pnpm add @nerio-ui/tokens@1.0.0-beta.1 @nerio-ui/adapters@1.0.0-beta.1 @nerio-ui/ui@1.0.0-beta.1 tailwindcsspnpm add -D @tailwindcss/postcss postcss
/* app/globals.css */@import "tailwindcss";@import "@nerio-ui/tokens/tailwind.css";@import "@nerio-ui/ui/styles.css";@source "../node_modules/@nerio-ui/ui/src";
import { Settings } from "@nerio-ui/adapters/icons";import { Alert, Card, Field, FormGroup, Table } from "@nerio-ui/ui";import { Button, Checkbox, Dialog, RadioGroup, Select, Switch, ToastProvider } from "@nerio-ui/ui/client";import "@nerio-ui/ui/styles.css";

@nerio-ui/ui is the server-safe entrypoint for static Core components and utilities, including Field and FormGroup. @nerio-ui/ui/client contains interactive Base UI-backed components such as Checkbox, RadioGroup, Switch, Select, and Dialog. @nerio-ui/ui/styles.css imports tokens, named keyframes, and the scoped no-Preflight compatibility rules; component visuals compile from their Tailwind recipes. Tailwind Preflight remains consumer-owned, and package source must be registered explicitly because Tailwind ignores node_modules by default. Adjust the @source path relative to your global stylesheet for other package-manager layouts.

Consumers may omit Preflight by importing only Tailwind's theme and utilities layers. Nerio's residual stylesheet remains limited to named keyframes plus scoped box-sizing and native-control typography compatibility for that mode; component visuals remain owned by static Tailwind recipes.

Import icons and icon types from @nerio-ui/adapters/icons. The adapter package has no aggregating root entrypoint: table, chart, form, and schema integrations use their dedicated subpaths and require only their matching optional peer.

Core packages ship TypeScript source. Add the Nerio packages used by your application to Next.js transpilePackages.

import type { NextConfig } from "next";const nextConfig: NextConfig = {  transpilePackages: ["@nerio-ui/adapters", "@nerio-ui/tokens", "@nerio-ui/ui"],};export default nextConfig;

The supported baseline is Node.js 22 or newer, React 19, Next.js 16.2, TypeScript 5.9, and Tailwind CSS 4.1 or newer within the v4 line. Automated browser evidence covers current Chromium, Firefox, and WebKit engine lines. See the repository's platform support policy for exact ranges and manual assistive-technology limitations.

Editable source installation

The recommended workflow installs the version-aligned Registry and CLI in the consuming project, then invokes the local nerio bin through pnpm.

pnpm add -D @nerio-ui/registry@1.0.0-beta.1 @nerio-ui/cli@1.0.0-beta.1
pnpm exec nerio initpnpm exec nerio listpnpm exec nerio info buttonpnpm exec nerio add button --dry-runpnpm exec nerio add buttonpnpm exec nerio diff buttonpnpm exec nerio update button --dry-runpnpm exec nerio doctor

The CLI writes editable source files into the consuming app. Use list and info to inspect registry contents, add --dry-run to preview files, diff and update --dry-run to review local/upstream drift, and doctor to validate configuration. The default Registry is version-aligned with the installed CLI instead of a moving branch. Successful installs record portable file hashes and dependency closure in nerio.lock.json; locally modified files are never overwritten by a normal update. nerio init detects the conventional src/app or src/pages project shape and defaults to src/components/nerio, so the documented @/components/nerio/... imports work with the standard Next.js @/* alias. Projects without a src application directory keep the components/nerio default; use --components to choose another location. Tailwind-first source installs include styles/tailwind.css; import it from a Tailwind-processed global stylesheet alongside the installed token and residual styles.

One-off CLI execution

Use the package-qualified one-off form for a quick initialization or install. Prefer the local workflow above for repeatable updates and version alignment.

pnpm dlx @nerio-ui/cli@1.0.0-beta.1 initpnpm dlx @nerio-ui/cli@1.0.0-beta.1 add button

Troubleshooting

  • Missing styles usually mean the Tailwind bridge import or package @source path is absent. Run pnpm exec nerio doctor and verify the path relative to the global stylesheet.
  • Next.js syntax or module errors from package source usually mean a used Nerio package is missing from transpilePackages.
  • Server Component errors mean an interactive primitive was imported from the wrong entrypoint. Keep static components on @nerio-ui/ui and add a client boundary for @nerio-ui/ui/client.
  • Adapter import failures require the peer for that exact subpath. Install Motion, TanStack Table, Recharts, React Hook Form, or Zod only when the matching adapter is used.
  • CLI/Registry incompatibility requires coordinated local versions. Reinstall @nerio-ui/cli and @nerio-ui/registry together.
  • Source drift is never silently overwritten. Run pnpm exec nerio diff, review update --dry-run, and resolve conflicts before applying an update.
  • If pnpm cannot resolve the nerio or nerio-mcp bin, confirm the package is installed in the project and use pnpm exec; do not call an internal package file.
  • MCP clients must run command pnpm with arguments ["exec", "nerio-mcp"] from the project containing the local package install.

Foundations

Use the canonical foundation sequence to move from token architecture and visual roles to composition, runtime behavior, accessibility, localization, and focused visual details. Every destination below is shared by documentation navigation, search, adjacent-page links, the sitemap, and the public llms.txt index.

  • Tokens — Learn how Nerio primitive, semantic, and component tokens support adaptable themes, modes, density, and product overrides.
  • Color — Choose Nerio semantic color roles, review complete state sequences, and validate custom themes across modes and accessibility preferences.
  • Typography — Understand Nerio typography tokens, semantic roles, resilience requirements, and font overrides for readable product interfaces.
  • Spacing & layout — Use Nerio spacing, density, rhythm, reflow, overflow, and direction contracts without moving product layout into Core.
  • Themes — Configure Nerio brand themes, color modes, and density through CSS variables without changing component source.
  • Accessibility — Understand Nerio accessibility invariants, product responsibilities, evidence boundaries, and validation workflow.
  • Localization — Configure LTR and RTL behavior, deterministic locale-sensitive output, and overridable Core labels in Nerio.
  • Radius — Use Nerio radius tokens and role aliases to maintain a consistent shape language across controls, containers, and overlays.
  • Effects — Use Nerio shadow, focus, and layering tokens to create calm, accessible visual hierarchy across product surfaces.
  • Motion — Apply CSS-first Nerio motion tokens or opt into the Motion adapter for advanced, accessible product animation.
  • Icons — Use the Nerio icon adapter to keep icons accessible, consistent, and independent from individual component APIs.

Principles

  • Keep Core universal, source-first, and independent from Pro packages.
  • Use semantic and component tokens before product-specific CSS.
  • Keep interactive components in client boundaries.

Contributing and releases

Read the repository's contribution guide before proposing changes. Releases follow the manual release runbook; CI validates readiness but never publishes packages, creates tags, or creates GitHub Releases.