Package Exports

@nqlib/nqui
@nqlib/nqui/debug.css
@nqlib/nqui/styles

Readme

@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

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 "tw-animate-css";
@custom-variant dark (&:is(.dark *));

@import "@nqlib/nqui/styles";

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 Local Development: If you're using npm link or file: protocol, you may need to use Webpack instead of Turbopack:

{
  "scripts": {
    "dev": "next dev --webpack"
  }
}

See Troubleshooting for more details.

For Vite

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

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

Note: Vite does NOT require @source directives. Tailwind CSS v4 automatically scans files when using the @tailwindcss/vite plugin. Only Next.js requires @source directives.

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 />}
    </>
  );
}

Component Instructions

Per-component implementation guides (AI/LLM-optimized) are in docs/components/:

After install: node_modules/@nqlib/nqui/docs/components/README.md (index of all components)
Each file: nqui-<component>.md — import, variants, props, notes
Token-optimized for easy AI consumption and implementation

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.

Troubleshooting

@source Directives: Next.js vs Vite

Problem: Tailwind classes not working, or confusion about whether to use @source directives

Solution:

Next.js REQUIRES @source directives in your CSS file:

@import "tailwindcss";
@source "./**/*.{js,ts,jsx,tsx,mdx}";
@source "../components/**/*.{js,ts,jsx,tsx,mdx}";
@source "../node_modules/@nqlib/nqui/dist/**/*.js";
@import "tw-animate-css";
@import "@nqlib/nqui/styles";

Vite does NOT need @source directives - Tailwind automatically scans files:

@import "tailwindcss";
@import "tw-animate-css";
@import "@nqlib/nqui/styles";

Why the difference? Next.js has a different file structure and build process, so Tailwind needs explicit paths. Vite's @tailwindcss/vite plugin automatically handles file scanning.

Common mistake: Adding @source directives to Vite projects (not needed and may cause issues) or missing them in Next.js projects (will cause Tailwind to not find classes).

Module Resolution Issues (Next.js 16+)

If you encounter Module not found: Can't resolve '@nqlib/nqui' when using npm link or file: protocol, switch to Webpack:

Quick Fix:

{
  "scripts": {
    "dev": "next dev --webpack"
  }
}

Or in next.config.ts:

const nextConfig: NextConfig = {
  experimental: {
    turbo: undefined, // Disable Turbopack
  },
};

Why? Next.js 16 uses Turbopack by default, which has limited symlink support. Webpack handles symlinks better for local development. Production builds always use Webpack, so there's no production impact.

See instructions.md for more troubleshooting tips.

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