Hayden

This post will explain what AdonisJS is, why you should use it, and how to get started—written for developers at any level.

When building backends with Node.js, you often face the same dilemma. Express is too minimal, forcing you to reinvent the wheel every time. NestJS feels complex and has a steep learning curve.

“Isn’t there a framework with all the features you need, without the complexity?” For those developers, there’s AdonisJS. Having worked with various Node.js frameworks in production, I thought “this is it” when I first tried AdonisJS. AdonisJS celebrated its 10th anniversary in September 2025, proving itself as a stable framework that’s evolved steadily over time.

 

AdonisJS

 

 

1. What is AdonisJS?

AdonisJS is a TypeScript-first web framework for Node.js that lets you build web applications and API servers. Simply put, it’s a tool for building backends for websites or mobile apps.

Its defining characteristic is the “battery included” approach. Just like a new smartphone comes with everything you need to start using it—charger, cable—AdonisJS comes with all the features you need for development right out of the box.

AdonisJS Core Philosophy

AdonisJS aims to help developers spend less time picking npm packages, writing glue code, and debating folder structures, and more time building features critical to business needs.

If you’ve used Express, you’ll relate to this. Spending an entire day wondering “which library should I use for this feature?” or “how do others structure their folders?” AdonisJS eliminates this time waste.

 

 

2. Key Features – Why Choose AdonisJS?

Modern JavaScript and TypeScript Foundation

Starting with AdonisJS v6, ECMAScript Modules (ESM) and TypeScript are the defaults. Why does this matter?

Many packages in the modern JavaScript ecosystem are transitioning to ESM. Using only CommonJS means you can’t use these latest packages or receive security updates. AdonisJS is prepared for this future.

AdonisJS pays close attention to type-safety, seamless intellisense, and support for auto imports. You’ll feel the IDE helping you at every moment while writing code.

Clear MVC Structure for Organized Development

AdonisJS embraces the classic MVC (Model-View-Controller) design pattern. This is particularly helpful for beginners as it makes it clear “where to write what.”

  • Models – Database-related logic
  • Views – User interface
  • Controllers – Business logic

If you’ve used Laravel or Ruby on Rails, this will feel immediately familiar. If you have Laravel experience and want to explore Node.js, AdonisJS feels like writing Laravel in TypeScript and Node.js, making it easy to get started in a day.

Powerful ORM – Lucid

AdonisJS includes its own ORM called Lucid, with support for PostgreSQL, MySQL, MSSQL, SQLite, and more.

// User query example - intuitive without SQL!
const users = await User.query()
  .where('active', true)
  .orderBy('created_at', 'desc')
  .limit(10)

You can work with databases using readable code like above, without writing complex SQL queries.

Everything You Need Out of the Box

AdonisJS is one of the rare frameworks in the Node.js community that ships with a complete suite of first-party packages.

Feature Package Description
Core @adonisjs/core Routing, Middleware, Session
Database @adonisjs/lucid SQL ORM, Query Builder
Auth @adonisjs/auth Session, API Tokens, Social Auth
Security @adonisjs/shield XSS, CSRF Protection
Templates edge.js HTML Rendering Engine
Validation @vinejs/vine One of the fastest validation libraries in Node.js
File Handling @adonisjs/drive File Uploads, Cloud Storage (S3, GCS)

With Express, you’d need to find and assemble all of these yourself. With AdonisJS, everything is ready from the start.

Excellent Performance

AdonisJS’s HTTP server has performance on par with Fastify. In actual benchmark tests, AdonisJS showed nearly double the performance compared to NestJS.

You might worry “won’t all these features slow it down?” Not at all. It’s often faster than Express.

 

 

3. Who Should Use AdonisJS?

Laravel or Rails Developers Transitioning to Node.js

If you have Laravel experience, AdonisJS’s structure will feel very familiar. The file structure, naming conventions, and even ORM usage are similar to Laravel.

Developers Tired of Express

There’s a real user testimonial: “What took me 3 weeks with just Express, I accomplished in 2 days with AdonisJS.” If you’re exhausted from constantly searching for and connecting libraries, try AdonisJS.

Teams Wanting Structured Projects

Rapid application development and developer experience are top priorities for the AdonisJS team. If you need a structure that remains manageable as projects scale, AdonisJS is the answer.

Those Wanting Full-Stack Framework Benefits

If you want the benefits of full-stack frameworks like Laravel or Rails in Node.js, AdonisJS is your best choice.

 

 

4. How Does It Compare to Other Frameworks?

AdonisJS vs Express

Express characteristics:

  • Minimal with high flexibility
  • Build everything yourself
  • Good for small projects

AdonisJS characteristics:

  • Includes ORM, query builder, built-in authentication system, and much more
  • Provides structured organization
  • Suitable for medium to large projects

Real development time comparison:

  • Express: File uploads → Find multer → Configure → Set up middleware → Security configuration
  • AdonisJS: Built-in → Simple configuration changes and done

AdonisJS vs NestJS

AdonisJS follows the MVC pattern, while NestJS uses a module-based architecture. AdonisJS provides its own ORM called Lucid, while NestJS offers flexibility to choose from various ORMs like TypeORM and Sequelize.

Feature AdonisJS NestJS
Primary Language JavaScript/TypeScript TypeScript
Pattern MVC Module-based
Learning Curve Low (Laravel-like) High (Angular-like)
ORM Lucid (Built-in) TypeORM, Sequelize, etc.
Philosophy Battery Included Module Freedom
Performance Very Fast Fast
Best For Rapid Development, Small-Medium Enterprise, Large Microservices

Which Should You Choose?

  • Need to build prototypes quickly → AdonisJS
  • Have Angular experience, building large enterprise apps → NestJS
  • Familiar with Laravel style → AdonisJS
  • Want to choose and configure everything yourself → NestJS

 

Express.js? – Node.js Backend Web Server Framework

What is ‘NestJS’? A Modern and Structured Node.js Framework

 

 

5. Getting Started – Installation to First Run

Let’s install and run AdonisJS. I’ll explain step-by-step so anyone can follow.

Prerequisites

You need Node.js version 20 or higher. First, check if Node.js is installed on your computer.

Open your terminal and enter:

node -v

If it shows v20.0.0 or higher, you’re good. If not installed or the version is lower:

Creating a New Project

You can create a new project using the npm init command.

# Basic project creation (interactive prompts will appear)
npm init adonisjs@latest my-app

# Project with MySQL database
npm init adonisjs@latest my-app -- --db=mysql

# PostgreSQL with API starter kit
npm init adonisjs@latest my-app -- --db=postgres --kit=api

Important: When passing CLI flags with npm init, you must use double dashes twice. Otherwise, the flags won’t be passed correctly.

Choosing a Starter Kit – Recommendations by Project Type

AdonisJS provides several starter kits tailored to different project types.

1) Web Starter Kit – Server-Rendered Websites

Tailored for creating traditional server-rendered web apps. Choose this for blogs, admin panels, or company websites with limited frontend interactivity.

npm init adonisjs@latest -- -K=web

# With MySQL
npm init adonisjs@latest -- -K=web --db=mysql

Key Features Included:

  • Edge.js (Template Engine) – Easy HTML creation
  • Vite (Frontend Bundler) – Automatic CSS, JS processing
  • Lucid (ORM) – Database connection
  • Auth (Authentication) – Login/Registration
  • Shield (Security) – XSS, CSRF protection
  • Static (Static Files) – Serve images, CSS, JS

Later, you can add tools like Hotwire, HTMX, or Alpine.js to create SPA-like experiences.

2) API Starter Kit – REST API Server

If you plan to build your frontend app using React or Vue, create your AdonisJS backend using the API starter kit.

npm init adonisjs@latest -- -K=api

# With PostgreSQL
npm init adonisjs@latest -- -K=api --db=postgres

# With token-based authentication
npm init adonisjs@latest -- -K=api --auth-guard=access_tokens

Compared to web starter kit:

  • ❌ Static file serving removed
  • ❌ No views layer or Vite configuration
  • ✅ CORS protection enabled (external domains can call API)
  • ✅ All responses automatically converted to JSON

The API starter kit is configured with session-based authentication by default, but you can use the –auth-guard flag for token-based authentication.

3) Slim Starter Kit – Minimal Configuration

For minimalists, the slim starter kit comes with just the framework core and default folder structure.

npm init adonisjs@latest -- -K=slim

# With PostgreSQL
npm init adonisjs@latest -- -K=slim --db=postgres

Choose this when you want the minimum without unnecessary features.

4) Inertia Starter Kit – Modern SPA

Inertia is a way to build server-driven single-page applications. You can choose from React, Vue, Solid, or Svelte.

# React with server-side rendering
npm init adonisjs@latest -- -K=inertia --adapter=react --ssr

# Vue without SSR
npm init adonisjs@latest -- -K=inertia --adapter=vue --no-ssr

# With Svelte
npm init adonisjs@latest -- -K=inertia --adapter=svelte

Starting the Development Server

Once the project is created, navigate to the folder and start the development server:

cd my-app
node ace serve --hmr

Ace is a command-line framework bundled inside the framework’s core. The –hmr flag monitors the file system and performs Hot Module Replacement.

What is Hot Module Replacement? When you modify code, changes are reflected automatically without restarting the server. This saves tremendous time during development!

Open http://localhost:3333 in your browser to see the AdonisJS welcome page. Success! 🎉

 

 

6. Building Your First API – Todo API

Let’s build a simple Todo management API to understand how AdonisJS works.

Step 1: Create a Simple Route

Open the start/routes.ts file and add a route:

import router from '@adonisjs/core/services/router'

// GET request - Fetch todo list
router.get('/todos', async () => {
  return [
    { id: 1, title: 'Learn AdonisJS', completed: false },
    { id: 2, title: 'Write blog post', completed: true }
  ]
})

With the server running, visit http://localhost:3333/todos in your browser or Postman to receive the JSON response.

Step 2: Create a Controller

In real projects, you don’t write code directly in routes—you use controllers.

Run this command in your terminal:

node ace make:controller Todo

The app/controllers/todos_controller.ts file is automatically created:

import type { HttpContext } from '@adonisjs/core/http'

export default class TodosController {
  // List todos
  async index({ response }: HttpContext) {
    const todos = [
      { id: 1, title: 'Learn AdonisJS', completed: false },
      { id: 2, title: 'Write blog post', completed: true }
    ]
    return response.json(todos)
  }
}

Modify the start/routes.ts file:

import router from '@adonisjs/core/services/router'
const TodosController = () => import('#controllers/todos_controller')

router.get('/todos', [TodosController, 'index'])

Note: #controllers is a special path alias used in AdonisJS v6. It points to app/controllers.

Step 3: Connect the Database

To store real data, you need to connect a database. I’ll use PostgreSQL as an example.

If you didn’t use the --db=postgres option when creating the project:

npm i @adonisjs/lucid
node ace configure @adonisjs/lucid

When the prompt appears, select PostgreSQL.

Configure database connection info in the .env file:

DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_DATABASE=my_app

Step 4: Create Model and Migration

node ace make:model Todo -m

The -m flag creates a migration file as well.

The database/migrations/xxxx_create_todos_table.ts file is created. Write the contents as follows:

import { BaseSchema } from '@adonisjs/lucid/schema'

export default class extends BaseSchema {
  protected tableName = 'todos'

  async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments('id')
      table.string('title').notNullable()
      table.boolean('completed').defaultTo(false)
      table.timestamp('created_at')
      table.timestamp('updated_at')
    })
  }

  async down() {
    this.schema.dropTable(this.tableName)
  }
}

Run the migration to create the actual database table:

node ace migration:run

Write the app/models/todo.ts file as follows:

import { DateTime } from 'luxon'
import { BaseModel, column } from '@adonisjs/lucid/orm'

export default class Todo extends BaseModel {
  @column({ isPrimary: true })
  declare id: number

  @column()
  declare title: string

  @column()
  declare completed: boolean

  @column.dateTime({ autoCreate: true })
  declare createdAt: DateTime

  @column.dateTime({ autoCreate: true, autoUpdate: true })
  declare updatedAt: DateTime
}

Step 5: Use the Model in Controller

Now modify the controller to integrate with the actual database:

import type { HttpContext } from '@adonisjs/core/http'
import Todo from '#models/todo'

export default class TodosController {
  // List todos
  async index({ response }: HttpContext) {
    const todos = await Todo.all()
    return response.json(todos)
  }

  // Create
  async store({ request, response }: HttpContext) {
    const todo = await Todo.create({
      title: request.input('title'),
      completed: false
    })
    return response.status(201).json(todo)
  }

  // Update
  async update({ params, request, response }: HttpContext) {
    const todo = await Todo.findOrFail(params.id)
    todo.title = request.input('title')
    todo.completed = request.input('completed')
    await todo.save()
    return response.json(todo)
  }

  // Delete
  async destroy({ params, response }: HttpContext) {
    const todo = await Todo.findOrFail(params.id)
    await todo.delete()
    return response.status(204)
  }
}

Add routes in one line:

import router from '@adonisjs/core/services/router'
const TodosController = () => import('#controllers/todos_controller')

router.resource('todos', TodosController).apiOnly()

Routes automatically created by resource() and apiOnly():

  • GET /todos → index (list)
  • POST /todos → store (create)
  • GET /todos/:id → show (details)
  • PUT/PATCH /todos/:id → update (modify)
  • DELETE /todos/:id → destroy (delete)

Done! Now test with Postman or other API testing tools.

 

 

7. Preparing for Production Deployment

AdonisJS applications are written in TypeScript, so they must be compiled to JavaScript before running in production.

node ace build

This command performs the following operations:

  1. Remove existing build folder
  2. Compile frontend assets with Vite (if configured)
  3. Compile TypeScript to JavaScript with tsc
  4. Copy necessary files to build folder
  5. Copy package.json

Once the build completes:

cd build
npm ci --omit=dev
node bin/server.js

For production deployment, using a process manager like PM2 is recommended:

npm install -g pm2
pm2 start bin/server.js --name my-app

 

 

8. Development Environment Setup – For a Better Experience

Using ESLint and Prettier

Official starter kits come with ESLint and Prettier already configured. Run them with:

# Lint code
npm run lint

# Auto-fix
npm run lint -- --fix

# Format code
npm run format

Install VSCode Extensions

If you’re a VSCode user, installing these extensions will greatly enhance your development experience:

  1. AdonisJS Extension
    • View application routes
    • Run Ace commands
    • Migrate database
    • Read docs directly in editor
  2. Edge Extension
    • Syntax highlighting
    • Autocomplete
    • Code snippets
  3. Japa Extension
    • Run tests without leaving editor
    • Execute tests with keyboard shortcuts

 

 

9. Useful Learning Resources and Community

Official Documentation and Guides

Free Learning Resources

Community

 

 

10. The Future of AdonisJS – v7 Roadmap

In June 2025, the AdonisJS team announced the v7 roadmap. Here’s a preview of the major changes:

Key Updates:

  • Node.js 24 will be the minimum required version
  • New Lucid ORM – auto-generate model columns from database, Value Objects support
  • HTTP Transformers – clearer control over data serialization
  • Type-safe routing
  • Improved Inertia support
  • Encryption updates
  • Flexible notification system

The AdonisJS team plans to publish major releases more frequently, but upgrades will be significantly smoother. A major version bump will no longer mean a full rewrite—you’ll be able to upgrade in just a few minutes.

 

 

AdonisJS occupies a unique yet practical position in the Node.js ecosystem. It’s not too minimal like Express, nor overly complex like NestJS. It strikes the perfect balance of “having everything you need without the complexity.”

AdonisJS isn’t an overnight success story. It’s a framework that’s evolved steadily over a decade. While it doesn’t have millions of GitHub stars, it has something more meaningful: a passionate, loving community. People who use AdonisJS tend to stick with it and often say they can’t imagine going back to anything else.

Where Should You Start?

  1. Beginners – Build a simple Todo app with web starter kit
  2. API Server Needed – Construct REST API with API starter kit
  3. Laravel Experience – You’ll feel at home quickly. Start now!
  4. Tired of Express – Experience how fast you can build the same features with AdonisJS

Queue functionality is planned for 2025, and v7 is in preparation, making this an increasingly exciting framework.

If you want high productivity without complex configuration, start with AdonisJS today!

 

 

Post Views: 10

Leave a Reply