---
lang: en
title: 'Booting an Application'
keywords: LoopBack 4.0, LoopBack 4
tags:
sidebar: lb4_sidebar
permalink: /doc/en/lb4/Booting-an-Application.html
summary:
---

## What does Booting an Application mean?

A typical LoopBack application is made up of many artifacts in different files,
organized in different folders. **Booting an Application** means:

* Discovering artifacts automatically based on a convention (a specific folder
  containing files with a given suffix)
* Processing those artifacts (this usually means automatically binding them to the Application's Context)

`@loopback/boot` provides a Bootstrapper that uses Booters to automatically
discover and bind artifacts, all packaged in an easy-to-use Mixin.

### What is an artifact?

An artifact is any LoopBack construct usually defined in code as a Class. LoopBack
constructs include Controllers, Repositories, Models, etc.

## Usage

### @loopback/cli

New projects generated using `@loopback/cli` or `lb4` are automatically enabled
to use `@loopback/boot` for booting the Application using the conventions
followed by the CLI.

### Adding to existing project

See [Using the BootMixin](#using-the-bootmixin) to add Boot to your Project manually.

---

The rest of this page describes the inner workings of `@loopback/boot` for advanced use
cases, manual usage or using `@loopback/boot` as a standalone package (with custom
booters).

## BootMixin

Boot functionality can be added to a LoopBack 4 Application by mixing it with the
`BootMixin`. The Mixin adds the `BootComponent` to your Application as well as
convenience methods such as `app.boot()` and `app.booters()`. The Mixin also allows
Components to set the property `booters` as an Array of `Booters`. They will be bound
to the Application and called by the `Bootstrapper`.

Since this is a convention-based Bootstrapper, it is important to set a `projectRoot`,
as all other artifact paths will be resolved relative to this path.

_Tip_: `application.ts` will likely be at the root of your project, so its path can be
used to set the `projectRoot` by using the `__dirname` variable. _(See example below)_

### Using the BootMixin

`Booter` and `Binding` types must be imported alongside `BootMixin` to allow TypeScript
to infer types and avoid errors. _If using `tslint` with the `no-unused-variable` rule,
you can disable it for the import line by adding `// tslint:disable-next-line:no-unused-variable`
above the import statement_.

```ts
import {BootMixin, Booter, Binding} from "@loopback/boot";

class MyApplication extends BootMixin(Application) {
  constructor(options?: ApplicationConfig) {
    super(options);
    // Setting the projectRoot
    this.projectRoot = __dirname;
    // Set project conventions
    this.bootOptions: BootOptions = {
      controllers: {
        dirs: ['controllers'],
        extensions: ['.controller.js'],
        nested: true,
      }
    }
  }
}
```

Now just call `app.boot()` from `index.ts` before starting your Application using `app.start()`.

#### app.boot()

A convenience method to retrieve the `Bootstrapper` instance bound to the
Application and calls its `boot` function. This should be called before an
Application's `start()` method is called. _This is an `async` function and should
be called with `await`._

```ts
class MyApp extends BootMixin(Application) {}

async main() {
  const app = new MyApp();
  app.projectRoot = __dirname;
  await app.boot();
  await app.start();
}
```

#### app.booters()

A convenience method to manually bind `Booters`. You can pass any number of `Booter`
classes to this method and they will all be bound to the Application using the
prefix (`booters.`) and tag (`booter`) used by the `Bootstrapper`.

```ts
// Binds MyCustomBooter to `booters.MyCustomBooter`
// Binds AnotherCustomBooter to `booters.AnotherCustomBooter`
// Both will have the `booter` tag set.
app.booters(MyCustomBooter, AnotherCustomBooter);
```

## BootComponent

This component is added to an Application by `BootMixin` if used. This Component:

* Provides a list of default `booters` as a property of the component
* Binds the conventional Bootstrapper to the Application

_If using this as a standalone component without the `BootMixin`, you will need to
bind the `booters` of a component manually._

```ts
app.component(BootComponent);
```

## Bootstrapper

A Class that acts as the "manager" for Booters. The Bootstrapper is designed to be
bound to an Application as a `SINGLETON`. The Bootstrapper class provides a `boot()`
method. This method is responsible for getting all bound `Booters` and running
their `phases`. A `phase` is a method on a `Booter` class.

Each `boot()` method call creates a new `Context` that sets the `app` context
as its parent. This is done so each `Context` for `boot` gets a new instance of
`booters` but the same context can be passed into `boot` so selective `phases` can be
run in different calls of `boot`.

The Bootstrapper can be configured to run specific booters or boot phases
by passing in `BootExecOptions`. **This is experimental and subject to change. Hence,
this functionality is not exposed when calling `boot()` via `BootMixin`**.

To use `BootExecOptions`, you must directly call `bootstrapper.boot()` instead of `app.boot()`.
You can pass in the `BootExecOptions` object with the following properties:

| Property         | Type                    | Description                                      |
| ---------------- | ----------------------- | ------------------------------------------------ |
| `booters`        | `Constructor<Booter>[]` | Array of Booters to bind before running `boot()` |
| `filter.booters` | `string[]`              | Names of Booter classes that should be run       |
| `filter.phases`  | `string[]`              | Names of Booter phases to run                    |

### Example

```ts
import { BootMixin, Booter, Binding, Bootstrapper } from "@loopback/boot";

class MyApp extends BootMixin(Application) {}
const app = new MyApp();
app.projectRoot = __dirname;

const bootstrapper: Bootstrapper = await this.get(
  BootBindings.BOOTSTRAPPER_KEY
);
bootstrapper.boot({
  booters: [MyCustomBooter],
  filter: {
    booters: ["MyCustomBooter"],
    phases: ["configure", "discover"] // Skip the `load` phase.
  }
});
```

## Booters

A Booter is a class that is responsible for booting an artifact. A Booter does its
work in `phases` which are called by the Bootstrapper. The following Booters are
a part of the `@loopback/boot` package and loaded automatically via `BootMixin`.

### Controller Booter

This Booter's purpose is to discover [Controller](Controllers.md) type Artifacts and to bind
them to the Application's Context.

You can configure the conventions used in your
project for a Controller by passing a `controllers` object on `BootOptions` property
of your Application. The `controllers` object supports the following options:

| Options      | Type                 | Default              | Description                                                                                                   |
| ------------ | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `dirs`       | `string \| string[]` | `['controllers']`    | Paths relative to projectRoot to look in for Controller artifacts                                             |
| `extensions` | `string \| string[]` | `['.controller.js']` | File extensions to match for Controller artifacts                                                             |
| `nested`     | `boolean`            | `true`               | Look in nested directories in `dirs` for Controller artifacts                                                 |
| `glob`       | `string`             |                      | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). |

### Repository Booter

This Booter's purpose is to discover [Repository](Repositories.md) type Artifacts and to bind
them to the Application's Context. The use of this Booter requires `RepositoryMixin`
from `@loopback/repository` to be mixed into your Application class.

You can configure the conventions used in your
project for a Repository by passing a `repositories` object on `BootOptions` property
of your Application. The `repositories` object supports the following options:

| Options      | Type                 | Default              | Description                                                                                                   |
| ------------ | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| `dirs`       | `string \| string[]` | `['repositories']`   | Paths relative to projectRoot to look in for Repository artifacts                                             |
| `extensions` | `string \| string[]` | `['.repository.js']` | File extensions to match for Repository artifacts                                                             |
| `nested`     | `boolean`            | `true`               | Look in nested directories in `dirs` for Repository artifacts                                                 |
| `glob`       | `string`             |                      | A `glob` pattern string. This takes precendence over above 3 options (which are used to make a glob pattern). |

### Custom Booters

A custom Booter can be written as a Class that implements the `Booter` interface. The Class
must implement methods that corresponds to a `phase` name. The `phases` are called
by the Bootstrapper in a pre-determined order (unless overridden by `BootExecOptions`).
The next phase is only called once the previous phase has been completed for all Booters.

#### Phases

**configure**

Used to configure the `Booter` with its default options.

**discover**

Used to discover the artifacts supported by the `Booter` based on convention.

**load**

Used to bind the discovered artifacts to the Application.
