docs: migrate missing pages from loopback.io

docs/site/Booting-an-Application.md

@@ -0,0 +1,238 @@
+---
+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.

docs/site/FAQ.md

@@ -16,6 +16,8 @@ summary: LoopBack 4 is a completely new framework, sometimes referred to as Loop
 - Suitable for small and large teams
 - Minimally opinionated, enforce your team's opinions instead
 
+See [Crafting LoopBack 4](Crafting-LoopBack-4.md) for more details.
+
 ### What’s the timeline for LoopBack 4?
 
 See [Upcoming releases](https://github.com/strongloop/loopback-next/wiki/Upcoming-Releases).