Container

API reference for the IoC Container used for dependency injection and service management in AdonisJS

The Container module provides dependency injection capabilities for AdonisJS applications. It re-exports all functionality from @adonisjs/fold, which is the underlying IoC container implementation.

Import

import { Container } from '@adonisjs/core/container'
import { inject } from '@adonisjs/core'
import type { ContainerBindings } from '@adonisjs/core/types'

ContainerBindings Interface

The ContainerBindings interface defines all services registered in the IoC container and available for dependency injection.

interface ContainerBindings {
  ace: Kernel
  dumper: Dumper
  app: ApplicationService
  logger: LoggerService
  config: ApplicationService['config']
  emitter: EmitterService
  encryption: EncryptionService
  hash: HashService
  server: HttpServerService
  router: HttpRouterService
  testUtils: TestUtils
  repl: Repl
}

Core Container Methods

make

Resolves a binding from the container.

const logger = await container.make('logger')

binding · keyof ContainerBindings · required

The name of the binding to resolve from the container.

return · Promise<T>

Returns a promise that resolves to the binding value.

bind

Binds a value or factory function to the container.

container.bind('myService', () => {
  return new MyService()
})

key · string · required

The binding key.

factory · (container: Container) => any · required

Factory function that returns the binding value.

bindValue

Binds a static value to the container.

container.bindValue('config', configObject)

key · string · required

The binding key.

value · any · required

The value to bind.

singleton

Binds a singleton to the container. The factory is called only once.

container.singleton('database', () => {
  return new Database()
})

key · string · required

The binding key.

factory · (container: Container) => any · required

Factory function that returns the singleton instance.

alias

Creates an alias for an existing binding.

container.alias('log', 'logger')

alias · string · required

The alias name.

binding · string · required

The original binding key.

has

Checks if a binding exists in the container.

if (container.has('logger')) {
  const logger = await container.make('logger')
}

key · string · required

The binding key to check.

return · boolean

Returns true if the binding exists.

hasBinding

Checks if a specific binding (not alias) exists.

if (container.hasBinding('logger')) {
  // logger is a direct binding
}

key · string · required

The binding key to check.

return · boolean

Returns true if the direct binding exists.

Dependency Injection

inject

Decorator for automatic dependency injection in class constructors.

import { inject } from '@adonisjs/core'

class UserController {
  @inject()
  constructor(
    protected logger: LoggerService,
    protected database: DatabaseService
  ) {}
}

The inject decorator automatically resolves constructor dependencies from the container.

Manual Injection

You can also manually specify injection tokens:

import { inject } from '@adonisjs/core'

class UserService {
  @inject(['logger', 'database'])
  constructor(
    protected logger: LoggerService,
    protected database: DatabaseService
  ) {}
}

tokens · string[]

Optional array of binding keys to inject. If not provided, the container will attempt to auto-resolve based on parameter types.

Container Events

The container emits events when bindings are resolved.

container_binding:resolved

Emitted when a container binding is resolved.

const emitter = await app.container.make('emitter')

emitter.on('container_binding:resolved', (event) => {
  console.log('Resolved:', event.binding)
  console.log('Value:', event.value)
})

event · ContainerResolveEventData

Event data containing binding information.

Show properties

binding · string

The name of the resolved binding.

value · any

The resolved value.

Available Container Services

The following services are pre-registered in the AdonisJS container:

ace

const ace = await app.container.make('ace')

ace · Kernel

The Ace command-line kernel for CLI commands.

app

const app = await container.make('app')

app · ApplicationService

The main application instance.

logger

const logger = await container.make('logger')

logger · LoggerService

The logger manager instance.

config

const config = await container.make('config')

config · ConfigProvider

The application configuration.

emitter

const emitter = await container.make('emitter')

emitter · EmitterService

The event emitter instance.

encryption

const encryption = await container.make('encryption')

encryption · EncryptionService

The encryption service for encrypting and decrypting data.

hash

const hash = await container.make('hash')

hash · HashService

The hash manager for password hashing.

server

const server = await container.make('server')

server · HttpServerService

The HTTP server instance.

router

const router = await container.make('router')

router · HttpRouterService

The HTTP router instance.

Usage Examples

Basic Service Resolution

import type { ApplicationService } from '@adonisjs/core/types'

// In a provider or during app lifecycle
const logger = await app.container.make('logger')
const router = await app.container.make('router')

logger.info('Application started')
router.get('/', async () => 'Hello World')

Creating Custom Bindings

// In a service provider
export class MyServiceProvider {
  async register() {
    this.app.container.singleton('myService', () => {
      return new MyService()
    })
  }
}

// Extend ContainerBindings type
declare module '@adonisjs/core/types' {
  interface ContainerBindings {
    myService: MyService
  }
}

Using Dependency Injection

import { inject } from '@adonisjs/core'
import type { LoggerService } from '@adonisjs/core/types'

export default class UsersController {
  @inject()
  constructor(protected logger: LoggerService) {}

  async index() {
    this.logger.info('Listing users')
    return []
  }
}

Type-Safe Container Access

import type { ApplicationService } from '@adonisjs/core/types'

class UserService {
  constructor(private app: ApplicationService) {}

  async sendEmail() {
    // Type-safe container access
    const logger = await this.app.container.make('logger')
    const emitter = await this.app.container.make('emitter')
    
    logger.info('Sending email')
    emitter.emit('email:sent', { to: '[e-mail]' })
  }
}

Conditional Bindings

if (app.inProduction) {
  app.container.singleton('cache', () => {
    return new RedisCache()
  })
} else {
  app.container.singleton('cache', () => {
    return new MemoryCache()
  })
}