Installation Guide
Velocity UI supports both an automated CLI workflow and a manual local integration workflow. Use the CLI when you want the fastest setup path, and use the manual approach when your team needs tighter control over file structure, naming, or internal architecture conventions.
The goal of this installation guide is to help you get components running cleanly in development, keep them maintainable in production, and avoid common setup mistakes around aliases, Tailwind configuration, and theme tokens.
Environment Setup
- Node.js 18+ (20+ recommended)
- Next.js 14+ App Router
- Tailwind CSS configured
- TypeScript enabled
- A working local development server if you plan to test the registry against your own app
Method 1: CLI (Recommended)
The CLI adds component files, resolves package dependencies, and standardizes the setup experience. It is the best option for most teams because it reduces copy-paste errors and keeps installation repeatable.
Initialize
npx -y vui-registry-cli-v1@latest initInitialization creates the registry config and prepares your project to receive component files with the expected aliases and utilities.
Add a Component
npx -y vui-registry-cli-v1@latest add spotlight-cardReplace spotlight-card with any available slug from the components catalog. Each install writes editable source files into your local project.
Local Registry (Dev)
Point the CLI at your local site. It reads /data/components.json from your dev server.
set VELOCITY_LOCAL_REGISTRY_URL=http://localhost:3000
npx -y vui-registry-cli-v1@latest add premium-buttonDry Run
Preview changes without writing to disk.
npx -y vui-registry-cli-v1@latest add premium-button --dry-runMethod 2: Manual Copy & Paste
Manual installation is useful when you want to review free component source before integrating it or when your project uses a custom folder structure. Premium component source is intentionally not exposed in public docs.
- Browse components in the catalog.
- Open a free component page and copy the file contents.
- Create files in
src/components/ui(or your preferred folder). - Install any listed dependencies.
- Verify imports, tokens, and peer packages before committing.
Method 3: CDN
A CDN distribution for prebuilt assets is planned. For now, the recommended path is local ownership through CLI install or manual setup so teams can inspect, adapt, and version their UI implementation directly.
Configuration
Path Aliases
Ensure tsconfig.json has an alias for @ pointing to your source folder.
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}Tailwind Setup
Include base styles and tokens in your global CSS.
@tailwind base;
@tailwind components;
@tailwind utilities;Dark Mode
Use next-themes for theme switching.
import { ThemeProvider } from 'next-themes'
<ThemeProvider attribute="class" defaultTheme="light">...</ThemeProvider>Production Notes
- Commit installed component files so your build does not depend on a live registry at runtime
- Audit dependencies before release to keep bundle size and security posture under control
- Prefer design tokens over hardcoded values so updates scale across the UI system
- Test light mode, dark mode, keyboard navigation, and responsive layouts before shipping
Build Process
- Components are normal React/TS files owned by your repo.
- Tree‑shakeable with your bundler.
- No runtime registry dependency required in production.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| Cannot find module | Missing tsconfig path alias | Add @/* alias |
| Styles not applied | Tailwind not configured | Include base and tokens in globals.css |
| Dark mode not toggling | Missing ThemeProvider | Wrap with next-themes |
| Registry add command fails | Wrong local registry URL or dev server offline | Check VELOCITY_LOCAL_REGISTRY_URL and restart the app |
Platform Notes
- Windows: Use
set VAR=valueto define env vars in cmd/PowerShell. - macOS/Linux: Use
export VAR=valuebefore running the CLI.