diff --git a/docs/cli-application/error-handling.mdx b/docs/cli-application/error-handling.mdx index 7a1a78ab..e84d7609 100644 --- a/docs/cli-application/error-handling.mdx +++ b/docs/cli-application/error-handling.mdx @@ -13,4 +13,130 @@ Understand how you can handle the errors of the CLI Application. ## Introduction -Coming soon +When you start a new Athenna project, error and exception +handling is already configured for you. But you can configure +your own extending the Athenna error handler. We'll dive +deeper into how to do that throughout this documentation. + +When you start a new Athenna project, error and exception +handling is already configured for you. But you can configure +your own extending the Athenna error handler. We'll dive deeper +into how to do that throughout this documentation. + +This documentation will cover about error handling in the **CLI** +application, which means that only errors that happens inside +the `handle()` method of commands and bellow that will be handled: + +```typescript title="app/console/commands/AppCommand.ts" +import { BaseCommand } from '@athenna/artisan' +import { AppService } from '#app/services/AppService' + +export class AppCommand extends BaseCommand { + public static signature(): string { + return 'app' + } + + public static description(): string { + throw new Error('This error will be handled by @athenna/core.') 👈 + + return `Get some information's about the application.` + } + + public async handle(): Promise { + const appService = ioc.safeUse('App/Services/AppService') + const json = JSON.stringify(appService.findOne(), null, 2) + + throw new Error('ConsoleExceptionHandler will handle this error.') 👈 + + this.logger.info(`Application information's: ${json}`) + } +} +``` + +:::info + +Errors handled by `@athenna/core` usually means that a +bootstrap failure has been found in your application. + +::: + +## Configuration + +The `debug` option in your `config/app.ts` configuration +file determines how much information about an error is +actually displayed to the user. By default, this option is +set to respect the value of the `APP_DEBUG` environment +variable, which is stored in your `.env` file. + +During local development, you should set the `APP_DEBUG` +environment variable to `true`. In your production +environment, this value should always be `false`. If the +value is set to `true` in production, you risk exposing +sensitive configuration values to your application's end +users. + +Every error will be logged by default using the `console` +driver from `@athenna/logger`. By default, Athenna uses the +`exception` channel of your `config/logging.ts` file to log +all exceptions that happens in your application. + +:::tip + +You can change the driver and formatter of `exception` +channel inside `config/logging.ts` file. This way you can +send all your error logs to another provider and with +a different formatter. + +::: + +## Custom exceptions + +You can create custom exception by executing the following +Artisan command: + +```shell +./node artisan make:exception BadCommandException +``` + +Next, import and raise the exception as follows. + +```typescript +import { BadCommandException } from '#app/exceptions/BadCommandException' + +throw new BadCommandException('Your command is bad.') +``` + +:::tip + +Always try to use a custom exception to throw your errors +inside Athenna. If you use `Error`, `TypeError` and other +classes, it will not be treated by the handlers and will +always be considered as a not treated exception. + +::: + +## Implementing your own exception handler + +Let's suppose you want to write a custom logic for handling +your exceptions. You can do so by creating your own +exception handler: + +```typescript title="app/console/exceptions/Handler.ts" +import { ConsoleExceptionHandler } from '@athenna/artisan' + +export class Handler extends ConsoleExceptionHandler { + public async handle(error: any) { + // Implement your own logic + } +} +``` + +Now you need to register your exception handler when +bootstrapping your application: + +```typescript title="bootstrap/main.ts" +await ignite.artisan(process.argv, { + displayName: 'Athenna', + exceptionHandlerPath: '#app/console/exceptions/Handler', 👈 +}) +``` diff --git a/docs/cli-application/publishing.mdx b/docs/cli-application/publishing.mdx index 3d97366d..0d55e492 100644 --- a/docs/cli-application/publishing.mdx +++ b/docs/cli-application/publishing.mdx @@ -13,4 +13,42 @@ Check how you can publish a global CLI application. ## Introduction -Coming soon +In this documentation section we are going to cover how +you can publish a global CLI application in NPM registry. + +## Logging in to NPM + +To publish your package on the NPM registry, you need to +have an account at NPM. If you don't have an account, +visit the [NPM sign up page](https://www.npmjs.com/signup) +to create one. + +After creating the account, open your terminal and run the +following command in the root of your package: + +```shell +npm login +``` + +You will get a prompt to enter your `username` and `password`. +If login is successful, you should see a message like this: + +```shell +Logged in as on https://registry.npmjs.org/. +``` + +## Publishing + +Now that you are authenticated, to publish a package to NPM +is very simple, just run the following command: + +```shell +npm publish --access public +``` + +If you have been following along, then congratulations! You +just published your first NPM package. + +You can visit the NPM website and run a search for your +package. You should see your package show up in the search results. + diff --git a/docs/cli-application/running.mdx b/docs/cli-application/running.mdx index ec1f023b..865c59a0 100644 --- a/docs/cli-application/running.mdx +++ b/docs/cli-application/running.mdx @@ -13,4 +13,48 @@ Check how to run your CLI commands in different scenarios. ## Introduction -Coming soon +The CLI application of Athenna can run in three ways. +Using the `./node artisan`, the npm scripts inside +`package.json` file or linking the CLI using `npm link`, +this way you can execute your CLI anywhere from your +terminal. As Artisan and npm scripts comes configured by +default in your application, we are going to focus in +`npm link` in this documentation. + +## Registering your CLI command name + +To register your CLI command name you need to add the +`bin` object inside your `package.json` file and set the +path to the entry point file of your CLI: + +```json +"bin": { + "yourCliCommand": "./bootstrap/main.js" +} +``` + +## Entrypoint file + +In our example we defined the `./bootstrap/main.js` +file as the entrypoint file of our CLI. By default, this +file comes with the shebang line +`#!/usr/bin/env -S node --experimental-import-meta-resolve` +in the top of the file. Without this line the `npm link` +command will not work. So just in case you want to define a +different entrypoint file, remember that +`#!/usr/bin/env -S node --experimental-import-meta-resolve` +should be on the top of this file. + +## Linking the CLI + +Now you just need to run the following command in your project root: + +```shell +npm link +``` + +And now the `yourCliCommand` will exist in your actual Node.js version: + +```shell +yourCliCommand --help +``` diff --git a/docs/rest-api-application/error-handling.mdx b/docs/rest-api-application/error-handling.mdx index 8b3c4b46..c38bf09c 100644 --- a/docs/rest-api-application/error-handling.mdx +++ b/docs/rest-api-application/error-handling.mdx @@ -15,8 +15,32 @@ Understand how you can handle the errors of the REST API application. When you start a new Athenna project, error and exception handling is already configured for you. But you can configure -your own extending the Athenna error handler. We'll dive -deeper into how to do that throughout this documentation. +your own extending the Athenna error handler. We'll dive deeper +into how to do that throughout this documentation. + +This documentation will cover about error handling in the **REST API** +application, which means that only errors that happens inside +routes and bellow that will be handled: + +```typescript title="routes/http.ts" +import { Route } from '@athenna/http' + +// If AppController.show throws, HttpExceptionHandler will handle it 👈 +Route.get('/', 'AppController.show') + +Route.get('/users', () => { + throw new Error('HttpExceptionHandler will handle this.') 👈 +}) + +throw new Error('This error will be handled by @athenna/core.') 👈 +``` + +:::info + +Errors handled by `@athenna/core` usually means that a +bootstrap failure has been found in your application. + +::: ## Configuration @@ -154,3 +178,12 @@ export class Handler extends HttpExceptionHandler { } } ``` + +Now you need to register your exception handler when +bootstrapping your application: + +```typescript title="bootstrap/main.ts" +await ignite.httpServer({ + exceptionHandlerPath: '#app/http/exceptions/Handler', 👈 +}) +```