From a01d339b18160d1f1eb49bdaab51e8c70effb81b Mon Sep 17 00:00:00 2001 From: jlenon7 Date: Fri, 23 Feb 2024 19:29:32 +0000 Subject: [PATCH 1/3] feat: better explanation about the framework --- .github/ISSUE_TEMPLATE/bug.yml | 2 +- .github/ISSUE_TEMPLATE/question.yml | 2 +- .github/SUPPORT.md | 2 +- docs/getting-started/athennarc-file.mdx | 2 +- docs/getting-started/installation.mdx | 143 ++++++++++++++++++++++++ docusaurus.config.js | 9 +- static/css/icons.css | 8 +- 7 files changed, 161 insertions(+), 7 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 69608b31..3be9a4b0 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -16,7 +16,7 @@ body: attributes: value: | ## Ask for help through appropriate channels - If you feel unsure about the cause of the problem, consider asking for help on for example [StackOverflow](https://stackoverflow.com/questions/ask) or our [Discord](https://discord.gg/mZyBkA936X) before posting a bug report. The issue tracker is not a help forum. + If you feel unsure about the cause of the problem, consider asking for help on for example [StackOverflow](https://stackoverflow.com/questions/ask) or our [Discord](https://discord.gg/JdEbBAKw6X) before posting a bug report. The issue tracker is not a help forum. - type: markdown attributes: value: | diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml index f93f1fb6..2acd841c 100644 --- a/.github/ISSUE_TEMPLATE/question.yml +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -13,7 +13,7 @@ body: For anything else, such as questions or getting help, please see: - [The Athenna help page](https://athenna.io/help) - - [Our `#help` channel in Discord](https://discord.gg/j6FKKQQrW9) + - [Our `#help` channel in Discord](https://discord.gg/JdEbBAKw6X) - The [AthennaIO](https://stackoverflow.com/questions/tagged/AthennaIO) tag on [StackOverflow](https://stackoverflow.com/questions/ask) - type: checkboxes id: no-post diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index 4ffe3181..45f9168a 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -1,3 +1,3 @@ -Please note this issue tracker is not a help forum. We recommend using [StackOverflow](https://stackoverflow.com/questions/tagged/athennaio) or [Discord channel](https://discord.gg/mZyBkA936X) for questions. +Please note this issue tracker is not a help forum. We recommend using [StackOverflow](https://stackoverflow.com/questions/tagged/athennaio) or [Discord channel](https://discord.gg/JdEbBAKw6X) for questions. diff --git a/docs/getting-started/athennarc-file.mdx b/docs/getting-started/athennarc-file.mdx index d4919fa1..02134edb 100644 --- a/docs/getting-started/athennarc-file.mdx +++ b/docs/getting-started/athennarc-file.mdx @@ -246,7 +246,7 @@ resolve the paths of your application: ``` The paths above are the default ones used by Athenna to resolve -your application paths. You can change one of then or many +your application paths. You can change one of them or many if you want, your directories defined in `directories` property will always be merged with the defaults. diff --git a/docs/getting-started/installation.mdx b/docs/getting-started/installation.mdx index 08cdeca3..13255f73 100644 --- a/docs/getting-started/installation.mdx +++ b/docs/getting-started/installation.mdx @@ -8,6 +8,72 @@ description: How to install and set up your first Athenna project. How to install and set up your first Athenna project. +## Meet Athenna + +Athenna is a framework written specially for the Node.js runtime +with expressive and elegant syntax. The framework provides a reliable +code foundation and starting point for creating your application, +allowing you to focus on creating something amazing while we sweat the +details. + +Athenna strives to provide an amazing developer experience while +providing powerful features such as thorough dependency injection, +an expressive database abstraction layer, unit and e2e testing, +and more. + +Whether you are new to Node.js ecosystem or have years of experience, +Athenna is a framework that can grow with you. We'll help you take +your first steps as a developer or give you a boost as you take your +expertise to the next level. We can't wait to see what you build, make +sure to share it with us in our [Discord community](https://discord.gg/JdEbBAKw6X). + +:::tip + +New to Athenna? Check out the [Athenna YouTube channel](https://www.youtube.com/@athennaio) +for an infinity of hands-on videos! + +::: + +## Why Athenna? + +There are a variety of tools and frameworks available to you when building +a software using Node.js. However, we believe Athenna is the best choice for +building modern microservices. + +### A progressive framework + +We like to call Athenna a "progressive" framework. By that, we mean that +Athenna grows with you. If you're just taking your first steps into backend +development, Athenna's vast library of documentation, guides, and video +tutorials will help you learn the ropes without becoming overwhelmed. + +If you're a senior developer, Athenna gives you robust tools for dependency +injection, unit and e2e testing, database abstracted layer and more. +Athenna is fine-tuned for building professional applications and ready to +handle enterprise work loads. + +### A scalable framework + +Athenna is incredibly scalable. Thanks to the scaling-friendly nature of +Node.js and Athenna's built-in support for fast, distributed cache systems +like Redis, horizontal scaling with Athenna is a breeze. In fact, Athenna applications +have been easily scaled to handle hundreds of millions of requests per month. + +### An agnostic framework + +Athenna is perpect for building modern software using microservices architecture. +No matter what type of application you are creating, be it a REST API, a CLI, a Cron Job, +Athenna has a reliable solution foundation for each occasion, the only thing you will +need to take care is how your application will communicate with the external world. + +### A community framework + +Athenna is not reinventing the whell, the framework combines the best packages +in the Node.js ecosystem to offer the most robust and developer friendly +framework. We are always seeking for talented developers like you to +help us by [contributing to the framework](https://github.com/athennaio) and +make it even better. + ## Your first Athenna project ### Prerequisites @@ -81,3 +147,80 @@ file to bootstrap your application with predefined configurations. - The `watch` flag is meant to watch the file system for changes and restart your application automatically when doing some change on it. + +### What the 🤬 is `Path.boostrap('main.ts')`? + +Well, Athenna tries a lot to be a framework without opinion, one thing +that some frameworks do that makes them to have a lot of opinion is defining +crucial file paths where you can't touch that file without breaking everything. + +Athenna is not totally different from them in this aspect, as you can see, +the `node artisan serve` command depends on the existence of the `./bootstrap/main.ts` +file. To be able to be "opinion less" without losing DX (Developer Experience) +we ensure that you can easily configure this path the way you want by doing two +things: + +1. In all places of our documentation you will see that we always use the [`Path`](/docs/the-basics/helpers#path) +helper to reference file paths, so your brain could detect that the directory path +you just see is configurable. +2. Inside `.athennarc.json` file or the `athenna` property of your `package.json` you +have the [`directories` property](/docs/getting-started/athennarc-file#the-directories-property) +where you can modify any path supported by the [`Path`](/docs/the-basics/helpers#path) helper. + +Ok, now you might be asking yourself: what the 🤬 is `.athennarc.json`? Be patient, we +gonna see later on this documentation page 😆. + +## Initial configuration + +All of the configuration files for the Athenna framework are stored +in the `Path.config()` directory. Each option is documented, so feel +free to look through the files and get familiar with the options available +to you. + +Athenna needs almost no additional configuration out of the box. You are +free to get started developing! However, you may wish to review the +`Path.config('app.ts')` file and its documentation. It contains several +options such as timezone and locale that you may wish to change according +to your application. + +## Environment based configuration + +Since many of Athenna's configuration option values may vary depending on +whether your application is running on your local machine or in production, +many important configuration values are defined using the `.env` file that +exists at the root of your application. + +Your `.env` file should not be committed to your application's source control, +since each developer / server using your application could require a different +environment configuration. Furthermore, this would be a security risk in the +event an intruder gains access to your source control repository, since any +sensitive credentials would get exposed. + +:::note + +For more information about the `.env` file and environment based configuration, +check out the full [configuration documentation](/docs/getting-started/configuration). + +::: + +## Workspace and runtime configurations + +Inside the root directory of your project, there is a file +called `.athennarc.json` or the `athenna` property of your +`package.json`. These configurations are used by Athenna +for configuring the workspace and certain runtime +settings of your Athenna application. Basically any configuration +related to how the framework will bootstrap and behave should be +defined in these configuration. + +:::note + +Always remember that if you can't find the `.athennarc.json` file +in the root path of you project, it will be defined inside of your +`package.json` in the `athenna` property. + +For more information about the RC file, more details about each one +of its options and also how to define your own properties inside of it +check out the full [Athenna RC file documentation](/docs/getting-started/athennarc-file). + +::: diff --git a/docusaurus.config.js b/docusaurus.config.js index dde3ff20..6454b737 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -90,7 +90,7 @@ const config = { html: '', }, { - href: 'https://discord.gg/mZyBkA936X', + href: 'https://discord.gg/JdEbBAKw6X', 'aria-label': 'Discord', className: 'navbar__icon navbar__discord', position: 'right', @@ -103,6 +103,13 @@ const config = { position: 'right', html: '', }, + { + href: 'https://www.youtube.com/watch?v=wNMrx6OGKFk', + 'aria-label': 'YouTube', + className: 'navbar__icon navbar__youtube', + position: 'right', + html: '', + }, ], }, prism: { diff --git a/static/css/icons.css b/static/css/icons.css index 461f15e2..fc50cdaa 100644 --- a/static/css/icons.css +++ b/static/css/icons.css @@ -23,11 +23,15 @@ font-size: 1.24rem; } -html[data-theme='light'] .navbar__github .navbar__discord .navbar__twitter { +.navbar__youtube { + font-size: 1.24rem; +} + +html[data-theme='light'] .navbar__github .navbar__discord .navbar__twitter .navbar__youtube { color: #000; } -html[data-theme='dark'] .navbar__github .navbar__discord .navbar__twitter { +html[data-theme='dark'] .navbar__github .navbar__discord .navbar__twitter .navbar__youtube { color: #fff; } From a04d4cb3c9631ab060016312ef6305e8e01859c8 Mon Sep 17 00:00:00 2001 From: jlenon7 Date: Fri, 23 Feb 2024 19:33:15 +0000 Subject: [PATCH 2/3] feat: add env value in some examples --- docs/architecture-concepts/application-lifecycle.mdx | 1 + docs/getting-started/athennarc-file.mdx | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/architecture-concepts/application-lifecycle.mdx b/docs/architecture-concepts/application-lifecycle.mdx index d50a5e78..28b912de 100644 --- a/docs/architecture-concepts/application-lifecycle.mdx +++ b/docs/architecture-concepts/application-lifecycle.mdx @@ -303,6 +303,7 @@ executed the `hello` command defined in our `.athennarc.json` file: "commands": { "hello": { "path": "#app/console/commands/HelloCommand", + "env": "local", "loadApp": false, "stayAlive": false, "loadAllCommands": false, diff --git a/docs/getting-started/athennarc-file.mdx b/docs/getting-started/athennarc-file.mdx index 02134edb..af119c77 100644 --- a/docs/getting-started/athennarc-file.mdx +++ b/docs/getting-started/athennarc-file.mdx @@ -163,6 +163,7 @@ of it could be the command path or an object with the "make:exception": "@athenna/core/commands/MakeExceptionCommand", "make:facade": { "path": "@athenna/core/commands/MakeFacadeCommand", + "env": "local", "destination": "./src/providers/facades", "loadApp": false, "stayAlive": false, From 56b4b3d5d9fa1fb3429deb1c036996b95d9008ae Mon Sep 17 00:00:00 2001 From: jlenon7 Date: Fri, 23 Feb 2024 20:13:58 +0000 Subject: [PATCH 3/3] feat: add docs for commands options in rc --- docs/getting-started/athennarc-file.mdx | 28 +++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/getting-started/athennarc-file.mdx b/docs/getting-started/athennarc-file.mdx index af119c77..63bdaaa0 100644 --- a/docs/getting-started/athennarc-file.mdx +++ b/docs/getting-started/athennarc-file.mdx @@ -167,12 +167,40 @@ of it could be the command path or an object with the "destination": "./src/providers/facades", "loadApp": false, "stayAlive": false, + "loadAllCommands": false, "environments": ["console"] } } } ``` +Depending on the command you are running, it got their +own configurations. Commands like `make:...` for example, +reads the `destination` property to the file generated +for a different path from it default. + +There are properties that you can define whatever your +command. Let's see who they are and what they do: + +- **`path`** - Defines the path to your command, this field is mandatory +if you are using an object to define your command. +- **`loadApp`** - If `true`, the `Ignite.fire()` method will be called +until running your command. The `Ignite.fire()` method is responsible +to load your env file and configuration files and also boot your +service providers. +- **`env`** - Defines which env file will be used to run your command. +This field is not required and it will only be relevant when the +`loadApp` property is `true`. +- **`stayAlive`** - If `true`, your command will stay running until the +event loop is not in use anymore. Very useful for keep running +background tasks from commands. +- **`loadAllCommands`** - If `true`, all the commands inside the `commands` +property will be loaded. Useful when you command needs to call other command +programmatically. +- **`environments`** - Only relevant when `loadApp` is `true`. The environments +set will be used as parameter for `Ignite.fire()` method and will help +Athenna to select the service providers that should or shouldn't be booted. + :::tip More information about commands could be found at