UnflowUI
Getting Started

Installation

Add UnflowUI packages to your project and configure the required dependencies.

Prerequisites

UnflowUI requires:

  • React 19 or later
  • Tailwind CSS v4 with PostCSS
  • Node.js 20 or later

Authenticate with GitHub Packages

The @unflowio/* packages are published to GitHub Packages, not the public npm registry. Add an .npmrc next to your app's package.json:

@unflowio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

GITHUB_TOKEN is a GitHub token with the read:packages scope (a personal access token locally, the workflow token in CI).

Install packages

bun add @unflowio/ui @unflowio/tokens

@unflowio/icons and @unflowio/utils are optional: install them when your app uses icons or utilities directly.

Import the stylesheet

Add one import to your root stylesheet, after Tailwind:

/* app/globals.css */
@import 'tailwindcss';
@import '@unflowio/ui/css';

@unflowio/ui/css brings in the design tokens (@unflowio/tokens/css) and a Tailwind @source that points at the shipped component files, so Tailwind generates every utility the components use. You do not need your own @source for UnflowUI.

Import a component

Components are imported by path, one entry per component. The package root exports utilities, types and i18n only, so importing a component never pulls the whole library into your bundle.

import { Button } from '@unflowio/ui/components/Button';
import { Badge } from '@unflowio/ui/components/Badge';

Next.js App Router

Every component that uses state, effects or event handlers ships with a "use client" directive, so you can import it straight into a Server Component without wrapping it in a client module of your own:

// app/page.tsx (a Server Component)
import { Button } from '@unflowio/ui/components/Button';

export default function Page() {
  return <Button label="Continue" />;
}

Server Components cannot pass functions to client components. Props such as onClick or onChange still need a client component of yours, the usual App Router rule. Purely presentational components (for example Badge, Skeleton, Spinner and the Table parts) have no directive and render on the server.

Set up i18n

Components have built-in translations in en, pt and es.

Your app has no i18next setup. Nothing to do: UnflowUI uses its own instance, in English. To switch language, call it from a client component:

import { i18n } from '@unflowio/ui';

i18n.changeLanguage('pt');

Your app already uses i18next. Merge the UnflowUI resources into your instance once, where you initialise it:

import i18n from 'i18next';
import { addUnflowResources } from '@unflowio/ui';

addUnflowResources(i18n);