Skip to main content

​
Prerequisites

Before installing AdonisJS Core, ensure you have the following:

Node.js

Version 24.0.0 or higherDownload from nodejs.org

Package Manager

npm, yarn, or pnpmComes with Node.js or install separately
AdonisJS Core requires Node.js 24.0.0 or higher. Using an older version will result in compatibility issues.

​
Install AdonisJS Core

Install the @adonisjs/core package using your preferred package manager: 
npm install @adonisjs/core
The @adonisjs/core package includes all the essential modules you need to build web applications, including HTTP server, routing, middleware, config management, and more.

​
Install Optional Dependencies

Depending on your application requirements, you may want to install these optional peer dependencies:

​
Development Tools

For hot module reloading and TypeScript compilation: 
npm install --save-dev @adonisjs/assembler

​
Password Hashing

For secure password hashing using Argon2 or Bcrypt:

​
Validation

For request validation with VineJS: 
npm install @vinejs/vine

​
Template Engine

For server-side rendering with Edge templates: 
npm install edge.js

​
Error Handling

For beautiful error pages in development: 
npm install youch

​
Pretty Logging

For formatted console output during development: 
npm install pino-pretty

​
TypeScript Configuration

AdonisJS is built with TypeScript. Create a tsconfig.json file in your project root:
tsconfig.json
{
  "extends": "@adonisjs/tsconfig/tsconfig.app.json",
  "compilerOptions": {
    "rootDir": "./",
    "outDir": "./build"
  }
}
The @adonisjs/tsconfig package provides recommended TypeScript configurations. Install it with npm install --save-dev @adonisjs/tsconfig.

​
Package.json Setup

Update your package.json to use ES modules:
package.json
{
  "name": "my-adonisjs-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "node --watch --import=@poppinss/ts-exec bin/server.ts",
    "build": "tsc",
    "start": "node build/bin/server.js"
  }
}
Setting "type": "module" enables ES module syntax (import/export) in your project.

​
Project Structure

Create a basic project structure: 
my-adonisjs-app/
├── bin/
│   └── server.ts          # HTTP server entry point
├── app/
│   ├── controllers/       # HTTP controllers
│   └── middleware/        # HTTP middleware
├── config/
│   └── app.ts            # Application configuration
├── start/
│   └── routes.ts         # Route definitions
├── package.json
└── tsconfig.json
You can customize this structure to fit your needs. AdonisJS is flexible and doesn’t enforce a specific directory layout.

​
Verification

Verify your installation by checking the installed version: 
npm list @adonisjs/core
You should see output similar to: 
@adonisjs/core@7.0.0

​
Next Steps

Now that you have AdonisJS Core installed, you’re ready to build your first application:

Quick Start Guide

Create your first HTTP server with AdonisJS

Architecture Overview

Learn about the core concepts and architecture

​
Troubleshooting

If you see an error about Node.js version, ensure you’re running Node.js 24.0.0 or higher:
node --version
If you need to upgrade, download the latest version from nodejs.org or use a version manager like nvm.
Some packages like argon2 and bcrypt require native compilation. Ensure you have:
  • Python (for node-gyp)
  • C++ build tools (Visual Studio Build Tools on Windows, gcc on Linux, Xcode on macOS)
On Windows, you can install build tools with:
npm install --global windows-build-tools
If you encounter import errors, ensure:
  1. Your tsconfig.json has "module": "ESNext" or "module": "NodeNext"
  2. Your package.json has "type": "module"
  3. You’re using .js extensions in your imports (TypeScript requirement for ES modules)

Need Help?

If you encounter issues not covered here, please open an issue on GitHub.