diff --git a/docs/cli/_category_.json b/docs/cli/_category_.json index ac3132a1..55995471 100644 --- a/docs/cli/_category_.json +++ b/docs/cli/_category_.json @@ -1,8 +1,8 @@ { - "label": "CLI", - "position": 4, - "link": { - "type": "generated-index", - "description": "Expresso TS CLI Tool." - } + "label": "CLI", + "position": 3, + "link": { + "type": "generated-index", + "description": "Expresso TS CLI Tool Overview." + } } diff --git a/docs/cli/generate.md b/docs/cli/generate.md deleted file mode 100644 index 2aaae698..00000000 --- a/docs/cli/generate.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Generate - -In order to provide a better developer experience, the ExpressoTS CLI provides a set of commands to help you scaffold the application resources such as use cases, controllers, DTO's, providers and services. - -This command allows developers to stay ahead of the curve by generating the boilerplate code for the application, so they can focus on the business logic. - -## Command Syntax - -The generate command can be executed as follows: - -```bash -expressots generate [options] -``` - -Or in its short form: - -```bash -expressots g [options] -``` - -### Command Structure - -We provide two different structures to scaffold the resources: - -- **[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` - This will create this folder structure: `/user/create` and the file: `create.[resource].ts` - - If you add `/` at the end of the structure, the CLI will create the resource inside of the folder. Example: `expressots generate service user/create/` - Structure: `user/create/` and the file: `create.[resource].ts` - -### Resource Root Folder - -- The root folder for all resources is the `src` folder. This can be changed in the `expressots.config.ts` file. -- In the opinionated mode, the root folder is the `src` folder and the resources scaffolded with `service, usecase, dto, controller` are created inside of the `useCases` folder. -- Entities are created inside of the `entities` folder, and providers inside of the `providers` folder. - -## Resource Types - -Current available resources: - -| Long form | short | Command | Expected result | -| ---------- | ----- | -------------------------- | ---------------------------------------------------------------------------------------- | -| usecase | u | expressots g u user/find | Use case to be created in the folder `useCases` with this folder structure: user/find | -| controller | c | expressots g c user/find | Controller to be created in the folder `useCases` inside of user/find | -| dto | d | expressots g d user/find | DTO to be created in the folder `useCases` inside of user/find | -| provider | p | expressots g p email/email | Provider to be created in the folder `providers` inside of user/find | -| service | s | expressots g s user/find | Service creates usecase, controller and DTO and add them in the desired folder user/find | -| entity | e | expressots g e user | Entity to be created in the folder `entities` with this folder structure: user | -| middleware | mi | expressots g mi auth | Middleware to be created in the folder `middlewares` with this folder structure: auth | -| module | mo | expressots g mo user | Module to be created in the folder where `controllers` and `usecases` are located | - -All resources can be created using the structure `folder/subfolder/resource`. - -## 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: - -```bash -expressots g s user-create -``` - -:::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. -::: - -Read more about the [ExpressoTS Config File](/docs/overview/expressots-config.md). - ---- - -## 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 diff --git a/docs/cli/generate.mdx b/docs/cli/generate.mdx new file mode 100644 index 00000000..96b41cbf --- /dev/null +++ b/docs/cli/generate.mdx @@ -0,0 +1,166 @@ +--- +sidebar_position: 1 +title: Generate +description: Scaffold ExpressoTS resources using the CLI. +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Generate + +In order to provide a better developer experience, the ExpressoTS CLI provides a set of commands to help you scaffold the application resources such as use cases, controllers, DTO's, providers and services. + +This command allows developers to stay ahead of the curve by generating the boilerplate code for the application, so they can focus on the business logic. + +## Command syntax + +One big advantage of the ExpressoTS CLI is the ability to scaffold resources using two different structures: the shorthand and +the folder/subfolder/resource. The shorthand operation is a more concise way to scaffold resources (recommended to be used in the opinionated template), while +the folder/subfolder/resource structure is more flexible and can be used in both templates. + +The generate command can be executed as follows: + +```bash +expressots generate [options] +``` + +Or in its short form: + +```bash +expressots g [options] +``` + + + +```bash title="Full form" +expressots generate service user/create +``` + +```bash title="Short form" +expressots g s user/create +``` + + + + +```bash title="Full form" +expressots generate service user-create +``` + +```bash title="Short form" +expressots g s user-create +``` + +```bash title="Passing http parameter as option" +expressots g s user-create -m post +``` + + + + + +## Command structure + +We provide two different structures to scaffold the resources, the **shorthand** and the **folder/subfolder/resource**. +These scaffold strategies work differently 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. + +#### Using single name + +```bash +expressots g c user +``` + +```bash title="Output" +src +└── user.controller.ts +``` + +#### Using the shorthand operation + +```bash +expressots g c user-create +``` + +```bash title="Output" +src +└── user + └── create + └── user-create.controller.ts +``` + +#### Using the folder/subfolder/resource structure + +```bash +expressots g c user/create +``` + +```bash title="Output" +src +└── user + └── create.controller.ts +``` + +If you add `/` at the end of the structure, the CLI will create the resource inside of the folder. Example: `expressots g c user/create/` + +```bash title="Output" +src +└── user + └── create + └── create.controller.ts +``` + +:::info +Opinionated templates come with predefined folder structures for each resource type, ensuring that resources are always created in the following designated folders: + + - useCases + - entities + - providers + +::: + +The root folder for all resources is the `src` folder. This can be changed in the `expressots.config.ts` file. + +## Resource types + +Resources available to be scaffolded are: + +| Long form | short | Command | Expected result | +| ---------- | ----- | -------------------------- | ---------------------------------------------------------------------------------------- | +| usecase | u | expressots g u user/find | Use case to be created in the folder `useCases` with this folder structure: user/find | +| controller | c | expressots g c user/find | Controller to be created in the folder `useCases` inside of user/find | +| dto | d | expressots g d user/find | DTO to be created in the folder `useCases` inside of user/find | +| provider | p | expressots g p email/email | Provider to be created in the folder `providers` inside of user/find | +| service | s | expressots g s user/find | Service creates usecase, controller and DTO and add them in the desired folder user/find | +| entity | e | expressots g e user | Entity to be created in the folder `entities` with this folder structure: user | +| middleware | mi | expressots g mi auth | Middleware to be created in the folder `middlewares` with this folder structure: auth | +| module | mo | expressots g mo user | Module to be created in the folder where `controllers` and `usecases` are located | + +For services, you can take advantage of creating the use case, controller and DTO at once. + +```bash +expressots g s user-create +``` + +```bash title="Output for the non opinionated template" +src +└── user + └── create + ├── user-create.controller.ts + ├── user-create.dto.ts + ├── user-create.usecase.ts + └── user-create.usecase.ts +``` + +:::info +The `expressots.config.ts` file, located in the project root folder, defines where all resources will be created and specifies the naming conventions for each type of resource. +::: + +Read more about the [ExpressoTS Config File](../features/expressots-config.mdx). + +--- + +## Support us ❤️ + +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 read our **[support guide](../support-us.mdx)**. diff --git a/docs/cli/overview.md b/docs/cli/overview.mdx similarity index 51% rename from docs/cli/overview.md rename to docs/cli/overview.mdx index b6e875b4..04a95b28 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.mdx @@ -1,14 +1,17 @@ --- -sidebar_position: 1 +sidebar_position: 0 +title: Overview +description: ExpressoTS CLI overview. --- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + # Overview -ExpressoTS CLI is a command-line interface tool that helps you to `create` ExpressoTS projects and `scaffold` ExpressoTS resources. +The CLI (command-line interface) tool helps you to create ExpressoTS projects and scaffold ExpressoTS resources. -:::info -We use the `npm` package manager in this tutorial for simplicity. However, you can use `yarn` or `pnpm` as well. -::: +We use the `npm` in this tutorial for simplicity. However, you can use your preferred package manager (`yarn` or `pnpm`) by replacing `npm` with the appropriate command. ## Installation @@ -18,26 +21,29 @@ First install the CLI globally using the command below: npm install -g @expressots/cli ``` -## Commands Available +## Commands available + +The CLI provides the following commands: -| 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 | +| Name | Alias | Description | +| ----------- | ------- | ----------------------------------------------------- | +| new project | new | Generate a new project | +| info | i | Provides project information | +| resources | r | Displays CLI commands and resources | +| scripts | scripts | Run scripts list or a specific script | +| help | help | 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 +## Usage examples The CLI has the following syntax: @@ -45,7 +51,7 @@ The CLI has the following syntax: expressots [options] ``` -### Help +## Help command Verify the available commands and options: @@ -53,7 +59,7 @@ Verify the available commands and options: expressots help ``` -### Info +## Info command Providers information about your Operational System, Project and CLI version: @@ -61,7 +67,7 @@ Providers information about your Operational System, Project and CLI version: expressots info ``` -### Resources list +## Resources list List all available resources to scaffold: @@ -69,12 +75,12 @@ List all available resources to scaffold: expressots resources (Alias: r) ``` -### 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: -```bash +```bash title="Create project command options" expressots new -p -t