이번 포스트에스는AdonisJS가 무엇인지, 왜 사용해야 하는지, 그리고 어떻게 시작하는지를 초보자도 따라할 수 있게 자세히 알려드려보고자 합니다.

Node.js로 백엔드를 개발하다 보면 항상 같은 고민에 빠지게 됩니다. Express는 너무 미니멀해서 매번 바퀴를 다시 발명하는 기분이고, NestJS는 배우기 어렵고 복잡하다는 느낌이 들죠.

“딱 필요한 기능은 다 있으면서, 복잡하지 않은 프레임워크는 없을까?” 그런 분들을 위한 프레임워크가 바로 AdonisJS입니다. AdonisJS를 처음 써 보면 “드디어 찾았다!”는 생각이 드실겁니다. 2025년 9월에 10주년을 맞이한 AdonisJS는 꾸준히 발전해온 안정적인 프레임워크입니다.

 

 

 

1. AdonisJS는 어떤 프레임워크인가요?

AdonisJS는 TypeScript를 우선으로 하는(TypeScript-first) Node.js 웹 프레임워크로, 웹 애플리케이션과 API 서버를 만들 수 있습니다. 쉽게 말하면, 웹사이트나 모바일 앱의 서버를 만들 때 사용하는 도구입니다.

가장 큰 특징은 “배터리 포함(Battery Included)” 방식입니다. 마치 새 스마트폰을 사면 바로 쓸 수 있게 충전기, 케이블이 다 들어있는 것처럼, AdonisJS도 개발에 필요한 모든 기능이 처음부터 준비되어 있습니다.

AdonisJS의 핵심 철학

AdonisJS는 개발자들이 npm 패키지를 고르고, 연결 코드를 작성하고, 폴더 구조를 고민하는 시간을 줄이고, 실제 비즈니스에 필요한 기능을 만드는 데 더 많은 시간을 쓰도록 돕는 것이 목표입니다.

Express를 써본 분들은 공감하실 겁니다. “이 기능 하나 추가하려면 어떤 라이브러리를 써야 하지?”, “다른 사람들은 폴더를 어떻게 구성하지?” 같은 고민에 하루를 다 쓴 경험 말이죠. AdonisJS는 이런 시간 낭비를 없애줍니다.

 

 

2. AdonisJS의 주요 특징 – 왜 선택해야 할까요?

최신 JavaScript와 TypeScript 기반

AdonisJS v6부터는 ECMAScript Modules(ESM)과 TypeScript를 기본으로 사용합니다. 이게 왜 중요할까요?

최신 JavaScript 생태계에서 많은 패키지들이 ESM으로 전환하고 있습니다. CommonJS만 사용하면 이런 최신 패키지를 사용하지 못하고, 보안 업데이트도 받을 수 없는 문제가 생깁니다. AdonisJS는 이런 미래를 미리 준비한 프레임워크입니다.

AdonisJS는 타입 안정성, 원활한 인텔리센스, 자동 import 지원에 특별히 신경을 씁니다. 코드를 작성하는 순간순간 IDE가 도와주는 걸 느낄 수 있습니다.

명확한 MVC 구조로 체계적인 개발

AdonisJS는 전통적인 MVC(Model-View-Controller) 디자인 패턴을 채택합니다. 처음 개발하는 분들에게는 “어디에 무엇을 작성해야 할지” 명확해서 특히 좋습니다.

• Models (모델) – 데이터베이스와 관련된 로직
• Views (뷰) – 사용자에게 보여지는 화면
• Controllers (컨트롤러) – 비즈니스 로직 처리

Laravel이나 Ruby on Rails를 써본 분들은 바로 친숙하게 느껴질 겁니다. Laravel 경험이 있고 Node.js를 시작하려는 개발자라면, AdonisJS는 Laravel을 TypeScript로 작성하는 것처럼 느껴져 하루 만에 시작할 수 있습니다.

강력한 ORM – Lucid

AdonisJS는 자체 ORM인 Lucid를 포함하고 있으며, PostgreSQL, MySQL, MSSQL, SQLite 등을 지원합니다.

// 사용자 조회 예시 - SQL 없이 직관적으로!
const users = await User.query()
  .where('active', true)
  .orderBy('created_at', 'desc')
  .limit(10)

복잡한 SQL 쿼리를 작성하지 않아도, 위처럼 읽기 쉬운 코드로 데이터베이스 작업을 할 수 있습니다.

개발에 필요한 모든 것이 기본 제공

AdonisJS는 Node.js 커뮤니티에서 드물게 퍼스트파티 패키지 전체 세트를 제공하는 프레임워크입니다.

기능	패키지명	설명
핵심 기능	@adonisjs/core	라우팅(Routing), 미들웨어(Middleware), 세션(Session)
데이터베이스	@adonisjs/lucid	SQL ORM, 쿼리 빌더
인증	@adonisjs/auth	세션, API 토큰, 소셜 로그인
보안	@adonisjs/shield	XSS, CSRF 보호
템플릿	edge.js	HTML 렌더링 엔진
검증	@vinejs/vine	Node.js에서 가장 빠른 검증 라이브러리
파일 처리	@adonisjs/drive	파일 업로드, 클라우드 저장소(S3, GCS) 지원

Express를 사용하면 이 모든 걸 직접 찾아서 조합해야 하지만, AdonisJS는 처음부터 다 준비되어 있습니다.

뛰어난 성능

AdonisJS의 HTTP 서버는 Fastify와 비슷한 성능을 보입니다. 실제 벤치마크 테스트에서 AdonisJS는 NestJS에 비해 거의 2배 가까운 성능을 보여줬습니다.

“기능이 많으면 느리지 않을까?” 걱정하실 수 있는데, 전혀 그렇지 않습니다. 오히려 Express보다 빠른 경우도 많습니다.

 

 

3. 어떤 개발자에게 AdonisJS가 적합할까요?

Laravel이나 Rails 개발자가 Node.js로 전환하는 경우

Laravel 경험이 있다면 AdonisJS의 구조가 매우 친숙하게 느껴질 것입니다. 파일 구조, 명명 규칙, 심지어 ORM 사용법까지 Laravel과 비슷합니다.

Express에 지친 개발자

“Express만 사용해서 3주 동안 고생한 것을, AdonisJS로는 이틀 만에 끝냈다”는 실제 사용자 후기가 있습니다. 매번 라이브러리를 찾고 연결하는 데 지쳤다면 AdonisJS를 시도해보세요.

체계적인 구조를 원하는 팀 프로젝트

빠른 애플리케이션 개발과 개발자 경험(Developer Experience)이 AdonisJS 팀의 최우선 목표입니다. 프로젝트 규모가 커져도 관리하기 쉬운 구조가 필요하다면 AdonisJS가 답입니다.

풀스택 프레임워크의 장점을 원하는 경우

Laravel이나 Rails 같은 풀스택 프레임워크의 장점을 Node.js에서 누리고 싶다면, AdonisJS가 최고의 선택입니다.

 

 

4. 다른 프레임워크와 비교하면 어떨까요?

AdonisJS vs Express

Express의 특징:

• 미니멀하고 자유도가 높음
• 모든 것을 직접 구성해야 함
• 작은 프로젝트에 적합

AdonisJS의 특징:

• ORM, 쿼리 빌더, 내장 인증 시스템 등 많은 기능이 이미 포함
• 체계적인 구조 제공
• 중대형 프로젝트에 적합

실제 개발 시간 비교:

• Express: 파일 업로드 → multer 찾기 → 설정 → 미들웨어 구성 → 보안 설정
• AdonisJS: 기본 제공 → 간단한 설정 변경만으로 완료

AdonisJS vs NestJS

AdonisJS는 MVC 패턴을 따르는 반면, NestJS는 모듈 기반 아키텍처를 사용합니다. AdonisJS는 자체 ORM인 Lucid를 제공하고, NestJS는 TypeORM, Sequelize 등 다양한 ORM을 선택할 수 있는 유연성을 제공합니다.

특징	AdonisJS	NestJS
기본 언어	JavaScript/TypeScript	TypeScript
패턴	MVC	모듈 기반
학습 곡선	낮음 (Laravel 유사)	높음 (Angular 유사)
ORM	Lucid (내장)	TypeORM, Sequelize 등 선택
철학	배터리 포함	모듈 선택의 자유
성능	매우 빠름	빠름
적합한 프로젝트	빠른 개발, 중소규모	엔터프라이즈, 대규모 마이크로서비스

어떤 걸 선택해야 할까요?

• 빠르게 프로토타입을 만들고 싶다 → AdonisJS
• Angular 경험이 있고 대규모 엔터프라이즈 앱을 만든다 → NestJS
• Laravel 스타일이 익숙하다 → AdonisJS
• 모든 걸 직접 선택하고 구성하고 싶다 → NestJS

 

Express.js란? – Node.js 기반 웹 애플리케이션 프레임워크

NestJS란? 확장성 높은 Node.js 백엔드 프레임워크

 

 

5. AdonisJS 시작하기 – 설치부터 첫 실행까지

자, 이제 실제로 AdonisJS를 설치하고 실행해보겠습니다. 초보자도 따라할 수 있게 단계별로 설명드릴게요.

사전 준비사항

Node.js 버전 20 이상이 필요합니다. 먼저 컴퓨터에 Node.js가 설치되어 있는지 확인해보세요.

터미널(또는 명령 프롬프트)을 열고 다음 명령어를 입력합니다:

node -v

v20.0.0 이상 버전이 표시되면 OK입니다. 만약 설치되어 있지 않거나 버전이 낮다면:

• Node.js 공식 웹사이트에서 다운로드하거나
• Volta를 사용하면 여러 버전의 Node.js를 쉽게 관리할 수 있습니다

새 프로젝트 생성하기

npm init 명령어를 사용해서 새 프로젝트를 생성할 수 있습니다.

# 기본 프로젝트 생성 (대화형 프롬프트가 나타남)
npm init adonisjs@latest my-app

# MySQL 데이터베이스를 사용하는 프로젝트
npm init adonisjs@latest my-app -- --db=mysql

# PostgreSQL과 API 스타터 킷
npm init adonisjs@latest my-app -- --db=postgres --kit=api

주의할 점: npm init 명령어에서 옵션을 전달할 때는 이중 대시(–)를 두 번 사용해야 합니다. 이렇게 하지 않으면 옵션이 제대로 전달되지 않습니다.

스타터 킷 선택하기 – 프로젝트 유형별 추천

AdonisJS는 프로젝트 성격에 맞는 여러 스타터 킷을 제공합니다.

1) 웹 스타터 킷 (Web Starter Kit) – 서버 렌더링 웹사이트

전통적인 서버 렌더링 웹 앱을 만들 때 적합합니다. 블로그, 관리자 페이지, 회사 웹사이트처럼 프론트엔드 인터랙션이 많지 않은 웹사이트를 만든다면 이것을 선택하세요.

npm init adonisjs@latest -- -K=web

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

포함된 주요 기능:

• Edge.js (템플릿 엔진) – HTML을 쉽게 작성
• Vite (프론트엔드 번들러) – CSS, JS 자동 처리
• Lucid (ORM) – 데이터베이스 연결
• Auth (인증) – 로그인/회원가입
• Shield (보안) – XSS, CSRF 보호
• Static (정적 파일) – 이미지, CSS, JS 파일 제공

나중에 Hotwire, HTMX, Alpine.js 같은 도구를 추가하면 SPA처럼 동작하는 웹사이트를 만들 수도 있습니다.

2) API 스타터 킷 (API Starter Kit) – REST API 서버

React나 Vue로 프론트엔드 앱을 만들 계획이라면, API 스타터 킷으로 백엔드를 만들면 됩니다.

npm init adonisjs@latest -- -K=api

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

# 토큰 기반 인증 사용
npm init adonisjs@latest -- -K=api --auth-guard=access_tokens

웹 스타터 킷과 비교했을 때:

• ❌ 정적 파일 제공 기능 제거
• ❌ 뷰 레이어와 Vite 설정 없음
• ✅ CORS 보호 활성화 (외부 도메인에서 API 호출 가능)
• ✅ 모든 응답을 JSON 형식으로 자동 변환

API 스타터 킷은 기본적으로 세션 기반 인증으로 설정되어 있지만, 토큰 기반 인증을 원한다면 –auth-guard 플래그를 사용할 수 있습니다.

3) 슬림 스타터 킷 (Slim Starter Kit) – 미니멀 구성

미니멀리스트를 위한 옵션으로, 프레임워크 핵심과 기본 폴더 구조만 제공합니다.

npm init adonisjs@latest -- -K=slim

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

불필요한 기능 없이 최소한만 사용하고 싶을 때 선택하세요.

4) Inertia 스타터 킷 – 모던 SPA

Inertia는 서버 주도 싱글 페이지 애플리케이션을 만드는 방법입니다. React, Vue, Solid, Svelte 중 선택할 수 있습니다.

# React + 서버 사이드 렌더링
npm init adonisjs@latest -- -K=inertia --adapter=react --ssr

# Vue (SSR 없이)
npm init adonisjs@latest -- -K=inertia --adapter=vue --no-ssr

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

개발 서버 실행하기

프로젝트가 생성되면, 폴더로 이동해서 개발 서버를 시작합니다:

cd my-app
node ace serve --hmr

Ace는 프레임워크 핵심에 포함된 커맨드라인 도구입니다. –hmr 플래그는 파일 시스템을 모니터링하고 Hot Module Replacement를 수행합니다.

Hot Module Replacement가 뭔가요? 코드를 수정하면 서버를 재시작하지 않아도 자동으로 변경사항이 반영됩니다. 개발할 때 시간을 엄청 절약해줍니다!

브라우저에서 http://localhost:3333을 열면 AdonisJS 환영 페이지가 보입니다. 성공입니다! 🎉

 

 

6. 첫 번째 API 만들어보기 – 할 일(Todo) API

이제 간단한 할 일 관리 API를 만들어보면서 AdonisJS의 작동 방식을 이해해봅시다.

단계 1: 간단한 라우트 만들기

start/routes.ts 파일을 열어서 라우트를 추가합니다:

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

// GET 요청 - 할 일 목록 조회
router.get('/todos', async () => {
  return [
    { id: 1, title: 'AdonisJS 배우기', completed: false },
    { id: 2, title: '블로그 글 작성하기', completed: true }
  ]
})

서버를 실행한 상태에서 브라우저나 Postman으로 http://localhost:3333/todos에 접속하면 JSON 응답을 받을 수 있습니다.

단계 2: 컨트롤러 만들기

실제 프로젝트에서는 라우트에 직접 코드를 작성하지 않고 컨트롤러를 사용합니다.

터미널에서 다음 명령어를 실행하세요:

node ace make:controller Todo

app/controllers/todos_controller.ts 파일이 자동으로 생성됩니다:

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

export default class TodosController {
  // 목록 조회
  async index({ response }: HttpContext) {
    const todos = [
      { id: 1, title: 'AdonisJS 배우기', completed: false },
      { id: 2, title: '블로그 글 작성하기', completed: true }
    ]
    return response.json(todos)
  }
}

start/routes.ts 파일을 수정합니다:

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

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

참고: #controllers는 AdonisJS v6에서 사용하는 특별한 경로 별칭(Path Alias)입니다. app/controllers를 가리킵니다.

단계 3: 데이터베이스 연결하기

실제 데이터를 저장하려면 데이터베이스를 연결해야 합니다. 여기서는 PostgreSQL을 예시로 설명하겠습니다.

프로젝트를 생성할 때 --db=postgres 옵션을 사용하지 않았다면:

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

프롬프트가 나타나면 PostgreSQL을 선택하세요.

.env 파일에서 데이터베이스 연결 정보를 설정합니다:

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

단계 4: 모델과 마이그레이션 만들기

node ace make:model Todo -m

-m 플래그는 마이그레이션 파일도 함께 생성합니다.

database/migrations/xxxx_create_todos_table.ts 파일이 생성됩니다. 내용을 다음과 같이 작성하세요:

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)
  }
}

마이그레이션을 실행해서 실제 데이터베이스에 테이블을 생성합니다:

node ace migration:run

app/models/todo.ts 파일을 다음과 같이 작성합니다:

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
}

단계 5: 컨트롤러에서 모델 사용하기

이제 실제 데이터베이스와 연동되도록 컨트롤러를 수정합니다:

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

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

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

  // 업데이트
  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)
  }

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

라우트를 한 줄로 추가합니다:

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

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

resource()와 apiOnly()가 자동으로 만들어주는 라우트:

• GET /todos → index (목록 조회)
• POST /todos → store (생성)
• GET /todos/:id → show (상세 조회)
• PUT/PATCH /todos/:id → update (수정)
• DELETE /todos/:id → destroy (삭제)

완성입니다! 이제 Postman이나 다른 API 테스트 도구로 테스트해보세요.

 

 

7. 프로덕션 배포 준비하기

AdonisJS 애플리케이션은 TypeScript로 작성되므로, 프로덕션에서 실행하기 전에 JavaScript로 컴파일해야 합니다.

node ace build

이 명령어는 다음 작업을 수행합니다:

1. 기존 build 폴더 제거
2. Vite로 프론트엔드 자산 컴파일 (설정된 경우)
3. tsc로 TypeScript를 JavaScript로 컴파일
4. 필요한 파일들을 build 폴더로 복사
5. package.json 복사

빌드가 완료되면:

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

실제 서버에 배포할 때는 PM2 같은 프로세스 매니저를 사용하는 것을 권장합니다:

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

 

 

8. 개발 환경 설정 – 더 나은 개발 경험을 위해

ESLint와 Prettier 사용하기

공식 스타터 킷은 이미 ESLint와 Prettier가 설정되어 있습니다. 다음 명령어로 실행할 수 있습니다:

# 코드 검사
npm run lint

# 자동 수정
npm run lint -- --fix

# 코드 포맷팅
npm run format

VSCode 확장 프로그램 설치하기

VSCode 사용자라면 다음 확장 프로그램을 설치하면 개발 경험이 크게 향상됩니다:

1. AdonisJS Extension
   • 애플리케이션 라우트 보기
   • Ace 명령어 실행
   • 데이터베이스 마이그레이션
   • 문서를 에디터에서 바로 읽기
2. Edge Extension
   • 문법 하이라이팅
   • 자동완성
   • 코드 스니펫
3. Japa Extension
   • 에디터를 떠나지 않고 테스트 실행
   • 키보드 단축키로 테스트 실행

 

 

9. 유용한 자료 출처와 커뮤니티

공식 문서 및 가이드

• AdonisJS 공식 문서 – 가장 정확하고 최신 정보
• AdonisJS GitHub – 소스코드와 이슈 트래킹
• AdonisJS 블로그 – 공식 블로그, 업데이트 소식

무료 학습 자료

• Let’s Learn AdonisJS 6 – 무료 스크린캐스트 시리즈 (영상으로 배우기)
• Edge.js 공식 문서 – 템플릿 엔진 가이드
• Japa 공식 문서 – 테스트 프레임워크 가이드

커뮤니티

• Discord 채널 – 실시간 질문과 답변
• GitHub Discussions – 긴 토론과 Q&A

 

 

10. 미래의 AdonisJS – v7 로드맵

2025년 6월, AdonisJS 팀은 v7 로드맵을 발표했습니다. 주요 변경사항을 미리 살펴보면:

주요 업데이트 내용:

• Node.js 24가 최소 요구 버전이 됩니다
• 새로운 Lucid ORM – 모델 컬럼을 데이터베이스에서 자동 생성하고, Value Objects 지원
• HTTP 트랜스포머 – 데이터 직렬화를 더 명확하게 제어
• 타입 안전 라우팅
• 향상된 Inertia 지원
• 암호화 업데이트
• 유연한 알림 시스템

AdonisJS 팀은 이제 메이저 릴리스를 더 자주 발표할 계획이지만, 업그레이드는 훨씬 쉬워질 것이라고 합니다. 메이저 버전 변경이 더 이상 전체 재작성을 의미하지 않으며, 몇 분 안에 업그레이드할 수 있게 됩니다.

 

 

AdonisJS는 Node.js 생태계에서 독특하면서도 실용적인 위치를 차지하고 있습니다. Express처럼 너무 미니멀하지도 않고, NestJS처럼 과도하게 복잡하지도 않습니다. 딱 중간 지점에서 “필요한 건 다 있고, 복잡하지 않은” 완벽한 균형을 잡은 프레임워크입니다.

AdonisJS는 하룻밤에 성공한 프로젝트가 아닙니다. 10년이라는 긴 시간 동안 꾸준히 발전해온 프레임워크이며, GitHub 스타가 수백만 개는 아니지만 더 의미 있는 것을 가지고 있습니다. 바로 열정적이고 사랑스러운 커뮤니티입니다. AdonisJS를 사용하는 사람들은 계속 사용하는 경향이 있으며, 다른 것으로 돌아갈 수 없다고 말하곤 합니다.

어디서부터 시작해야 할까요?

1. 처음 시작하는 분 – 웹 스타터 킷으로 간단한 Todo 앱 만들어보기
2. API 서버가 필요한 분 – API 스타터 킷으로 REST API 구축
3. Laravel 경험자 – 금방 익숙해질 것입니다. 바로 시작하세요!
4. Express에 지친 분 – AdonisJS로 같은 기능을 얼마나 빨리 만들 수 있는지 경험해보세요

2025년에는 Queue(큐) 기능도 추가될 예정이고, v7도 준비 중이니 앞으로 더욱 기대되는 프레임워크입니다.

복잡한 설정 없이, 높은 생산성으로 개발하고 싶다면 지금 바로 AdonisJS를 시작해보세요!