DOCSEARCHbyAlgolia
Submit Docs

AdonisJS Documentation

website·Indexed 31 days ago

https://adonisjs-docs-ja.vercel.app

A full-stack Node.js web framework. This documentation covers core concepts including the Lucid ORM, Ace CLI, EdgeJS templating engine, authentication, authorization via @adonisjs/bouncer, and HTTP request/response handling. It also provides guides on middleware, environment variables, testing with Japa and Playwright, and deployment for Node.js 20.6+.

Tokens
116.5K
Snippets
759
Records
825
Agent score
72%

What's inside AdonisJS

  1. Overview of AdonisJS Authentication Concepts

    AdonisJS authentication is built around two primary concepts: Guards and Providers.

    • Guards: Implement the end-to-end logic for a specific login type. For example, the session guard uses cookies and sessions, while the access_tokens guard uses tokens.
    • Providers: Responsible for retrieving users and tokens from the data source (e.g., a database). The built-in Lucid provider is commonly used to fetch users via Lucid models.

    Note: The auth package focuses on HTTP request authentication. It does not handle user registration (forms, email verification), account management (password recovery), or authorization/permissions (use the bouncer package for authorization).

  2. Overview of AdonisJS TypeScript Build Tools

    AdonisJS uses a combination of tools to handle TypeScript, separating development speed from production stability:

    • TSC (TypeScript Compiler): Used for type checking and creating production builds.
    • TS Node Maintained: A Just-in-Time (JIT) compiler that allows running TypeScript files without a separate compilation step during development.
    • SWC: A Rust-based compiler used in conjunction with TS Node to significantly speed up the JIT process during development.

  3. Overview of Hot Module Replacement (HMR) in AdonisJS

    Hot Module Replacement (HMR) in AdonisJS allows JavaScript modules to be reloaded after modification without restarting the entire process, providing a faster feedback loop. Unlike frontend HMR (e.g., Vite or Webpack), AdonisJS HMR is designed for the backend; it does not communicate with the browser or maintain frontend state. It leverages Node.js loader hooks and works exclusively with dynamic imports. Because core AdonisJS components like controllers, middleware, and event listeners are dynamically imported by default, they benefit from HMR without requiring code changes.

  4. Overview of AdonisJS Assembler Hooks

    Assembler Hooks allow you to execute code at specific points in the AdonisJS assembler lifecycle. The assembler handles tasks such as starting the development server, building the application, and running tests. These hooks are typically used for generating files, compiling code, or injecting custom build steps (e.g., how @adonisjs/vite builds frontend assets before the rest of the build process).

  5. Overview of AdonisJS Framework

    AdonisJS is a TypeScript-first web framework for Node.js designed for building full-stack web applications and JSON API servers. It provides a structured environment with a seamless TypeScript setup, Hot Module Replacement (HMR) for backend code, and a comprehensive collection of maintained packages. The framework is built on modern JavaScript primitives, utilizing ES modules, Node.js subpath import aliases, SWC for TypeScript execution, and Vite for asset bundling.

  6. Understand the AdonisJS HTTP Context

    The HttpContext class is instantiated for every incoming HTTP request. It acts as a request-specific store that holds all relevant information for the duration of that request. It is automatically passed to route handlers, middleware, and exception handlers.

  7. Understand the AdonisJS middleware execution flow

    AdonisJS middleware follows the Chain of Responsibility pattern and consists of two phases:

    1. Downstream Phase: Code executed before calling the next method. Used for processing the incoming request.
    2. Upstream Phase: Code executed after calling the next method. Used for inspecting or modifying the response.

    Note: You do not need to wrap next() in a try/catch block; AdonisJS automatically converts exceptions to HTTP responses via the global exception handler, ensuring upstream logic still executes.

  8. Understand the AdonisJS HTTP Layer Architecture

    The AdonisJS HTTP layer is a custom-built system (not based on a micro-framework) consisting of several key modules that handle the lifecycle of a web request:

    • Router: Defines application endpoints (routes) and maps them to handlers (closures or controllers).
    • Controllers: JavaScript classes used to organize business logic and handle specific HTTP requests.
    • HttpContext (ctx): An instance created for every incoming request that holds the request body, headers, and authenticated user information.
    • Middleware: Implements the 'Chain of Responsibility' pattern to intercept and respond to requests before they reach the route handler.
    • Global Exception Handler: A centralized location to catch exceptions during the request lifecycle and convert them into HTTP responses or log them to external services.
    • Server Module: Binds the router, middleware, and exception handler to the Node.js HTTP server.

  9. Implement MVC Architecture in AdonisJS

    AdonisJS follows the classic Model-View-Controller (MVC) design pattern. Developers define routes using a functional API, bind them to controllers to handle HTTP request logic, and use models to interact with the database. The controller then returns either a rendered view (template) for traditional web apps or a JSON response for API servers.
    // 1. Define Route (start/routes.ts)
import router from '@adonisjs/core/services/router'
const PostsController = () => import('#controllers/posts_controller')

router.get('posts', [PostsController, 'index'])

// 2. Controller Logic (app/controllers/posts_controller.ts)
import Post from '#models/post'
import type { HttpContext } from '@adonisjs/core/http'

export default class PostsController {
  async index({ view }: HttpContext) {
    const posts = await Post.all()
    
    // For Web Apps: Render a template
    return view.render('pages/posts/list', { posts })
    
    // For API Servers: Return data directly (automatically serialized to JSON)
    // return posts
  }
}

  10. Understand AdonisJS application entry points

    AdonisJS uses different entry points located in the bin directory to boot the application depending on the execution environment:

    • bin/server.ts: Boots the application to handle HTTP requests (used by node ace serve).
    • bin/console.ts: Boots the application to handle CLI commands via Ace.
    • bin/test.ts: Boots the application to run tests using Japa.

    All entry points use the Ignitor module to instantiate the Application class, initialize the app, and execute the main action (e.g., starting the HTTP server or running tests).

  11. Understand Async Local Storage (ALS) in Node.js

    AsyncLocalStorage allows you to create an asynchronous state that persists across callbacks and promise chains. It is similar to thread-local storage in other languages, enabling data to be stored and accessed throughout the duration of a web request or other asynchronous operation without explicitly passing the data as a parameter to every function.

  12. Understand AdonisJS project governance roles

    AdonisJS follows a hierarchical governance structure to manage its ecosystem of packages. The roles are defined as follows:

    • Author (Harminder Virk): Responsible for overall governance, standards, and direction. The Author decides if new projects should exist under AdonisJS, assigns Project Leads, and defines the framework's vision.
    • Project Lead: Leads specific packages. They make final decisions on all aspects of their assigned project, set strategic goals, and communicate them to the community. They cannot archive or delete a project from AdonisJS but can transition leadership if they stop working on it.
    • Core Team: Experienced contributors trusted to screen other contributions and write code directly. They provide guidance to Project Leads and often have informal control over specific areas of the source code.
      • Active Core Team: Regularly contribute via issue triage, bug fixes, documentation, or feature development.
      • Core Team Emeritus: Former core members recognized for past contributions who are no longer active but welcome to return.
    • Contributors: Community members who provide value (bug reports, RFC discussions, support, coding) but generally do not have direct write access to the project code. Anyone can become a contributor by performing a beneficial action for the project.
    • Users: The primary audience for the project. Users are encouraged to participate by providing feedback, promoting the project, and offering financial support via GitHub Sponsors.