Quick Start

1. Create a Next.js project

Run this in the folder where you keep your projects. It creates a new folder called my-app and moves into it:

npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --yes
cd my-app

That gives you the App Router, TypeScript, Tailwind CSS v4, ESLint, a src/ folder and the @/ import alias that every Nexus UI component uses (@/lib/utils means src/lib/utils.ts). Packages are installed for you, so there is no separate npm install. Every command from here on runs inside my-app.

2. Set up shadcn/ui

Nexus UI is installed with the shadcn CLI, and the components import its cn() helper. One command sets up both:

npx shadcn@latest init -d

-d accepts the defaults so it asks nothing; leave it off if you want to choose a style yourself. The command:

• creates components.json in the project root, the file the CLI reads its settings from;
• creates src/lib/utils.ts with the cn() helper (today it is one line, export { cn } from "cn", backed by the cn package it installs) and a starter src/components/ui/button.tsx;
• installs the packages those files use and adds colour variables to src/app/globals.css.

Check that src/lib/utils.ts now exists. If it does not, create it yourself with the two-line helper on the cn() page. To understand each piece, see Install Next.js, Install Tailwind CSS and Add utilities.

3. Add a free component with the CLI

We will add the Glow Button, which is free. The same two steps work for every free component and block.

1. Tell the CLI where Nexus UI lives. This writes one entry into your components.json for you, so there is nothing to edit by hand. Run it once per project:
   npmpnpmyarnbun

   npx shadcn@latest registry add "@nexus-labs=https://www.nexus-ui.com/api/registry/{name}"

   Type it exactly as shown, including {name}. That is a placeholder the CLI fills in itself: when you later ask for @nexus-labs/glow-button it requests https://www.nexus-ui.com/api/registry/glow-button. You never replace it with anything.
2. Install the component.
   npmpnpmyarnbun

   npx shadcn@latest add @nexus-labs/glow-button

   It asks you to confirm, then writes the component files into src/components/glow-button/, adds the helper it needs in src/lib/ui-sounds.ts, and installs the packages it uses (such as framer-motion). It may also add the Inter font setup so the component looks like its preview. Add --dry-run to see the list without writing anything, or -y to skip the confirmation.
3. For any other component, open its page on /components and copy the command from its Install box. The name after @nexus-labs/ is the component's registry name.

Prefer not to touch components.json? Skip step 1 and install a free component straight from its address instead (it still needs the file from step 2 above):

npx shadcn@latest add https://www.nexus-ui.com/api/registry/glow-button

Then jump to step 6.

4. Add a Pro component with the CLI

Pro components are served only to people with a Pro plan, so the CLI has to prove who you are with an API key. You make the key once and reuse it in every project. The example below installs Particle Reveal.

1. Create the key. Open nexus-ui.com/dashboard/api-key (sign in first; you need a Pro plan) and press Generate key. Copy the key now: it starts with nxs_ and is shown only once. If you lose it, generate a new one, which stops the old one working.
2. Save the key in your project. In the project root, next to package.json, create a file named .env.local and put this one line in it, with your own key after the equals sign:

   NEXUS_API_KEY=nxs_your_key_here

   Keep the key here and not in components.json. That file is normally committed to git, while .env.local is already ignored by git in a new Next.js project.
3. Point the registry at the key. Open components.json. Inside the outermost braces, add the "registries" entry below as a new line next to the others (after a comma on the line above). If you already ran the command from step 3, there is a "registries" entry already: replace it with this one.

   {
     "$schema": "https://ui.shadcn.com/schema.json",
     ...everything the init command wrote stays as it is...,
     "registries": {
       "@nexus-labs": {
         "url": "https://www.nexus-ui.com/api/registry/{name}",
         "headers": {
           "Authorization": "Bearer ${NEXUS_API_KEY}"
         }
       }
     }
   }

   The dots line stands for what is already in your file; do not type it. Leave ${NEXUS_API_KEY} and {name} exactly as written. The CLI reads NEXUS_API_KEY from .env.local when it runs, and fills in {name} with the component you ask for. This one entry also works for free components.
4. Install the component. Run it from the project root, the folder that holds .env.local:
   npmpnpmyarnbun

   npx shadcn@latest add @nexus-labs/particle-reveal

   Pro blocks install the same way, for example @nexus-labs/text-animations. Each component's page shows its exact command.

If it fails

• A message that NEXUS_API_KEY is missing: the variable was not found. Check the file is named .env.local, sits in the project root, and that you ran the command from that folder.
• A 401 or unauthorized message: the key is wrong, was replaced by a newer one, or your Pro plan is not active. Generate a key again on the API key page and update .env.local.
• An unknown registry @nexus-labs: the registries entry is missing from components.json or the file is no longer valid JSON (look for a missing comma).

5. Or copy a component by hand

You can skip the registry and the key entirely and copy the files yourself. The steps below use the Glow Button; any component works the same way. Pro components show their source only while you are signed in with a Pro plan.

1. Install the packages. Nearly every component animates with Framer Motion:
   npmpnpmyarnbun

   npm install framer-motion

   A component page lists any extra package under Copying by hand?
2. Open the source. Go to the component's page on /components, scroll to Add it to your project, find Copying by hand? and press Show the source files. You get one tab per file, each headed Save as with the exact path to use.
3. Create each file. For every tab, create the file at the path shown (make the folders if they do not exist yet), then paste the code. For the Glow Button that is four files: src/components/glow-button/glow-button.tsx, src/components/glow-button/magnetic-button.tsx, src/components/glow-button/index.ts and the helper src/lib/ui-sounds.ts. Do not skip the helper: the component imports it, and without it the build stops with Module not found: Can't resolve '@/lib/ui-sounds'.
4. Check the helper. The components import cn() from @/lib/utils, which step 2 created. Without shadcn, make that file yourself; see the cn() page.

6. Use it in a page

Installing only adds the component to your project; it does not show it anywhere until a page uses it. Every component page has a Usage tab on its preview: a complete page that uses it, not the component itself. Its first line says where to save it, normally src/app/page.tsx, so you paste the whole example there. Some start with "use client" because they pass functions to the component; keep that line. For the Glow Button the page is:

// src/app/page.tsx

import { GlowButton } from "@/components/glow-button";

export default function Page() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <GlowButton href="#">Get started</GlowButton>
    </main>
  );
}

For Particle Reveal the import is import { ParticleReveal } from "@/components/particle-reveal" and the tag is <ParticleReveal text="Launch" />. Then start the app:

npm run dev

Open http://localhost:3000. If it does not compile, read the first error line: Module not found names the file you are missing. The CLI page covers monorepos, previewing installs and more.