Skip to main content

​
Installation

Gaia UI components can be added to your project in two ways: using the official Gaia UI CLI (recommended) or manually using the shadcn CLI with our registry.

​
Prerequisites

Before installing Gaia UI, make sure you have:
  • Node.js 18+ installed
  • A Next.js project (version 13+)
  • Tailwind CSS configured in your project
If you don’t have a Next.js project yet, create one: 
npx create-next-app@latest my-app
cd my-app

​
Method 1: Using Gaia UI CLI (Recommended)

The easiest way to add components is using the official @heygaia/ui CLI:
1

Add a component

Use the add command to install any component:
npx @heygaia/ui add composer
This will:
  • Download the component and its dependencies
  • Install required npm packages
  • Add the component to your components/ui directory
2

Add multiple components at once

You can install multiple components in a single command:
npx @heygaia/ui add raised-button message-bubble composer
3

Install base dependencies

Gaia UI components use standard shadcn/ui base components. Install them separately:
npx shadcn@latest add button tooltip avatar dropdown-menu popover skeleton

​
Method 2: Using shadcn CLI Directly

You can also use the shadcn CLI directly with full registry URLs:
1

Add component with full URL

Use the full registry URL for any component:
npx shadcn@latest add https://ui.heygaia.io/r/composer.json
2

Configure namespace (optional)

For a cleaner syntax, configure the @heygaia namespace in your components.json:
{
  "registries": {
    "@heygaia": "https://ui.heygaia.io/r/{name}.json"
  }
}
Then use namespace syntax:
npx shadcn@latest add @heygaia/composer

​
Manual Installation

For complete control, you can manually copy components from the GitHub repository into your project:
1

Copy component files

Navigate to the registry/new-york/ui directory and copy the component files you need to your project’s components/ui directory.
2

Install dependencies

Check the registry.json file for the component’s dependencies and install them:
npm install [dependencies]
3

Update imports

Adjust import paths in the component files to match your project structure.

​
Troubleshooting

​
Missing base components

If you see errors about missing components like Button or Tooltip, install the shadcn base components: 
npx shadcn@latest add button tooltip avatar

​
Import path errors

Make sure your tsconfig.json or jsconfig.json has the @/ path alias configured: 
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

​
TypeScript errors

Ensure you’re using TypeScript 5.0 or higher: 
npm install -D typescript@latest

​
Next Steps

Now that you have Gaia UI installed, follow the Quick Start guide to add your first component to your app.

Build docs developers (and LLMs) love

Get started for freeTalk to us