Merge pull request #55 from expressots/feature/update-cli-doc

refactor: update cli 1.11.1
expressots · Aug 4, 2024 · 1c772ed · 1c772ed
2 parents eafeacc + 09e2446
commit 1c772ed
Show file tree

Hide file tree

Showing 12 changed files with 751 additions and 428 deletions.
diff --git a/docs/cli/generate.md b/docs/cli/generate.md
@@ -13,20 +13,20 @@ This command allows developers to stay ahead of the curve by generating the boil
 The generate command can be executed as follows:
 
 ```bash
-expressots generate <resource> <structure>
+expressots generate <resource> <structure> [options]
 ```
 
 Or in its short form:
 
 ```bash
-expressots g <resource> <structure>
+expressots g <resource> <structure> [options]
 ```
 
 ### Command Structure
 
 We provide two different structures to scaffold the resources:
 
--   **[entity-action]**: `expressots generate service user-create`
+-   **[shorthand]**: `expressots generate service user-create`
     This will create this folder structure: `/user/create` and the file: `user-create.[resource].ts`
 
 -   **[folder/subfolder/resource]**: `expressots generate service user/create`
@@ -58,49 +58,19 @@ Current available resources:
 
 All resources can be created using the structure `folder/subfolder/resource`.
 
-## Scaffolding using hyphenated names
+## Scaffolding Using Shorthand Operation
 
-For services, you can take advantage of creating the use case, controller and DTO at once using the structure `entity_action` or `entity-action`. Example: `expressots g s user-create`.
+For services, you can take advantage of creating the use case, controller and DTO at once using the structure `entity_action` or `entity-action`. Example:
 
-:::info
-The `expressots.config.ts` configuration file, located in the project root folder, determines where all resources will be created.
-:::
-
-## ExpressoTS Config File
-
-The configuration file is located in the root folder of the project and it's called `expressots.config.ts`. This file is used to configure the CLI and the project.
-
-Here is the current configuration file with all the available options:
-
-```typescript
-import { ExpressoConfig, Pattern } from "@expressots/core";
-
-const config: ExpressoConfig = {
-    sourceRoot: "src",
-    scaffoldPattern: Pattern.KEBAB_CASE,
-    opinionated: true,
-    scaffoldSchematics: {
-        entity: "entity",
-        provider: "provider",
-        module: "module",
-        controller: "controller",
-        dto: "dto",
-        middleware: "middleware",
-        usecase: "useCases",
-    },
-};
-
-export default config;
+```bash
+expressots g s user-create
 ```
 
--   **sourceRoot**: the root folder that will be used by the CLI to create the resources. Default: `src`
--   **scaffoldPattern**: the pattern that will be used to create the resources. Default: `Pattern.KEBAB_CASE`. Example: `user-create`
--   **opinionated**: if true, the CLI will create the resources using the opinionated folder structure
--   **scaffoldSchematics**: the folder convention names for each resource. Default: `useCases`, `entities`, `providers`, `middlewares`, `controllers`, `dtos`
-
-## Recommendations
+:::info
+The `expressots.config.ts` configuration file, located in the project root folder, determines where all resources will be created. Also determine the resource names for each type of resource.
+:::
 
-Try to use as many different forms of creating resources as possible. This will help you to understand how the CLI works and how to use it in your favor. It also helps us improve the CLI to make it more robust.
+Read more about the [ExpressoTS Config File](/docs/overview/expressots-config.md).
 
 ---
 

diff --git a/docs/cli/overview.md b/docs/cli/overview.md
@@ -4,10 +4,10 @@ sidebar_position: 1
 
 # Overview
 
-The ExpressoTS CLI is a command-line interface tool that helps you to `create` ExpressoTS projects and `scaffold` the application resources such as use cases, controllers, dto's, providers and services.
+ExpressoTS CLI is a command-line interface tool that helps you to `create` ExpressoTS projects and `scaffold` ExpressoTS resources.
 
 :::info
-We use the `npm` package manager in this tutorial, but you can use your favorite package manager, such as `yarn` or `pnpm`.
+We use the `npm` package manager in this tutorial for simplicity. However, you can use `yarn` or `pnpm` as well.
 :::
 
 ## Installation
@@ -18,7 +18,28 @@ First install the CLI globally using the command below:
 npm install -g @expressots/cli
 ```
 
-## Basic usage
+## Commands Available
+
+| Name        | Alias  | Description                                           |
+| ----------- | ------ | ----------------------------------------------------- |
+| new project | new    | Generate a new project                                |
+| info        | i      | Provides project information                          |
+| resources   | r      | Displays CLI commands and resources                   |
+| help        | h      | Show command help                                     |
+| service     | g s    | Generate a service [controller, usecase, dto, module] |
+| controller  | g c    | Generate a controller                                 |
+| usecase     | g u    | Generate a usecase                                    |
+| dto         | g d    | Generate a DTO                                        |
+| entity      | g e    | Generate an entity                                    |
+| provider    | g p    | Generate internal provider                            |
+| provider    | add    | Add external provider to the project                  |
+| provider    | create | Create external provider                              |
+| module      | g mo   | Generate a module                                     |
+| middleware  | g mi   | Generate a middleware                                 |
+
+## Usage Examples
+
+The CLI has the following syntax:
 
 ```bash
 expressots <command> [options]
@@ -29,28 +50,26 @@ expressots <command> [options]
 Verify the available commands and options:
 
 ```bash
-expressots --help
+expressots help
 ```
 
 ### Info
 
 Providers information about your Operational System, Project and CLI version:
 
 ```bash
-expressots info or i
+expressots info
 ```
 
 ### Resources list
 
 List all available resources to scaffold:
 
 ```bash
-expressots resources or r
+expressots resources (Alias: r)
 ```
 
-![Resources](../overview/img/scaffold-resources.png)
-
-## Create a Project
+### Create a Project
 
 There are two options to create a new project, interactively or silently (passing the options as arguments).
 Here is the complete command syntax:
@@ -59,13 +78,13 @@ Here is the complete command syntax:
 expressots new <project-name> -p <package-manager> -t <template> -d <directory>
 ```
 
-### Interactively
+#### Interactively
 
 ```bash
 expressots new <project-name>
 ```
 
-### Silently
+#### Silently
 
 ```bash
 expressots new <project-name> -p <package-manager> -t <template> -d <directory>
@@ -77,6 +96,115 @@ expressots new <project-name> -p <package-manager> -t <template> -d <directory>
 
 The flag `-d` is optional and is used to specify the directory where the project will be created. If not specified, the project will be created in the current directory.
 
+### Add a Provider
+
+Add an external provider to the project:
+
+```bash
+expressots add <provider-name>
+```
+
+### Create a Provider
+
+Create a new ExpressoTS provider. For more information about providers, check the [Providers](/docs/overview/providers.md#creating-and-registering-an-external-provider) section.
+
+```bash
+expressots create <provider-name>
+```
+
+## Scaffold Resources
+
+The CLI provides commands to scaffold resources like `controller`, `usecase`, `dto`, `entity`, `module` and `middleware`.
+
+```bash
+expressots generate <resource> <name> [options]
+```
+
+Resources are created in the `src` directory by default. They also can be scaffolded in 2 different ways: `passing the path` or using the `shorthand operation`.
+
+:::caution
+The resource scaffolding operations produce different results based on the project template used. The `opinionated` template provides a more structured project, while the `non-opinionated` template provides a more flexible project structure.
+:::
+
+### Non Opinionated Scaffold
+
+#### Passing the Path
+
+```bash
+expressots g c services/user
+```
+
+The command above will create a controller named `user` inside the `services` directory.
+
+```bash
+src
+└── services
+    └── user.controller.ts
+```
+
+#### Shorthand Operation
+
+```bash
+expressots g c services-user
+```
+
+The command above will create a controller named `services-user` inside the `services/user` directory.
+
+```bash
+src
+└── services
+    └── user
+        └── services-user.controller.ts
+```
+
+### Opinionated Scaffold
+
+In the `opinionated` template, the scaffolded resources are created following a predefined structure.
+
+-   [@providers](/docs/overview/providers.md)
+-   [@entities](/docs/overview/entities.md)
+-   [@useCases](/docs/overview/usecase.md)
+-   [@repositories](/docs/overview/repositories.md)
+
+#### Passing the Path
+
+```bash
+expressots g c services/user
+```
+
+The command above will create a controller named `user` inside the `useCases/services` directory.
+
+```bash
+src
+└── useCases
+    └── services
+        └── user.controller.ts
+```
+
+:::info
+dto, usecase, controller, modules will be created in the `useCases` directory.
+:::
+
+#### Shorthand Operation
+
+```bash
+expressots g c services-user
+```
+
+The command above will create a controller named `services-user` inside the `useCases/services/user` directory.
+
+```bash
+src
+└── useCases
+    └── services
+        └── user
+            └── services-user.controller.ts
+```
+
+:::info
+Using the shorthand operation in the opinionated template offers significant benefits. It creates a well-structured project that's easier to navigate and understand. When you scaffold with the shorthand, the CLI automatically places resources in the correct directories, adds controllers to their modules, and integrates the module into the container.
+:::
+
 ---
 
 ## Support the Project
@@ -89,3 +217,15 @@ ExpressoTS is an MIT-licensed open source project. It's an independent project w
 -   Join our **[Discord](https://discord.com/invite/PyPJfGK)**
 -   Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)**
 -   Share the project with your friends and colleagues
+
+```
+
+```
+
+```
+
+```
+
+```
+
+```
diff --git a/docs/overview/application.md b/docs/overview/application.md
@@ -116,16 +116,16 @@ Another important aspect of the Application class is lifecycle hooks. These hook
 
 Scripts for building, running, and testing the application are provided, accommodating different development stages and operational needs, from development to production.
 
-| Script               | Description                                     | Command            |
-| -------------------- | ----------------------------------------------- | ------------------ |
-| expressots run build | Build the production bundle in a ./dist folder. | npm run build      |
-| expressots run dev   | Runs in development watch mode.                 | npm run dev        |
-| expressots run prod  | Runs in production mode based on built bundle.  | npm run prod       |
-| test                 | Run your tests located in the test folder.      | npm run test       |
-| test:watch           | Run your tests in watch and interactive mode.   | npm run test:watch |
-| test:cov             | Produces test coverage report.                  | npm run test:cov   |
-| format               | Format the code using prettier.                 | npm run format     |
-| lint                 | Lint code using eslint.                         | npm run lint       |
+| Script           | Description                                     | Command            |
+| ---------------- | ----------------------------------------------- | ------------------ |
+| expressots build | Build the production bundle in a ./dist folder. | npm run build      |
+| expressots dev   | Runs in development watch mode.                 | npm run dev        |
+| expressots prod  | Runs in production mode based on built bundle.  | npm run prod       |
+| test             | Run your tests located in the test folder.      | npm run test       |
+| test:watch       | Run your tests in watch and interactive mode.   | npm run test:watch |
+| test:cov         | Produces test coverage report.                  | npm run test:cov   |
+| format           | Format the code using prettier.                 | npm run format     |
+| lint             | Lint code using eslint.                         | npm run lint       |
 
 ## Starting the application
 

diff --git a/docs/overview/expressots-config.md b/docs/overview/expressots-config.md
@@ -0,0 +1,63 @@
+---
+sidebar_position: 18
+---
+
+# ExpressoTS Config File
+
+The ExpressoTS configuration file is located in the root folder of the project and it's called `expressots.config.ts`. This file is used to configure the CLI and the project.
+
+Here is the current configuration file with all the available options:
+
+```typescript
+import { ExpressoConfig, Pattern } from "@expressots/core";
+
+const config: ExpressoConfig = {
+    sourceRoot: "src",
+    scaffoldPattern: Pattern.KEBAB_CASE,
+    opinionated: true,
+    scaffoldSchematics: {
+        entity: "entity",
+        provider: "provider",
+        module: "module",
+        controller: "controller",
+        dto: "dto",
+        middleware: "middleware",
+        usecase: "useCases",
+    },
+};
+
+export default config;
+```
+
+-   **sourceRoot**: the root folder that will be used by the CLI to create the resources. Default: `src`
+
+-   **scaffoldPattern**: the pattern that will be used to create the resources. Default: `Pattern.KEBAB_CASE`. Example: `user-create`
+
+-   **opinionated**: if true, the CLI will create the resources using the opinionated folder structure
+
+-   **scaffoldSchematics**: the folder convention names for each resource. Default: `useCases`, `entities`, `providers`, `middlewares`, `controllers`, `dtos`. With scaffold schematics you can customize the folder and resource names.
+
+:::caution
+Scaffold schematics are only designed for the non-opinionated template. The opinionated template has a predefined structure.
+:::
+
+## Recommendations
+
+Try to use as many different forms of creating resources as possible. This will help you to understand how the CLI works and how to use it in your favor. It also helps us improve the CLI to make it more robust.
+
+---
+
+## Support the Project
+
+ExpressoTS is an MIT-licensed open source project. It's an independent project with ongoing development made possible thanks to your support. If you'd like to help, please consider:
+
+-   Become a **[sponsor on GitHub](https://github.com/sponsors/expressots)**
+-   Follow the **[organization](https://github.com/expressots)** on GitHub and Star ⭐ the project
+-   Subscribe to the Twitch channel: **[Richard Zampieri](https://www.twitch.tv/richardzampieri)**
+-   Join our **[Discord](https://discord.com/invite/PyPJfGK)**
+-   Contribute submitting **[issues and pull requests](https://github.com/expressots/expressots/issues/new/choose)**
+-   Share the project with your friends and colleagues
+
+```
+
+```