How to Install VivekUI in Next.js App Router (and Pages Router)

`npm install @the_viveksingh/vivek-ui` — or the yarn or pnpm equivalent. There is nothing else to install. No Tailwind, no PostCSS plugin, no CVA, no clsx, no Radix. The package declares `react` and `react-dom` as peer dependencies at `^18 || ^19`, which you already have.

The package publishes both ESM and CJS builds with type declarations, and each release is verified against npm, yarn and pnpm under all three TypeScript `moduleResolution` modes — `bundler`, `node16` and legacy `node`. That combination is where most libraries quietly break, so it is worth knowing it is covered.

Import the stylesheet once, at your application's entry point. In the Next.js App Router that is `app/layout.tsx`. In the Pages Router it is `pages/_app.tsx`. In Vite or Create React App it is `src/main.tsx`. The import is `import '@the_viveksingh/vivek-ui/styles.css'`.

Once, at the entry point, is the important part. Importing it inside individual components works but means the bundler may inject it repeatedly and your ordering becomes unpredictable, which is how people end up fighting their own overrides. If you use charts, `charts.css` is a separate import at a separate subpath so applications with no charts pay nothing for them.

Import what you need directly from the package root: `import { Card, Heading, Text, Badge, Button } from '@the_viveksingh/vivek-ui'`. Composite components expose their parts as properties — `Card.Header`, `Card.Body`, `Card.Footer` — so the structure reads like the markup it produces.

Because the package is per-file ESM with `sideEffects: false`, importing `Button` alone does not pull in the rest of the library. The published size-limit figures put a lone `Button` at 771 B minified and brotlied, against 47.6 kB for importing every component at once.

If components render with no styling at all, the CSS import is almost certainly missing or in a file that is not on the render path. In the App Router it must be in a layout that actually wraps the route you are looking at — putting it in a nested layout that only covers part of the app leaves the rest unstyled.

The inverse symptom, styles appearing then being overridden by your own CSS unpredictably, is usually the same import appearing in several places. Search for `styles.css` across the repo; there should be exactly one.

A large share of the catalogue is server-safe, and wrapping a page in `'use client'` because one component needs it pushes everything else across the boundary too. Put the directive on the smallest component that genuinely needs interactivity, not on the page.

The practical approach is to build the page as a Server Component and extract the interactive island into its own file. That is exactly how the library itself is structured, which is why 49 of the 91 components can render on the server in the first place.

The instinct when a colour is wrong is to write a more specific selector or reach for `!important`. With VivekUI that is rarely necessary: theming runs on CSS custom properties, so setting the variable on `:root` or on any wrapper element changes everything beneath it.

Component classes are deliberately flat and low-specificity, so a single class of your own wins without an escalation. If you find yourself writing three-selector overrides, you are almost certainly working against the grain of the design.