From ac30342a9747efa79ba19be48a721e6d1c28395d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20P=C3=B6hls?= Date: Mon, 17 Jan 2022 06:07:04 +0100 Subject: [PATCH] wip --- bootstrappers.md | 89 ------------------------------------------ directory-structure.md | 38 ++++++++---------- navigation.js | 2 +- service-providers.md | 9 +++++ 4 files changed, 27 insertions(+), 111 deletions(-) delete mode 100644 bootstrappers.md create mode 100644 service-providers.md diff --git a/bootstrappers.md b/bootstrappers.md deleted file mode 100644 index fb11b4b..0000000 --- a/bootstrappers.md +++ /dev/null @@ -1,89 +0,0 @@ -# Supercharge Bootstrappers - - -## Introduction -Bootstrappers are the core of your Supercharge application. When starting your Supercharge Node.js server, the framework composes your whole application using the framework’s bootstrappers and your application bootstrappers. - -The idea of bootstrappers in Supercharge is to “register” functionality to the application. For example, reading the environment context of your Node.js proces happens in an environment bootstrapper when starting your application. Core bootstrappers load configurations, events, loggers, middleware, routes, or connect to the database. - - -## Configuration -Supercharge automatically loads core bootstrappers when starting your application. These core bootstrappers are environment, configuration, events, loggging, database, composing the HTTP and console kernels, loading routes and middleware. - -To load your own bootstrappers, open the `bootstrap/app.js` configuration file. This file exports an object containing the `bootstrappers` property exposing an array of bootstrappers: - -```js -module.exports = { - bootstrappers: [ - require('../app/bootstrappers/session'), - - // further bootstrappers come here - ] -} -``` - - -## Registering Bootstrappers -A default Supercharge installation registers the session bootstrapper providing server side sessions. If you don’t need sessions in your application, for example when developing stateless apps like APIs, you can remove the bootstrapper from the `bootstrappers` array. - -Register your own bootstrappers by adding them to the `bootstrappers` array in the `bootstrap/app.js` config file: - -```js -module.exports = { - bootstrappers: [ - require('../app/bootstrappers/session'), - - require('a-supercharge-package/bootstrapper'), - ] -} -``` - -The `require('a-supercharge-package/bootstrapper')` statement assumes that your `a-supercharge-package` has a `bootstrapper.js` file in the root of the package directory. The `require` method form Node.js will search for a file located at the defined package path. This allows you to reference a bootstrapper file without exporting it as the main entry point to your module. - - -## Bootstrappers and the Boot Method -Every bootstrapper in Supercharge must be a class. The constructor of your bootstrapper class receives the application instance. The application instance gives you access to the HTTP `server` and `console` kernel instances. - -For the actual bootstrapping, the framework calls the `async boot` method when starting the application. - -Depending on whether your want to extend the HTTP server or the console kernel, you have access to both: - -```js -class YourBootstrapper { - constructor ({ server, console }) { - this.server = server - this.console = console - } - -async boot () { - // - } -} - -module.exports = YourBootstrapper -``` - -Here’s a sample “maintenance bootstrapper” adding request lifecycle extension points (middleware) and two Craft console commands: - - -```js -const MaintenanceLifecycle = require('my-maintenance-package/middleware') -const StopMaintenanceCommand = require('my-maintenance-package/commands/stop') -const StartMaintenanceCommand = require('my-maintenance-package/commands/start') - -class MaintenanceBootstrapper { - constructor ({ server, console }) { - this.server = server - this.console = console - } - - async boot () { - await this.server.extClass(MaintenanceLifecycle) - - await this.console.addCommand(StopMaintenanceCommand) - await this.console.addCommand(StartMaintenanceCommand) - } -} - -module.exports = MaintenanceBootstrapper -``` diff --git a/directory-structure.md b/directory-structure.md index 65ebbca..9244b2e 100644 --- a/directory-structure.md +++ b/directory-structure.md @@ -4,9 +4,9 @@ ## Introduction Supercharge gives you a default directory structure that should work well for small and large applications. The Supercharge framework tightly integrates with the given application structure by loading files from directories in your `app` folder. -Of course, you’re free to modify the application structure, but make sure to use the corresponding Node.js imports and don’t rely on Supercharge’s globals then. +Of course, you’re free to modify the application structure. Make sure to update the corresponding Node.js imports when renaming folders or moving files. -Supercharge’s directory structure is inspired by the [Laravel](https://laravel.com) PHP framework. At first, it may overwhelm due to all the existing directories. You’ll quickly understand their use-case and value. It becomes a predictable and extensible architecture that is a joy to work with. +Supercharge’s directory structure is inspired by the [Laravel](https://laravel.com) PHP framework. We find this directory structure provides a predictable and extensible architecture that is a joy to work with. ```info New Supercharge applications don’t contain all folder by default to reduce noise. When extending your application by scaffolding files with [Craft](/docs/{{version}}/craft-cli), they are created for you automatically. @@ -14,71 +14,67 @@ New Supercharge applications don’t contain all folder by default to reduce noi ## Supercharge’s Application Directory -### The “app” Directory +### The `app` Directory The `app` directory is the core of your application. Everything related to your application should go in there. This directory contains subdirectories that we’ll explore soon. -### The “bootstrap” Directory +### The `bootstrap` Directory This directory contains all files related to Supercharge’s application lifecycle. It contains the `app.js` file allowing you to extend Supercharge with packages from the community by registering the related [bootstrappers](/docs/{{version}}/bootstrappers). It also contains the `lifecycle.js` file that allows you to intercept the application start and stop procedures. -### The “config” Directory +### The `config` Directory The `config` directory contains all your application configuration files. Have a look at the individual configuration files to become familiar with the available options to customize Supercharge’s behavior. -### The “public” Directory +### The `public` Directory This directory includes all your asset files, like JavaScript, CSS, and images. -### The “resources” Directory +### The `resources` Directory This directory contains the web views and raw asset files. Put all your JavaScript or CSS files in the `resources` directory if you create a build pipeline. Reference the final build output to the `public`folder, because Supercharge serves assets in your web views from there. -### The “storage” Directory +### The `storage` Directory All files generated by the framework should go into the `storage` directory. For example, logging to a file would store the log file within this storage folder. If you need to store something from your application, point the file handling to this directory. -### The “test” Directory +### The `test` Directory This directory includes all your application tests. To get started with testing in Supercharge, you should read the [Testing](/docs/{{version}}/testing) section. -## The “app” Directory +## The `app` Directory This directory contains the important files of your application, like `routes`, `models`, `middleware`, and more! You’ll find pre-configured directories, like `routes` and `plugins`. These directories build a starting point for you to extend and separate concerns. When starting a Supercharge server, it will automatically look folders in the `app` directory to auto-load. -### The “auth“ Directory +### The `auth` Directory This directory contains all your authentication related schemes and strategies. For example, an authentication strategy can be session-based authenticating requests using a session. You can read more on authentication and how it’s handled in Supercharge in the related [authentication docs](/docs/{{version}}/authentication). -### The “events“ Directory +### The `events` Directory You may guess what this directory contains (and you’re right): event classes. Use events to notify listeners about an action. Events are a great way to decouple logic into separate parts. For example, [scaffolding authentication in Supercharge](/docs/{{version}}/authentication) will create a `UserRegistered` event that fires on user sign-up. Add event listeners to, for example, send a welcome email to the newly registered user. -### The “listeners“ Directory +### The `listeners` Directory This directory contains all your event listeners. The listeners are classes that wait for a specific event to fire and then handle it. For example, you can add a `SendWelcomeMail` listener that waits for the `UserRegistered` event to fire and then send out a welcome email. -### The “mails“ Directory +### The `mails` Directory [Mailables](/docs/{{version}}/mailer) in Supercharge are JavaScript classes. Create all the emails you want to send out as a class. -### The “middleware“ Directory +### The `middlewar`` Directory This directory includes all your [HTTP middleware](/docs/{{version}}/middleware). Supercharge auto-loads all files in this directory and registers them as middleware to the HTTP core. -### The “models“ Directory +### The `models` Directory The `models` directory stores all your application models. Supercharge will create a `User` model when [scaffolding authentication](/docs/{{version}}/authentication). You can use and extend and update this model to your needs. -### The “plugins“ Directory -Supercharge uses hapi as the HTTP core and hapi uses plugins to isolate functionality in reusable components. Compose your own [plugins](/docs/{{version}}/plugins) and place them into the `plugins` directory. Supercharge will auto-load them when starting the HTTP server. - - -### The “routes“ Directory +### The `routes` Directory This directory contains all your HTTP server’s [routes](/docs/{{version}}/routing). When starting the server, Supercharge will load all files from the `routes` directory and register them to the server. diff --git a/navigation.js b/navigation.js index dce2bdf..271de3d 100644 --- a/navigation.js +++ b/navigation.js @@ -14,8 +14,8 @@ module.exports = { slug: 'getting-started', sections: { Installation: 'installation', - 'Configuration & Env': 'configuration', 'Directory Structure': 'directory-structure', + 'Configuration & Env': 'configuration', Application: 'application', // 'App Lifecycle': 'app-lifecycle', Development: 'development', diff --git a/service-providers.md b/service-providers.md new file mode 100644 index 0000000..48bedaf --- /dev/null +++ b/service-providers.md @@ -0,0 +1,9 @@ +# Service Providers + + +## Introduction +tba. + +```ts + +```