or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ace-commands.mdapplication.mdauth-hash.mdcommands.mdconfig-env.mdevents.mdhelpers.mdhttp-server.mdindex.mdlogging.mdtest-utils.md
tile.json

tessl/npm-adonisjs--core

Core framework package for AdonisJS providing HTTP server management, dependency injection, CLI commands, authentication, hashing, configuration, event handling, logging and more.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@adonisjs/core@6.19.x

To install, run

npx @tessl/cli install tessl/npm-adonisjs--core@6.19.0

index.mddocs/

AdonisJS Core

AdonisJS Core is the comprehensive foundation framework package for building full-stack Node.js applications. It provides HTTP server management, dependency injection container, CLI command system (Ace), authentication and hashing, environment configuration, event system, logging, REPL, request body parsing, encryption, health checks, and testing utilities in a single, cohesive package.

Package Information

  • Package Name: @adonisjs/core
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @adonisjs/core

Core Imports

import { Ignitor } from "@adonisjs/core";

Individual module imports:

import { BaseCommand, Kernel } from "@adonisjs/core/ace";
import { Application } from "@adonisjs/core/app";
import { Container } from "@adonisjs/core/container";
import { Router, Server } from "@adonisjs/core/http";
import { Exception, createError } from "@adonisjs/core/exceptions";
import { vine } from "@adonisjs/core/vine";
import { AceFactory, IgnitorFactory, TestUtilsFactory } from "@adonisjs/core/factories";
import type { ContainerBindings, EventsList } from "@adonisjs/core/types";
import { AppProvider, HashProvider } from "@adonisjs/core/providers";
import { Dumper } from "@adonisjs/core/dumper";
import { stubsRoot } from "@adonisjs/core";

For CommonJS:

const { Ignitor } = require("@adonisjs/core");

Basic Usage

import { Ignitor } from "@adonisjs/core";

// Create application bootstrapper
const ignitor = new Ignitor(new URL("./", import.meta.url));

// Start HTTP server
const httpServer = ignitor.httpServer();
await httpServer.start(() => {
  console.log("Server started successfully");
});

// Or start Ace CLI
const ace = ignitor.ace();
await ace.handle(process.argv.slice(2));

Architecture

AdonisJS Core is built around several key architectural components:

  • Ignitor: Central application bootstrapper that manages the entire application lifecycle
  • Application Container: Dependency injection system powering all framework components
  • Modular Design: Each major capability (HTTP, CLI, Auth, etc.) is a separate module with clean interfaces
  • Service Providers: Auto-registration system for framework services and user-defined services
  • Process Management: Separate process classes for HTTP server, CLI commands, and test runner
  • Configuration System: Environment-aware configuration with type safety

Core Framework Components

Application Bootstrapping

Core application lifecycle management and dependency injection container. Essential for initializing and managing AdonisJS applications.

class Ignitor {
  constructor(appRoot: URL, options?: IgnitorOptions);
  createApp(environment: AppEnvironments): ApplicationService;
  httpServer(): HttpServerProcess;
  ace(): AceProcess;
  testRunner(): TestRunnerProcess;
  tap(callback: (app: ApplicationService) => void): this;
  terminate(): Promise<void>;
}

interface IgnitorOptions {
  importer?: Importer;
}

type AppEnvironments = "web" | "console" | "test" | "repl";

Application Bootstrapping

HTTP Server Management

Complete HTTP server functionality including routing, middleware, request/response handling, and body parsing.

class HttpServerProcess {
  start(callback?: () => void): Promise<void>;
  close(): Promise<void>;
}

// Key HTTP exports from @adonisjs/http-server
class Router {
  get(pattern: string, handler: RouteHandlerNode): Route;
  post(pattern: string, handler: RouteHandlerNode): Route;
  put(pattern: string, handler: RouteHandlerNode): Route;
  delete(pattern: string, handler: RouteHandlerNode): Route;
  group(callback: () => void): RouteGroup;
}

class Server {
  start(callback?: () => void): Promise<void>;
  close(): Promise<void>;
}

HTTP Server

CLI Commands (Ace)

Complete command-line interface system for building custom CLI commands, code generation, and development tools.

class Kernel extends AceKernel<typeof BaseCommand> {
  constructor(app: ApplicationService);
}

class BaseCommand extends AceBaseCommand {
  static options: CommandOptions;
  app: ApplicationService;
  createCodemods(): Promise<Codemods>;
  terminate(): Promise<void>;
}

interface CommandOptions {
  staysAlive?: boolean;
  startApp?: boolean;
}

CLI Commands

Authentication & Hashing

Secure hashing and authentication utilities with support for multiple hashing algorithms (Argon2, bcrypt, scrypt).

// Hash configuration and drivers
function defineConfig(config: HashConfig): HashConfig;

interface HashConfig {
  default: string;
  list: Record<string, HashDriverConfig>;
}

// Available drivers: argon, bcrypt, scrypt
const drivers: {
  argon: ArgonDriverFactory;
  bcrypt: BcryptDriverFactory;
  scrypt: ScryptDriverFactory;
};

Authentication & Hashing

Configuration & Environment

Environment-aware configuration system with type safety and validation.

// Configuration from @adonisjs/config
class ConfigManager {
  get<T = any>(key: string, defaultValue?: T): T;
  set(key: string, value: any): void;
  has(key: string): boolean;
}

// Environment from @adonisjs/env
class Env {
  get(key: string, defaultValue?: string): string;
  getOrFail(key: string): string;
  set(key: string, value: string): void;
}

Configuration & Environment

Event System

Pub/sub event system for building loosely coupled applications.

// Event emitter from @adonisjs/events
class Emitter {
  emit<T extends keyof EventsList>(event: T, data: EventsList[T]): void;
  on<T extends keyof EventsList>(event: T, handler: EventHandler<EventsList[T]>): void;
  off<T extends keyof EventsList>(event: T, handler: EventHandler<EventsList[T]>): void;
  once<T extends keyof EventsList>(event: T, handler: EventHandler<EventsList[T]>): void;
}

interface EventsList {
  'container_binding:resolved': ContainerResolveEventData<ContainerBindings>;
  'http:server_ready': { port: number; host: string; duration: [number, number] };
}

Event System

Logging

Multi-driver logging system with structured logging support.

// Logger from @adonisjs/logger
class LoggerManager {
  use(name?: string): Logger;
  info(message: string, meta?: any): void;
  error(message: string, meta?: any): void;
  warn(message: string, meta?: any): void;
  debug(message: string, meta?: any): void;
}

interface Logger {
  info(message: string, meta?: any): void;
  error(message: string, meta?: any): void;
  warn(message: string, meta?: any): void;
  debug(message: string, meta?: any): void;
}

Logging

Dumper

Development debugging utility for pretty-printing variables and objects with syntax highlighting.

class Dumper {
  dump(...values: any[]): void;
  dd(...values: any[]): never;
}

function defineConfig(config: DumperConfig): DumperConfig;

interface DumperConfig {
  enabled: boolean;
  theme: 'dark' | 'light';
  depth: number;
}

interface FactoryParameters {
  rcFileContents: Record<string, any>;
  config: Record<string, any>;
}

Exception Handling

Framework exception utilities for error management and custom error creation.

// Exception utilities from @poppinss/utils
class Exception extends Error {
  constructor(message: string, options?: ExceptionOptions);
  static create(message: string, code?: string): Exception;
}

function createError(
  message: string, 
  code?: string, 
  statusCode?: number
): Exception;

class RuntimeException extends Exception {}
class InvalidArgumentsException extends Exception {}

Validation (Vine Integration)

VineJS validation integration for request and data validation.

// VineJS validation integration
const vine: {
  string(): StringSchema;
  number(): NumberSchema;
  boolean(): BooleanSchema;
  object<T>(schema: T): ObjectSchema<T>;
  array<T>(schema: T): ArraySchema<T>;
  file(options?: FileRuleValidationOptions): FileSchema;
};

interface FileRuleValidationOptions {
  size?: string | number;
  extnames?: string[];
}

Helper Utilities

Core Helpers

Utility functions for common development tasks including parsing, security, and file operations.

// Helper functions from various utility libraries
function parseImports(code: string): Promise<Import[]>;
function cuid(): string;
function isCuid(value: string): boolean;

class VerificationToken {
  constructor(secret: string, purpose: string);
  generate(payload: any): string;
  verify(token: string): any;
}

// Utilities from @poppinss/utils
function slash(path: string): string;
function joinToURL(base: string, path: string): string;
function safeEqual(a: string, b: string): boolean;
class Secret {
  constructor(value: string);
  release(): string;
}

Helper Utilities

Test Utilities

Testing helpers and utilities for building robust test suites.

class TestUtils {
  cleanup(): Promise<void>;
  db(): DatabaseTestUtils;
  httpServer(): HttpTestUtils;
}

Test Utilities

Factory Classes

Factory classes for creating configured instances of core framework components.

// Factory classes from @adonisjs/core/factories
class IgnitorFactory {
  preload(action: (app: ApplicationService) => void | Promise<void>): this;
  merge(params: Partial<FactoryParameters>): this;
  withCoreProviders(): this;
  withCoreConfig(): this;
  create(appRoot: URL, options?: IgnitorOptions): Ignitor;
}

class AceFactory {
  make(ignitor: Ignitor): Promise<Kernel>;
  make(appRoot: URL, options?: IgnitorOptions): Promise<Kernel>;
}

class TestUtilsFactory {
  create(ignitor: Ignitor): TestUtils;
  create(appRoot: URL, options?: IgnitorOptions): TestUtils;
}

Built-in Commands

AdonisJS Core includes numerous built-in commands for development workflows:

  • serve: Start development server with hot reloading
  • build: Build application for production
  • test: Run application test suite
  • repl: Start interactive REPL session
  • add: Add and configure packages
  • configure: Configure packages post-installation
  • generate_key: Generate application encryption key

Built-in Commands

Service Providers

Built-in service providers that register and configure framework services.

// Core service providers from @adonisjs/core/providers/*

/**
 * Application provider - registers core application services
 */
class AppProvider {
  constructor(app: ApplicationService);
  register(): void | Promise<void>;
  boot(): void | Promise<void>;
}

/**
 * Hash provider - registers hash manager and drivers
 */
class HashProvider {
  constructor(app: ApplicationService);
  register(): void | Promise<void>;
  boot(): void | Promise<void>;
}

/**
 * REPL provider - registers REPL commands and functionality
 */
class ReplProvider {
  constructor(app: ApplicationService);
  register(): void | Promise<void>;
  boot(): void | Promise<void>;
}

/**
 * VineJS provider - registers Vine validation integration
 */
class VineJSProvider {
  constructor(app: ApplicationService);
  register(): void | Promise<void>;
  boot(): void | Promise<void>;
  ready(): void | Promise<void>;
}

/**
 * Edge provider - registers Edge template engine
 */
class EdgeProvider {
  constructor(app: ApplicationService);
  register(): void | Promise<void>;
  boot(): void | Promise<void>;
  ready(): void | Promise<void>;
}

Type Definitions Module

Comprehensive TypeScript type definitions accessible via the /types module export.

// Type definitions from @adonisjs/core/types
// Provides extensive type coverage for:

// Application container bindings
interface ContainerBindings {
  ace: Kernel;
  app: ApplicationService;
  config: ConfigManager;
  dumper: Dumper;
  emitter: Emitter;
  encryption: Encryption;
  env: Env;
  hash: HashManager;
  logger: LoggerManager;
  repl: Repl;
  router: Router;
  server: Server;
  testUtils: TestUtils;
  [key: string]: any;
}

// Event system types
interface EventsList {
  'container_binding:resolved': ContainerResolveEventData<ContainerBindings>;
  'http:server_ready': { port: number; host: string; duration: [number, number] };
  'http:request_completed': { request: HttpContext['request']; response: HttpContext['response'] };
  [key: string]: any;
}

// Health check system types
interface HealthCheckResult {
  displayName: string;
  health: {
    healthy: boolean;
    message?: string;
  };
  meta: Record<string, any>;
}

// Logger configuration types
interface LoggerConfig {
  enabled: boolean;
  name: string;
  level: string;
  redact?: string[];
  messageKey?: string;
  timestampKey?: string;
  levelKey?: string;
}

// Body parser types
interface BodyParserConfig {
  allowedMethods: string[];
  encoding: string;
  limit: string | number;
  types: string[];
}

// Helper utility types
interface FileValidationOptions {
  size?: string | number;
  extnames?: string[];
}

Types

interface ApplicationService {
  container: Container;
  config: ConfigManager;
  env: Env;
  logger: LoggerManager;
  terminate(): Promise<void>;
}

interface ContainerBindings {
  [key: string]: any;
}

type ConfigProvider<T> = {
  type: 'provider';
  resolver: (app: ApplicationService) => Promise<T>;
};

interface IgnitorOptions {
  importer?: Importer;
}

type Importer = (filePath: string) => Promise<any>;

interface ExceptionOptions {
  code?: string;
  status?: number;
  cause?: Error;
}

interface StringSchema {
  minLength(length: number): this;
  maxLength(length: number): this;
  email(): this;
  url(): this;
}

interface NumberSchema {
  min(value: number): this;
  max(value: number): this;
  positive(): this;
  negative(): this;
}

interface BooleanSchema {
  // Boolean validation schema
}

interface ObjectSchema<T> {
  // Object validation schema
}

interface ArraySchema<T> {
  minLength(length: number): this;
  maxLength(length: number): this;
}

interface FileSchema {
  size(value: string | number): this;
  extnames(extensions: string[]): this;
}

interface DumperConfig {
  enabled: boolean;
  theme: 'dark' | 'light';
  depth: number;
}

interface FactoryParameters {
  rcFileContents: Record<string, any>;
  config: Record<string, any>;
}