Installation

This guide covers the initial setup for using Kit components in your AdonisJS + Edge 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 Hypermedia variant build on the following stack:

• AdonisJS for the backend (controllers, middleware, routes, mail)
• Edge for server-rendered templates
• Lucid ORM for database queries and model management
• VineJS for request validation
• MJML for transactional email templates

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 --hypermedia

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 Edge views 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 views 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 view 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 views are standard Edge templates that render HTML. They work with any styling approach you would normally use in a server-rendered application:

• Tailwind CSS for utility-first styling directly in your markup
• Vanilla CSS with your own stylesheet
• A CSS framework like Bootstrap or Bulma for pre-built components

Since Edge templates render on the server, you can also use Edge components and partials to build reusable UI elements (buttons, form fields, card layouts) that you apply across Kit views for a consistent look.

What to preserve when styling

When modifying Kit views, 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 actions and methods. The action and method attributes on forms connect to your AdonisJS routes. Do not change these unless you also update start/routes.ts.
• CSRF token. Every form includes {{ csrfField() }} for CSRF protection. This must remain in every POST/PUT/DELETE form.
• Error display logic. Kit views use @error tags or flash message checks to display validation errors. Keep the error rendering even if you restyle how errors appear.

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

Using a coding agent to style templates

The bare templates are structured to work well with coding agents. Each view is a self-contained Edge template with clearly named fields and straightforward HTML.

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 `pages/account/activate.edge`. 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 usage of form field components and the `@link` component.