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.

Available Starter Kits

AdonisJS offers three 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.

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

Once the development server is running, open your browser and visit http://localhost:3333 . You should see the AdonisJS welcome page confirming your installation was successful.

What You Just Installed

Your starter kit includes:

Working authentication: Try creating an account at http://localhost:3333/signup and logging in at http://localhost:3333/login. The authentication system is fully functional and the users table already exists in your SQLite database (tmp/db.sqlite).
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.

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.

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:

node ace