Installation

This guide covers the initial setup for using Kit components in your AdonisJS + React application. You will:

• Install and configure the @adonisplus/kit package
• Understand how the Kit CLI adds components to your project
• Learn how to approach styling the bare UI templates that components provide

Tech stack

Kit components for the React variant build on the following stack:

• AdonisJS for the backend (controllers, middleware, routes, mail)
• Inertia.js as the bridge between server and client
• React for frontend pages
• Lucid ORM for database queries and model management
• VineJS for request validation
• Edge + MJML for transactional email templates (emails are server-rendered regardless of your frontend choice)

You do not need to install these separately. AdonisJS starter kits include all of them out of the box.

Configure the private registry

AdonisJS Plus packages are published to a private npm registry. Before installing any Plus packages, you need to point npm to this registry and provide your access token.

Create an .npmrc file in the root of your project (if one does not already exist) and add the following line. This file should be committed to version control.

@adonisplus:registry=https://plus.adonisjs.com/registry/

Next, store your access token in your global npm configuration. You can create a token from the AdonisJS Plus dashboard under the Tokens section. Run this command once per machine.

npm config set "//plus.adonisjs.com/registry/:_authToken" your_token_here

For CI pipelines and production deployments, see the packages installation guide for detailed instructions on authenticating with GitHub Actions, Docker, Fly.io, and other platforms.

Install the Kit CLI

The Kit CLI is distributed as the @adonisplus/kit package. It provides the node ace kit:add command used throughout the component guides.

node ace add @adonisplus/kit

You can verify the installation worked by running

node ace kit:add --help

Adding components

Each component has its own guide with step-by-step instructions. You can add a component using the CLI or by following the manual installation steps.

The CLI copies the necessary files into your project and modifies existing files where needed. In cases where the CLI cannot update a file automatically, it will print the instructions on the terminal for you to apply manually.

node ace kit:add login --react

After running the command, review the terminal output carefully. It will display the exact code you need to add to files like start/routes.ts. Copy and apply those changes before moving on.

The manual installation sections in each guide show exactly what the CLI does. Both approaches produce the same result. Use the CLI when you want speed, and follow the manual steps when you want to understand each change being made.

Working with bare templates

Kit components ship their React pages with semantic HTML and no styling. A login page will have a <form>, <input> fields, <label> elements, error display logic, and a submit button, but no CSS classes.

This is the starting point, not the finished product. You are expected to style these pages to match your application's design.

Recommended workflow

The most effective approach is to style components as you add them, rather than adding all components first and styling later.

1. Add a component using the CLI or manual steps.
2. Verify it works by running the dev server and testing the flow. Confirm that form submissions, redirects, error displays, and email delivery all function correctly.
3. Style the page using your preferred approach.
4. Commit your changes before moving on to the next component. This gives you a clean baseline and makes it easy to revert if something goes wrong with the next component.

Choosing a styling approach

Kit templates are plain React components that return JSX. They work with any styling approach you would normally use in a React application:

• Tailwind CSS for utility-first styling directly in JSX
• CSS Modules for scoped, component-level styles
• A component library like Radix, shadcn/ui, or Headless UI for pre-built accessible primitives

If you use a component library, you can replace the bare HTML elements in Kit pages with library components. For example, replace a plain <input> with a Radix TextField or a shadcn Input. Keep the form structure, field names, and error handling logic intact while swapping the visual layer.

What to preserve when styling

When modifying Kit pages, keep the following intact:

• Form field names. Controllers and validators expect specific field names like email, password, code. Changing these will break server-side validation.
• Form routes. The Form component's route prop connects to your AdonisJS routes. Do not change these unless you also update start/routes.ts.
• Error display logic. The {({ errors }) => ...} render function receives server-side validation errors. Keep the error rendering even if you restyle how errors appear.
• Route parameters. Props like routeParams on Form and Link components pass dynamic values to route URLs. These must stay.

Everything else (layout, spacing, colors, typography, component hierarchy) is yours to change.

Using a coding agent to style templates

The bare templates are structured to work well with coding agents. Each page is a self-contained React component with clearly named fields and straightforward JSX.

After adding a component, you can ask your coding agent to style it for you. Be specific about the file path, your styling approach, and what must remain unchanged. For example, a good prompt would be:

I want you to scan this codebase and understand how we have styled the application. Once, you have enough understanding:

Re-design the account activation page at `inertia/pages/account/activate.tsx`. Keep the following unchanged:

- All form field name attributes
- The Form component's route prop
- Current approach of handling and displaying server-side errors.
- The routeParams props on Form and Link components