DOCSEARCHbyAlgolia
Submit Docs

AdonisJS v6 Documentation

website·Indexed 37 days ago

https://v6-docs.adonisjs.com/guides/preface/introduction

Comprehensive guides and references for AdonisJS v6, a Node.js framework. Covers core concepts like routing, controllers, and dependency injection, as well as official packages for authentication (@adonisjs/bouncer, @adonisjs/ally), database integration (@adonisjs/lucid, @adonisjs/redis), and frontend tooling with Vite and Inertia.

Tokens
110.6K
Snippets
730
Records
806
Agent score
60%

What's inside AdonisJS

  1. Overview of AdonisJS

    AdonisJS is a TypeScript-first web framework for Node.js designed for building full-stack web applications or JSON API servers. It provides a structured environment with built-in support for Hot Module Replacement (HMR), a seamless TypeScript build process, and a collection of official packages for common tasks like email, validation, CRUD operations, and authentication. The framework is frontend-agnostic, meaning it can be paired with traditional template engines, JSON APIs for Vue/React, or Inertia.

  2. Overview of AdonisJS TypeScript build tools

    AdonisJS uses a combination of tools to handle TypeScript depending on the environment:

    • TSC (TypeScript Compiler): Used for type-checking and creating the final production build.
    • TS Node Maintained: A Just-in-Time (JIT) compiler used during development to execute TypeScript files without a manual compilation step.
    • SWC: A Rust-based compiler used in conjunction with TS Node during development to accelerate the JIT process.

  3. Overview of AdonisJS Assembler hooks

    Assembler hooks allow developers to execute custom code at specific points in the AdonisJS assembler lifecycle. They are typically used for tasks like file generation, code compilation, or injecting custom build steps. For example, the @adonisjs/vite package uses these hooks to build front-end assets when node ace build is executed.

  4. Overview of AdonisJS Authentication architecture

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

    • Guards: End-to-end implementations of a specific login type (e.g., session for cookies/sessions, access_tokens for opaque tokens).
    • Providers: Responsible for looking up users and tokens from a data source (e.g., the Lucid provider uses database models).

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

    Hot Module Replacement (HMR) in AdonisJS allows for reloading JavaScript modules after modification without restarting the entire process, resulting in a faster development feedback loop. Unlike frontend HMR (e.g., Vite), AdonisJS HMR is backend-focused and does not propagate updates to the browser or reconcile frontend state. It relies on Node.js loader hooks and works exclusively with dynamic imports. Critical application parts like Controllers, middleware, and event listeners are dynamically imported by default and thus support HMR without additional code changes.

  6. Architecture of custom authentication guards in AdonisJS

    Custom authentication guards in AdonisJS are built around two primary concepts:

    1. User Provider: Guards must be user-agnostic. They do not hardcode database queries but instead rely on a User Provider implementation passed via the constructor to find and manage users.
    2. Guard Implementation: The guard must implement the GuardContract interface, which defines the necessary APIs for the guard to integrate with the broader Auth layer.

  7. Configure AdonisJS packages via the configure command

    The configure command is used to set up a package. It imports the package's main entry point and executes its exported configure method. This method receives an instance of the Configure command, providing direct access to the stubs and codemods APIs.

  8. Understand AdonisJS governance roles and responsibilities

    AdonisJS follows a hierarchical governance structure to manage its ecosystem of packages:

    • Project Author (Harminder Virk): Responsible for overall governance, standards, and direction. Decides which projects live under the AdonisJS umbrella and assigns project leads.
    • Project Leads: Selected by the Project Author to lead specific packages. They have the final say in decision-making for their respective projects and set strategic objectives.
    • Core Team: Experienced contributors relied upon to write code and screen contributions. They provide guidance to the project lead and often have informal control over specific technical areas.
    • Contributors: Community members who benefit the project through bug reports, feature additions, or user support. They do not have direct commit authority but engage via RFCs, GitHub, and Discord.
    • Users: The primary audience who use the framework and can contribute via evangelism, feedback, and financial support.

  9. Manage application configuration files

    AdonisJS stores configuration files in the config directory. You can add custom files to this directory as needed. For secrets and environment-specific settings, use environment variables instead of hardcoding values in these files.

  10. Understand the purpose of the AdonisRC file

    The adonisrc.ts file configures the workspace settings of an AdonisJS application. It is used to register providers, define command aliases, specify files for production builds, and configure directory paths. Because this file is imported by tools outside the main application, you must not include application-specific code or environment-specific conditionals within it.

  11. Choose a SQL ORM or Query Builder for AdonisJS

    AdonisJS allows the use of any Node.js SQL library or ORM. While the core team maintains Lucid, other popular options include:

    • Lucid: An Active Record ORM and query builder built on Knex (official).
    • Prisma: A type-safe ORM with automated migrations and intuitive data models.
    • Kysely: A lean, end-to-end type-safe query builder without models.
    • Drizzle ORM: A lightweight TypeScript ORM popular within the community.
    • MikroORM: A maintained ORM built on top of Knex.
    • TypeORM: A widely used ORM in the TypeScript ecosystem.

  12. Understand and use AdonisJS Container Services

    Container services are JavaScript modules that wrap app.container.make calls. They allow developers to resolve pre-configured objects from the IoC container using standard ESM import statements instead of calling the container manually. This enables better IDE support (auto-imports) and a more unified syntax across the codebase.
    // Instead of this:
import app from '@adonisjs/core/services/app'
const db = await app.container.make('lucid.db')

// Use the container service:
import db from '@adonisjs/lucid/services/db'