@nqlib/nqui

A React component library with enhanced UI components and developer tools. Built with TypeScript, Tailwind CSS, and Radix UI primitives.

Installation

Install from npmjs.com (recommended - no authentication needed):

npm install @nqlib/nqui

Alternative: Install from GitHub Packages (requires GitHub account + token):

# Create .npmrc in your project
echo "@nqlib:registry=https://npm.pkg.github.com" > .npmrc

# Authenticate with GitHub
npm login --registry=https://npm.pkg.github.com

# Install
npm install @nqlib/nqui

Quick Start

Option 1: Package Import (Recommended)

For Next.js

1. Import CSS in your app/layout.tsx or app/globals.css:

// app/globals.css
@import "tailwindcss";
@source "./**/*.{js,ts,jsx,tsx,mdx}";
@source "../components/**/*.{js,ts,jsx,tsx,mdx}";
@source "../node_modules/@nqlib/nqui/dist/**/*.js";
@import "../node_modules/tw-animate-css/dist/tw-animate.css";
@custom-variant dark (&:is(.dark *));

@import "@nqlib/nqui/styles";

2. Use components:

"use client";

import { Button } from '@nqlib/nqui';

export default function Page() {
  return <Button>Click me</Button>;
}

Note: Pages using nqui components must include "use client" because nqui components use React hooks.

For Vite

1. Import CSS in your src/main.tsx or src/index.css:

/* src/index.css */
@import "tailwindcss";
@import "../node_modules/tw-animate-css/dist/tw-animate.css";
@import "@nqlib/nqui/styles";

2. Use components:

import { Button } from '@nqlib/nqui';

function App() {
  return <Button>Click me</Button>;
}

Option 2: Init Script (Alternative)

The init script automatically detects your framework and sets up CSS with framework-specific Tailwind directives:

npx @nqlib/nqui init-css

This will:

• Detect your framework (Next.js, Vite, Remix, etc.)
• Add framework-specific Tailwind setup
• Copy nqui CSS variables to the appropriate location
• Provide next steps

For Next.js: Creates/updates app/globals.css with Next.js-specific directives
For Vite: Creates/updates src/index.css with Vite-specific directives

Setup Requirements

Tailwind CSS Configuration

nqui requires Tailwind CSS v4. Ensure you have it installed:

npm install tailwindcss@^4.1.0

For Next.js, Tailwind CSS v4 works with the new @import syntax in CSS files.

For Vite, install the Tailwind CSS Vite plugin:

npm install @tailwindcss/vite

Then add it to your vite.config.ts:

import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

Optional: Debug Tools

If you want to use the debug tools in development:

npx @nqlib/nqui init-debug-css

Then import in your app:

import { DebugPanel } from '@nqlib/nqui';
import '@nqlib/nqui/debug.css';

function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === 'development' && <DebugPanel />}
    </>
  );
}

Usage Examples

Basic Components

import { Button, Checkbox, Input } from '@nqlib/nqui';

function MyForm() {
  return (
    <form>
      <Input placeholder="Enter text" />
      <Checkbox label="Accept terms" />
      <Button variant="default">Submit</Button>
    </form>
  );
}

Enhanced Components

nqui includes enhanced versions of common components with additional variants:

import { Button, Separator } from '@nqlib/nqui';

function MyComponent() {
  return (
    <>
      <Button variant="success">Success</Button>
      <Button variant="warning">Warning</Button>
      <Button variant="info">Info</Button>
      <Separator variant="shadow-outset" />
    </>
  );
}

Custom Components

import { ColorPicker, Rating, TableOfContents } from '@nqlib/nqui';

function MyApp() {
  return (
    <>
      <ColorPicker value="oklch(0.75 0.15 240)" onChange={handleChange} />
      <Rating value={4} onChange={setRating} />
      <TableOfContents items={tocItems} />
    </>
  );
}

Framework Support

• ✅ Next.js (App Router) - Fully tested and supported
• ✅ Vite - Fully supported
• ✅ Remix - Supported
• ✅ Create React App - Supported

All components are framework-agnostic and work with any React setup.

Features

• ✨ Enhanced UI Components - Button, Checkbox, RadioGroup, Separator, ScrollArea with additional variants
• 🎨 Custom Components - ColorPicker, Rating, TableOfContents
• 🛠️ Debug Tools - Development tools for inspecting and testing components
• 🎯 TypeScript - Full TypeScript support with exported types
• ♿ Accessible - Built on Radix UI primitives for accessibility
• 🎨 Themable - CSS variables for easy theming
• 📦 Tree-shakeable - Import only what you need

Documentation

• Installation Guide - Detailed setup instructions
• Debug Tools - Debug panel documentation
• AGENTS.md - Development guidelines for contributors

Development

For contributors:

# Install dependencies
npm install

# Run dev server (showcase app)
npm run dev

# Build library
npm run build:lib

# Build showcase app
npm run build:app

# Lint
npm run lint

Publishing

For maintainers:

Publish to npmjs.com (recommended):

npm version patch|minor|major
npm run publish:npm

Publish to GitHub Packages:

npm version patch|minor|major
npm run publish:github

Publish to both:

npm version patch|minor|major
npm run publish:both

See PUBLISHING.md for detailed instructions.

License

MIT