Installation

Before you start

Refinery components are designed for modern web projects. For the smoothest setup, start with:

• - Next.js v16+ or a React v19+ app.
• - Tailwind CSS v4+.
• - Motion installed from the motion package and imported from motion/react.
• - A working components.json from the shadcn CLI.
• - Node.js 20.9+ if you are using Next.js.

Next.js is the recommended path because create-next-app@latest can set up React, Tailwind, TypeScript, the App Router, Turbopack, and path aliases in one flow. A Vite or other React app also works as long as Tailwind, aliases, and shadcn are configured correctly.

If you have an existing project, make sure it has those pieces in place before installing Refinery components. The shadcn CLI will check for these things when you try to install a component, but it is easier to get them sorted out first.

Below are instructions for starting a new Next.js app with the recommended setup. If you have an existing project, skip to Start the app and make sure it is healthy before initializing shadcn and installing components.

Create a Next.js app

Run the latest Next.js starter:

The installer may ask whether you want the recommended Next.js defaults or custom settings. Recommended defaults are the quickest route for Refinery because they include TypeScript, ESLint, Tailwind CSS, the App Router, Turbopack, AGENTS.md, and the @/* import alias.

If you choose to customize, you can use these answers:

Would you like to use TypeScript? Yes
Which linter would you like to use? ESLint
Would you like to use React Compiler? Your choice
Would you like to use Tailwind CSS? Yes
Would you like your code inside a `src/` directory? Your choice
Would you like to use App Router? Yes
Would you like to customize the import alias? No
Would you like to include AGENTS.md to guide coding agents to write up-to-date Next.js code? Your choice

The important pieces are Tailwind CSS, React, and the import alias. Refinery examples assume the common @/* alias, but the shadcn CLI will follow whatever aliases are stored in your components.json.

Start the app

Run the dev server once to make sure the project is healthy:

Open http://localhost:3000. If the app loads, stop the server or leave it running in another terminal.

Initialize shadcn

From the project root, initialize shadcn:

The CLI detects your framework, Tailwind setup, TypeScript setup, and alias configuration. Depending on your project, it may ask about:

• - The template, style, base, or preset to use.
• - The base color.
• - Whether you use CSS variables.
• - The path to your global CSS file.
• - The alias for components.
• - The alias for utilities.
• - The icon library.

For a new Next.js and Tailwind v4 app, the defaults are usually the right choice. Keep the component alias pointed at something like @/components, and keep the utility alias pointed at something like @/lib/utils. If you prefer the current shadcn preset flow, you can also use shadcn/create or shadcn@latest init -t next to scaffold and configure the app in one step.

When this finishes, you should have a components.json file in your project root. That file tells the shadcn CLI where to place installed components, where your Tailwind CSS file lives, and which registries it can read from.

Install Motion

Many Refinery components use Motion for animation. Install the current motion package:

Use imports from motion/react in your app. That is the modern package path for Motion, formerly known as Framer Motion:

import { motion } from "motion/react";

Some components declare their own dependencies in the registry item, so "shadcn add" can install them for you. Installing Motion up front keeps your app ready for the motion-heavy Refinery components.

Add your first Refinery component

Refinery is shadcn CLI-compatible, but it is not currently a registered shadcn registry namespace. That means the first install can use the full component URL:

The CLI will fetch the registry item, show the files it wants to add, install dependencies if needed, and write the component into your project according to components.json.

After installation, import the component from the location where the CLI placed it. With the usual alias setup, that will look similar to this:

import { TerminalText } from "@/components/terminal-text";

You now have Refinery running in your app. For the full workflow, including adding the @refinery registry alias and installing more components by name, continue to Registry.