Installation

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

• Install and configure the @adonisplus/kit package
• Understand how the Kit CLI adds components to your project
• Learn how the API variant differs from the Hypermedia and React variants

Tech stack

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

• AdonisJS for the backend (controllers, middleware, routes, mail)
• Lucid ORM for database queries and model management
• VineJS for request validation
• Tuyau for typed route names and API client schema generation
• Edge + MJML for transactional email templates (emails are server-rendered HTML even though the application emits JSON)

You do not need to install these separately. The AdonisJS API starter kit includes 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:list

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

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.

What the API variant ships

Unlike the Hypermedia and React variants, the API variant does not include any view layer. Your application emits JSON only. The frontend is a separate codebase (SPA, mobile app, or third-party integration) that consumes the JSON contract.

Two API-specific concerns are configured during the Auth Setup guide:

• Frontend URL. A FRONTEND_URL environment variable and the matching appFrontendUrl config entry. Mailers build links like ${appFrontendUrl}/verify-email?token=... so the email points at your frontend, not the backend.
• JSON error responses. All controllers and middleware return errors in the standard AdonisJS framework shape: { "errors": [{ "message": "..." }] }. The VerifiedAccountMiddleware returns a 403 with this shape rather than redirecting.

The login and signup guides also offer two authentication strategies (access tokens or session cookies) that you pick once and apply to all subsequent components.

Reading the JSON contract

Every successful response is wrapped in a data envelope by the serialize(...) HttpContext helper that the api starter kit ships with:

{ "data": { "user": { ... }, "token": "..." } }

Successful responses contain either the resource ({ data: { user } }), a credential plus the resource ({ data: { user, token } }), or a minimal status message ({ data: { message: "verified" } }). Errors do not use the data envelope and instead return the errors array directly:

{ "errors": [{ "message": "Invalid user credentials" }] }

Your frontend code should branch on the presence of data vs errors (or on the response status code) when handling responses. This shape is consistent across every endpoint a Kit component adds, so a single response handler in your frontend can deal with all of them.