Liminal UI

Guide

Installation

How to install and configure Liminal UI in your React project

Installation

This guide walks you through installing the Liminal UI CLI, initializing your project, and adding your first components. You can use npm, pnpm, yarn, or bun.

Prerequisites

  • Node.js 18+
  • A React 18+ project (Next.js, Vite, Remix, Create React App, etc.)
  • Tailwind CSS already configured (see Tailwind setup if needed)

Install the CLI

Install the Liminal UI CLI globally so you can run liminal from any directory:

npm install -g @liminal-ui/cli

Alternatively, run commands without a global install using npx or pnpm dlx:

bash
npx @liminal-ui/cli init

Initialize your project

From the root of your React project, run:

npx @liminal-ui/cli init

If you installed the CLI globally, you can run:

bash
liminal init

The wizard will ask:

  • TypeScript: Are you using TypeScript?
  • React Server Components: Are you using RSC? (e.g. Next.js App Router)
  • Components path: Where to put UI components (default: src/components/ui)
  • Utils path: Where to put shared utilities (default: src/lib)

After this, you’ll have a components.json config and the folder structure ready for components.

Example: components.json

Initialization creates a components.json file in your project root. It might look like this:

json
{
  "$schema": "https://liminal-ui.com/schema.json",
  "style": "default",
  "tsx": true,
  "rsc": false,
  "components": "src/components/ui",
  "utils": "src/lib",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib"
  }
}

You can edit this file to change paths or options; the CLI reads it when you run liminal add.

Project structure after init

A typical structure after running liminal init and adding a few components:

tsx
your-app/
├── components.json
├── src/
│   ├── components/
│   │   └── ui/          # Components added with `liminal add`
│   │       ├── button.tsx
│   │       └── ...
│   └── lib/
│       └── utils.ts      # cn() and other helpers

Path aliases (e.g. @/components/ui) must be configured in your build tool (see framework sections below).

Add components

Add components one by one with:

npx @liminal-ui/cli add button

With the CLI installed globally:

bash
liminal add button

The CLI will copy the component source into your configured components path and install any required dependencies (e.g. Ark UI). You can then import and use it:

tsx
import { Button } from "@/components/ui/button";

export default function Page() {
return (
  <Button variant="outline" size="lg">
    Get started
  </Button>
);
}

Replace button with any component name from the components list (e.g. liminal add dialog, liminal add tabs).

Framework-specific setup

Next.js

  • App Router: Ensure tsconfig.json (or jsconfig.json) has path aliases, e.g. "@/*": ["./src/*"]. Next.js uses this for @/components and @/lib.
  • Tailwind: If you use tailwind.config.ts, ensure content includes your components path so Tailwind can see the classes used in Liminal UI components.

Vite

  • In vite.config.ts, add resolve alias if not already present, for example: resolve: { alias: { "@": path.resolve(__dirname, "./src") } }
  • Ensure tsconfig.json has "paths": { "@/*": ["./src/*"] } so types resolve.

Remix

  • Use Remix’s built-in alias support (e.g. ~ or @) and point it to your app directory. Set the same path in components.json (e.g. app/components/ui) so the CLI writes files where your aliases expect them.

Manual installation

If you prefer not to use the CLI, you can copy component source files from the Liminal UI repository into your project. You’ll need to:

  1. Copy the component file(s) (e.g. button.tsx) into your UI folder.
  2. Ensure cn and any other utilities from @/lib/utils exist.
  3. Install Ark UI and other dependencies listed in the component or in the repo’s package.json.

The CLI automates this and keeps paths consistent with your components.json.

Troubleshooting

"Command not found: liminal"
Install the CLI globally (see Install the CLI above) or use npx @liminal-ui/cli / pnpm dlx / bunx instead of liminal.

Path alias errors (e.g. @/components/ui not found)
Check that your build tool and tsconfig.json (or jsconfig.json) define the same alias you use in imports. For example, if you use @/*, it must resolve to the directory that contains components and lib.

Tailwind classes not applied
Ensure your Tailwind content (or equivalent) includes the paths where Liminal UI components live (e.g. src/components/**/*.{ts,tsx}). Otherwise Tailwind won’t see the classes and will purge them.

RSC / "use client" issues
If you use React Server Components (e.g. Next.js App Router), components that use hooks or browser APIs must have "use client" at the top. The CLI can set this when you answer “Yes” to RSC during liminal init. If you added components before enabling RSC, add "use client" manually to those files if they use client-only features.

Next steps