Installation

Tell your agent what you need. Aceternity UI works with Claude Code, Codex, Cursor and any agent that speaks MCP. Prefer the terminal? Every component also installs with one shadcn command.

Install with an AI agent

The shadcn MCP server lets your agent search the Aceternity registry, read the code and install components into your project. Set it up once per project.

Add the Aceternity registry

Add Aceternity to the registries in components.json, so the agent can find every component by name. No components.json yet? Run npx shadcn@latest init first.

components.json

{
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

Add the MCP server to your agent

Pick your client: claude, cursor or vscode. Then restart the agent so it loads the server.

Terminal

$ npx shadcn@latest mcp init --client claude

Ask for what you need

Describe the result, not the file names:

“Find a pricing section in the Aceternity registry and add it to the home page.”

“Build a landing page with an Aceternity hero, a bento grid and a testimonials section.”

“Install the Aceternity SaaS landing page and replace the copy with my product.”

For Pro blocks and pages, give the registry your API key (see Pro blocks and pages). Signed in? The MCP page in your dashboard fills in the config with your key.

Or set it up with one prompt

No MCP? Paste this into Claude Code, Codex, Cursor or any agent that can run commands. It sets up the registry and installs a first component.

Prompt

Set up this project for Aceternity UI:
1. If there is no components.json, run `npx shadcn@latest init`.
2. Add "@aceternity": "https://ui.aceternity.com/registry/{name}.json" to "registries" in components.json.
3. Install @aceternity/bento-grid with `npx shadcn@latest add @aceternity/bento-grid` and show it on the home page.

Requirements

React 19 and a React framework: Next.js, TanStack Start, Vite or React Router.
Tailwind CSS v4. For an older project, see Install Tailwind CSS.
TypeScript is recommended. The components are written in .tsx.

Set up your project by hand

Your agent can do this for you. To do it yourself, or to check what it did:

Create a project

Create Next.js answers yes to Tailwind CSS by default, so you get Tailwind CSS v4 set up.

Terminal

$ npx create-next-app@latest my-app

Initialize shadcn

This adds components.json, the cn utility and the CSS variables. Then add the Aceternity registry from the first section.

Terminal

$ npx shadcn@latest init

Or add the utilities without shadcn

Install Motion and the class helpers, then add lib/utils.ts. Components import Motion from motion/react.

Terminal

$ npm i motion clsx tailwind-merge

lib/utils.ts

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Install with the CLI

With the registry in components.json, use the name from the component page. The CLI adds the files and installs their dependencies.

Terminal

$ npx shadcn@latest add @aceternity/bento-grid

Browse the registry from the terminal before you install:

Terminal

$ npx shadcn@latest search @aceternity -q "card"

Prefer to copy and paste? Every component page also shows the full source.

Pro blocks and pages

Blocks, pages and Pro components come with the All-Access Pass. Your agent and the CLI install them the same way; the registry only needs your API key.

Create an API key

Create a key on the API key page of your dashboard. Copy it now: it is shown only once.

Save the key in your environment

Put it in .env.local and keep that file out of git.

.env.local

ACETERNITY_PRO_TOKEN=your-api-key

Send the key from the registry

Replace the registry entry in components.json. The CLI and the MCP server read ${ACETERNITY_PRO_TOKEN} from your environment, so the key never goes in the file.

components.json

{
  "registries": {
    "@aceternity": {
      "url": "https://ui.aceternity.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACETERNITY_PRO_TOKEN}"
      }
    }
  }
}

Ask your agent, or run the command

“Add the Aceternity hero section with hub to the top of the home page.”

Terminal

$ npx shadcn@latest add @aceternity/hero-section-with-hub

A page installs as one page file plus one component per section:

Terminal

$ npx shadcn@latest add @aceternity/saas-landing-page

Run a template

Templates are complete Next.js projects. Download one from its template page, unzip it, then install and run it:

Terminal

$ npm install && npm run dev

Troubleshooting

401 Unauthorized when installing: The key is missing, expired or not on an active license. Check that ACETERNITY_PRO_TOKEN is set in the shell that runs the CLI, or create a new key in your dashboard.
Peer dependency errors with React 19: Some packages have not updated their peer ranges yet. Run the install with npm install --legacy-peer-deps or use pnpm.
Cannot find module framer-motion: The components use motion, the new name of Framer Motion. Install motion and import from motion/react.
Styles do not apply: Make sure your global CSS starts with @import "tailwindcss"; and is imported in your root layout.

Still stuck? Ask in Discord or read the full CLI reference.