Getting Started
Velocity UI is a production-focused React component library and registry for modern Next.js applications. You add components directly into your codebase, keep full ownership of the implementation, and avoid package lock-in. That model makes customization easier for product teams, improves long-term maintainability, and keeps your UI stack aligned with your own design tokens, motion system, and build pipeline.
This guide walks through the fastest path to install Velocity UI, initialize the CLI, import your first component, and set up theming so your app is ready for real production work instead of just a demo.
Prerequisites
- Node.js 18+ (20+ recommended)
- npm, pnpm, or yarn
- Next.js 14+ App Router
- Basic React and TypeScript knowledge
- Tailwind CSS configured if you want the default styling tokens and utility workflow
Quick Start (5 minutes)
The quick start below is optimized for new projects. If you already have an existing app, you can skip the project creation step and start from the CLI install section.
Step 1: Initialize Your Project
npx create-next-app@latest my-app --typescript --tailwind --app
cd my-appStep 2: Install Velocity-UI CLI
npm install -g vui-registry-cli-v1The CLI helps you initialize registry config, pull local component files, and keep installation commands consistent across projects.
Step 3: Initialize Velocity-UI
vui-registry-cli-v1 initThis sets up the components.json registry, Tailwind utilities, and the @/components/ui alias.
Step 4: Add Your First Component
vui-registry-cli-v1 add buttonThis command adds the component files into your project, resolves the required dependencies, and gives you editable local source code instead of a locked package abstraction.
Step 5: Use the Component
import { Button } from '@/components/ui/button'
export default function Page(){
return <Button variant="default">Click Me</Button>
}Setup Theme
Velocity UI defaults to a refined light theme. Use next-themes to support both light and dark.
import { ThemeProvider } from 'next-themes'
export default function RootLayout({ children }:{ children: React.ReactNode }){
return (
<html lang="en">
<body>
<ThemeProvider attribute="class" defaultTheme="light">
{children}
</ThemeProvider>
</body>
</html>
)
}For brand consistency, keep colors, spacing, radii, and shadows token-driven. That makes it easier to adapt shared components across landing pages, dashboards, auth flows, and product surfaces without rewriting styles.
Why Teams Choose Velocity UI
- Own the code locally and customize components without vendor lock-in
- Ship polished React UI faster with reusable motion-aware building blocks
- Keep product design consistent with token-driven theming and accessible defaults
- Scale from startup landing pages to complex app dashboards with the same system
Troubleshooting
Error: Cannot find module
Run the init command and verify tsconfig.json path aliases include @.
Components not styling correctly
Ensure Tailwind is configured and your globals.css includes base styles and tokens.
Theme flicker or mismatch
Confirm your root layout uses ThemeProvider and that CSS variables are defined for both light and dark mode.