Skip to main content

@ensono-stacks/rest-client

This plugin provides the ability to quickly get up and running with http clients and endpoints. One can generate the basic HTTP methods required to start building out a project.

What benefits does it give you?

  • Helps track versioning and easily bump versions of endpoints using one of the plugins.
  • Ensure solid foundational syntax accuracy
  • Promote best practice in generated code

Setting up @ensono-stacks/rest-client

Install the @ensono-stacks/rest-client with the following command:

npm install --save-dev @ensono-stacks/rest-client@latest

Executors and Generators

To see a list of the plugin capabilities run the following command:

nx list @ensono-stacks/rest-client

View additional information about a plugin capability through the following command:

nx g @ensono-stacks/rest-client:[generator-executor-name] --help

Generators

@ensono-stacks/rest-client:http-client

Installs and creates a new instance of Axios, ready to generate a client with custom configuration

This plugin installs Axios and configures a new instance of the provider ready to be customised and consumed via your project.

Usage

nx g @ensono-stacks/rest-client:http-client

Command line arguments

The following command line arguments are available:

OptionDescriptionTypeAccepted ValuesDefaultRequired
--nameLibrary namestringtrue
--directorySubdirectory inside libs/ where the generated library is placedstring
--importPathWhat import path would you like to use for the librarystring
--tagsAdd tags to the library (used for linting)string
--skipFormatSkip formatting filesbooleanfalse

Generator Output

The http-client will create a new library within your libs folder for the axios http client:

Generated files

├── http-client
│ ├── src
│ │ ├── index.ts
│ │ ├── index.test.ts
│ ├── README.md
│ ├── tsconfig.json
│ ├── tsconfig.lib.json
│ ├── project.json
│ ├── .eslintrc.json
│ ├── jest.config.ts
└── └── tsconfig.spec.json

Additionally, the package.json will be updated with the axios dependency.

Modified files
├── root
│ ├── tsconfig.base.json
└── └──package.json

In order to import the http-client into your application a new entry for the client is added to the tsconfig.base.json "paths"

"paths": {
"@<workspace-name>/http-client": [
"libs/http-client/src/index.ts"
]
}

@ensono-stacks/rest-client:client-endpoint

Add Axios HTTP methods to your existing application

This plugin gives you choice of selecting from the HTTP methods using Axios as the provider for setting up the initial building blocks of your new endpoint.

Prerequisites

This generator requires a http-client project to be available.

Usage

nx g @ensono-stacks/rest-client:client-endpoint

Command line arguments

The following command line arguments are available:

OptionDescriptionTypeAccepted ValuesDefaultRequired
--nameLibrary namestringtrue
--httpClientThe import path of the previously generated http-client used in the applicationstringtrue
--envVarThe name of the API url environment variablestringAPI_URLtrue
--endpointVersionThe version of the endpointnumber1true
--methodsList of HTTP methods to be generated. Choose from get, post, patch, put, delete, head, optionsarrayget, post, patch, put, delete, head, optionstrue
--directorySubdirectory inside libs/ where the generated library placedstring
--tagsAdd tags to the project (used for linting)string

Generator Output

The client-endpoint will create a new library within your libs folder, using your answer to the 'What is the import path of your previously generated http-client library?' to import the previously created http-client into your client endpoint:

Example of files being generated

└── libs
│ ├── client-endpoint
│ │ ├── V1
│ │ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── index.ts
│ │ │ │ ├── index.test.ts
│ │ │ │ ├── index.types.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsconfig.lib.json
│ │ │ ├── project.json
│ │ │ ├── .eslintrc.json
│ │ │ ├── jest.config.ts
└───└───└───└── tsconfig.spec.json
└── .env.local

Be sure to add the API_URL as an environment variable to the created .env.local file for local development

In order to import the client-endpoint into your application a new entry for the client is added to the tsconfig.base.json "paths"

"paths": {
"@<workspace-name>/client-endpoint/v1": [
"libs/client-endpoint/v1/src/index.ts"
]
}

@ensono-stacks/rest-client:bump-version

Details

Creates new version(s) for an existing client endpoint This plugin reads any existing endpoints and creates a new directory for the specified new version with the files contained within the previous version.

Prerequisites

This generator requires a client-endpoint project to be available.

Usage

nx g @ensono-stacks/rest-client:bump-version

Command line arguments

The following command line arguments are available:

OptionDescriptionTypeAccepted ValuesDefaultRequired
--nameThe endpoint name you want to bumpstringtrue
--directorySubdirectory inside libs/ where the generated endpoint is placedstring
--endpointVersionThe version you want to bump your endpoint. Omitting this value will bump latest version + 1.number

Generator Output

The generator will take a copy of your latest endpoint and bump it to the next version (unless overridden through the --endpointVersion argument)

V1 endpoint

├── client-endpoint
│ ├── v1
│ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── index.ts
│ │ │ │ ├── index.test.ts
│ │ │ │ ├── index.types.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsconfig.lib.json
│ │ │ ├── project.json
│ │ │ ├── .eslintrc.json
│ │ │ ├── jest.config.ts
└───└───└───└── tsconfig.spec.json

Once the bump-version generator has been used, your library structure will look similar to the following:

Bumped endpoint structure

├── client-endpoint
│ ├── v1
│ │ ├── [...]
│ ├── v2
│ │ ├── README.md
│ │ │ ├── src
│ │ │ │ ├── index.ts
│ │ │ │ ├── index.test.ts
│ │ │ │ ├── index.types.ts
│ │ │ ├── tsconfig.json
│ │ │ ├── tsconfig.lib.json
│ │ │ ├── project.json
│ │ │ ├── .eslintrc.json
│ │ │ ├── jest.config.ts
└───└───└───└── tsconfig.spec.json

In order to import the bumped client-endpoint into your application a new entry for the client is added to the tsconfig.base.json "paths"

"paths": {
"@<workspace-name>/client-endpoint/v2": [
"libs/client-endpoint/v2/src/index.ts"
]
}

@ensono-stacks/rest-client:openapi-client

Generates boilerplate configuration of types, client, stubs and validation using from your openapi schema using Orval.

Utilising Orval, this plugin generates various files based off your openapi schema to enable quick acceleration from definition to implementation.

Usage

nx g @ensono-stacks/rest-client:openapi-client

Command line arguments

The following command line arguments are available:

OptionDescriptionTypeAccepted ValuesDefaultRequired
--nameLibrary namestringtrue
--schemaThe relative path to your openapi schemastringtrue
--zodValidation for your openapi schemabooleanfalsetrue
--tagsAdd tags to the library (used for linting)string
--directorySubdirectory inside libs/ where the generated library is placedstring

Generator Output

The openapi-client will create a new library within your libs folder for the various files generated:

Generated files

├── openapi-client
│ ├── src
│ │ ├── model
| │ │ ├── ...
│ │ ├── <libraryName>.msw.ts
│ │ ├── <libraryName>.ts
│ │ ├── <libraryName>.zod.ts
│ │ ├── index.ts
│ ├── .eslintrc.json
│ ├── jest.config.ts
│ ├── orval.config.js
│ ├── orval.zod.config.js
│ ├── openapi-schema.(json/yaml)
│ ├── project.json
│ ├── README.md
│ ├── tsconfig.json
│ ├── tsconfig.lib.json
└── └── tsconfig.spec.json

Key things to highlight about the generated files are as follows:

  • The generator first creates the orval config files orval.config.js orval.zod.config.js which are used to set the options for orval to be executed against. These options determine what files to generate and how.
  • Once the config files are generated, we execute the Orval generator. The 3 <libraryName>... files are created along wih the model folder with its contents. This generation consists of the end result following the openapi definition being converted into code implementation; types, client, stubs and validation.

The relevant dependencies (orval, msw, @faker-js/faker, zod) are also installed in order for the generation to take place and to resolve the relevant syntax/prettier errors.