Installation

This guide explains how to set up a new AdonisJS application from scratch. It covers the prerequisites, project creation, and starting the development server. You do not need prior experience with AdonisJS, but basic knowledge of Node.js is useful.

Prerequisites

Before you begin, make sure you have the following tools installed.

• Node.js ≥ 24.x
• npm ≥ 11.x

You can verify your installed versions using the following commands.

node -v
npm -v

Check that your Node.js and npm versions meet these requirements before continuing. You can download the latest versions from the Node.js website or use a version manager like Volta/nvm.

Creating a new application

AdonisJS provides the create-adonisjs initializer package to scaffold new applications. This package creates a new project directory with all necessary files, dependencies, and configuration based on your selections during the setup process.

Replace [project-name] with your desired project name. The initializer will create a new directory with that name and set up your AdonisJS application inside it.

npm create adonisjs@latest [project-name]

This command starts an interactive setup and asks you to select a starter kit, or you may pre-define a starter kit using the --kit CLI option.

npm create adonisjs@latest [project-name] -- --kit=hypermedia
npm create adonisjs@latest [project-name] -- --kit=react
npm create adonisjs@latest [project-name] -- --kit=vue
npm create adonisjs@latest [project-name] -- --kit=api

Available starter kits

AdonisJS offers four official starter kits. Each kit sets up a different type of application, depending on how you want to build your user interface and manage interactivity.

• Hypermedia Starter Kit. Uses Edge as the server-side templating engine and integrates Alpine.js to add lightweight, reactive behavior to your frontend. Ideal for applications that primarily render HTML on the server and only need minimal frontend logic.

• React Starter Kit. Uses Inertia.js alongside React to build a fullstack React application powered by the AdonisJS backend. It can operate as a server-rendered app or a Single Page Application (SPA), depending on your configuration.

• Vue Starter Kit. Similar to the React setup, but with Vue as the frontend framework. It utilizes Inertia.js and provides the same full-stack capabilities, including backend-driven routing, shared state, and SPA support.

• API Starter Kit. A monorepo setup with two apps: an AdonisJS backend and an empty frontend project where you can configure any frontend framework of your choice (TanStack Start, Nuxt, Next.js, or others). End-to-end type-safety and shared transformer types are already configured between the backend and frontend.

All starter kits come pre-configured with sensible defaults, streamlined development workflows, and ready-to-use authentication features. For a detailed comparison and usage guidance, see the Pick your path guide.

Project defaults

Every newly created AdonisJS application includes:

• Opinionated folder structure.
• Lucid ORM configured with SQLite as the default database.
• Built-in authentication flows for login and signup.
• ESLint and Prettier setup with pre-defined configuration.

These features help you get started quickly. You can customize, extend, or remove them as your project grows.

Starting the development server

After creating your app, move into your project directory and start the development server.

node ace serve --hmr

npm run dev

{ "hello": "world" }

What you just installed

Your starter kit includes:

• Pre-configured development environment. TypeScript, ESLint, Prettier, and Vite are set up with sensible defaults.

• Database setup. Lucid ORM is configured with SQLite, ready for you to start building models and running migrations.

• Organized project structure. Routes are defined in start/routes.ts, models live in app/models/, controllers are in app/controllers/, and middleware resides in app/middleware/. This convention keeps your codebase organized as it grows.

• Working authentication. All starter kits include a fully functional authentication system with signup and login flows.

Dev-server modes

• Hot Module Replacement (--hmr). This is the recommended approach for most development scenarios. HMR updates your application in the browser without requiring a full page reload, preserving your application's state while reflecting code changes instantly. This provides the fastest development feedback loop, especially when working on frontend components or styles.

• File watching (--watch). This mode automatically restarts the entire server process when you make changes to your code. While this approach takes slightly longer than HMR since it requires a full restart, it ensures a clean application state with every change and can be useful when working on server-side logic or when HMR updates aren't sufficient.

Exploring other commands

The ace command-line tool includes many commands for development and production workflows.

To see all available commands, run the following.

node ace

Next steps

• New to AdonisJS? Follow the Tutorial to build a complete application and learn how everything works together.
• Want to understand the codebase first? Read Folder Structure to see how the project is organized.