@ensono-stacks/workspace

The @ensono-stacks/workspace plugin contains generators to manage the Nx workspace itself. These will often be useful in any workspace, regardless of the specific apps or libraries it contains.

Using a standard setup for workspaces ensures consistency across projects and allows developers to easily onboard onto new projects.

caution

This plugin will automatically be installed and configured if creating a stacks workspace with the Stacks CLI or @ensono-stacks/create-stacks-workspace

Setting up @ensono-stacks/workspace

Install the @ensono-stacks/workspace with the following command:

npm

npm install --save-dev @ensono-stacks/workspace@latest

yarn

yarn add --dev @ensono-stacks/workspace@latest

@ensono-stacks/workspace depends on the @ensono-stacks/core plugin.

Executors and Generators

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

nx list @ensono-stacks/workspace

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

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

Generators

@ensono-stacks/workspace:init

Set up libraries to manage code & commit quality

Set up libraries to manage code & commit quality, keeping projects consistent and will generally be useful in any workspace.

Allows you to choose your recommended 3rd party provider options.

Prerequisites

To scaffold your workspace with infrastructure there is a dependency on the stacks field within nx.json. If you have already run the Stacks CLI these fields will be automatically populated. Alternatively, if you created your workspace with create-stacks-workspace, these fields will have been populated if you passed in the relevant CLI arguments. If you are Stackifying an existing Nx workspace, this must be added manually - an example stacks field can be seen here:

{
  "stacks": {
    "business": {
      "company": "Ensono",
      "domain": "stacks",
      "component": "nx"
    },
    "domain": {
      "internal": "test.com",
      "external": "test.dev"
    },
    "cloud": {
      "platform": "azure",
      "region": "euw"
    },
    "pipeline": "azdo",
    "terraform": {
      "group": "terraform-group",
      "storage": "terraform-storage",
      "container": "terraform-container"
    },
    "vcs": {
      "type": "github",
      "url": "remote.git"
    }
  }
}

Please see the Stacks CLI documentation for information on each of these values.

Usage

Initialise your NX workspace with stacks with the following command:

nx g @ensono-stacks/workspace:init

Command line arguments

Interactive options can instead be passed via the command line:

Option	Description	Type	Accepted Values	Default
--husky	Install & configure husky	boolean	[true, false]	true
--commitizen	Install & configure commitizen	boolean	[true, false]	true
--eslint	Install & configure eslint	boolean	[true, false]	true
--pipelineRunner	Which pipeline runner to use	enum	[taskctl, none]	taskctl

Generator Output

Files updated: package.json

Files created:

├── workspace root
│   ├── .husky
│   ├── ├── commit-msg
│   ├── ├── pre-commit
│   ├── ├── prepare-commit-msg
│   ├── .eslintrc.json
│   ├── commitlint.config.js
│   ├── tsconfig.base.json

If --pipelineRunner=taskctl is passed, the generator will also create a build directory:

├── workspace root
│   ├── build
│   ├── ├── azDevOps
│   ├── ├── ├── azuredevops-runner.yaml - Azure Devops pipeline definition. Consumes `stages` and `vars` files in this directory
│   ├── ├── ├── azuredevops-stages.yaml - Azure Devops pipeline stages
│   ├── ├── ├── azuredevops-vars.yaml - Azure Devops variable definitions required by the pipeline
│   ├── ├── taskctl
│   ├── ├── ├── contexts.yaml - Context definitions for taskctl
│   ├── ├── ├── tasks.yaml - Task definitions for taskctl to be consumed by the pipeline

This sets up a CI/CD pipeline to provide a smooth collaborative workflow.

Currently supported pipeline tools are Azure Devops and taskctl.

caution

The build files will only be generated if required project values have been collected from the Stacks CLI or through the @ensono-stacks/create-stacks-workspace plugin.

Commit management

Keeping commits well-structured and clear is key to enabling collaboration on a project. This generator initialises three tools to empower consistent commits:

• Commitizen - Interactive tool that helps to build constructive messages on commit. The generator adds commitizen config to the package.json:

Commitizen config

"config": {
    "commitizen": {
        "path": "@commitlint/cz-commit-lint"
    }
  }

• Commitlint - Standardised commit message format to make reading commit history easy. The generator installs Commitlint and uses it for commitizen config.
• Husky - Git hook management tool. The generator adds a prepare script to ensure husky is always installed:

Husky install script

"scripts": {
    "prepare": "husky install"
  },

It also adds commitizen to the git prepare-commit-msg script, and Commitlint to the commit-msg. This means that you can simply run git commit and get the benefits of both tools.

Code quality management

Stacks projects use ESLint and Typescript to help maintain code quality. Using the same config in every Stacks project ensures consistency and allows developers to more easily onboard onto new projects.

This generator creates config files for both Typescript and ESLint and installs the relevant dependencies.