Aligent AWS Microservices template

A template for developing a suite of AWS microservices using AWS CDK, Typescript, and Nx.

Setup

1. Update application name in package.json.

   It's recommend to have the name in the format of: @<brand-name>-int/integrations

   Example: @aligent-int/integrations

2. Install the template and validate it's passing code standards

   nvm use && yarn install && yarn audit

3. (Optional) Commit the initial state of the template. This ensures subsequent changes are easy to review, rather than getting lost in the template boilerplate

   git add . && git commit -m 'Serverless application template'

4. (Optional) Bootstrap SSM parameters:

   If there are existing parameters in SSM Parameter store, import them

   yarn nx run core:parameters

   Alternatively, copy the parameters/.env.example.csv file to parameters/.env.csv in the application project, modify the contents, and push the parameters to AWS

   yarn nx run core:parameters:import

   The default SSM path and file path can be changed in an application's parameters target or via CLI arguments

5. (Optional) Change default base branch If your pull requests will target a branch other than main, change the value of defaultBranch in nx.json to the name of the branch that Nx should compare to when running tasks with affected

   {
     "defaultBase": "origin/staging"
   }

Services

Services are the core components deployed to AWS by the application

Add a service | Test app | Deploy app | Clean up app | Remove a service | Mock Endpoints

⭐ Adding a new service

Services are generated by our @tools/cdk-service-plugin. It supports generating CDK-based services using predefined templates and executors as described below.

yarn nx g service
# You will be prompted to:
# 1. Enter the service name
# 2. Select the service type (general or notification)

# Alternatively, provide the name and type as arguments
yarn nx g service test-app --type=general
# Will create a project called @services/test-app in the services/ folder

Import and instantiate the service in ApplicationStage inside applications/core/bin/main.ts:

import { YourServiceStack } from '@services/your-service-name';

// Application setup here...

class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    Tags.of(this).add('STAGE', id);

    // Instantiate service stacks here as required..
    new YourServiceStack(scope, 'your-service-name', {
      ...props,
      description: 'Your service description',
    });
  }
}

Note: You will need to run yarn install and yarn nx sync before other projects will detect the new service

---

🧪 Testing the application

After adding a new service, test the application:

yarn lint        # Lint affected projects
yarn test        # Run tests for affected projects
yarn typecheck   # Type check affected projects

By default, Nx will only test code impacted by recent changes to save time. Post-fixing with :all will test the whole repository, not just recently affected parts

yarn test:all

The yarn audit command is useful after making significant changes to ensure the entire repository is passing code checks

yarn audit

---

🚀 Playground deploy of the application

Deploy the dev stage of your application to your playground AWS Profile:

yarn pg:deploy
# You may be prompted to confirm deployment of changes

If you just want to check the CDK compilation process without deploying, use yarn pg:synth.

If you need more control, arbitrary CDK commands can be run using the core application project

yarn nx run core:cdk list prd/**

---

🗑️ Clean up the application from playground

During normal development CDK will remove resources that are no longer used by your application.

If necessary, the entire application can be removed from the account associated with your playground AWS profile:

yarn pg:destroy
# You will be prompted to confirm deletion of the stacks

---

❌ Removing a service

Always remove services using the Nx generator

yarn nx g remove <service-name>

You may need to remove imports of the service from the application first. You may need to remove references to the service in nx.json afterwards.

🧪 Testing with Mock Services

The application may include mock services for testing integrations without external dependencies

To switch between mock and real dependencies, change the value of the relevant url SSM Parameter.

Libraries

Libraries are located in the libs folder.

General libraries are generated by the @nx/js plugin. For more information, check out their document

API client libraries should be generated by the @aligent/openapi-plugin

General library | API Client | Remove a service

⭐ Adding a new library

# Generates a non-buildable library with eslint, vitest
# Lives in a subfolder of 'libs'
# Import path defaults to @<brand-name>/<library-name>
yarn nx g library libs/<library-name>  --importPath=libs/<library-name>

---

🔌 Adding a new API client

yarn nx g client --name=<client-name> --schemaPath=<path-to-openapi-spec>

❌ Removing A Library

Always remove libraries using the Nx generator

yarn nx g remove <library-name>

You may need to remove imports of the library from the codebase first

Working with Nx

General commands

Below are some example of general Nx. commands. For more information, check out their document.

• Remove a service or library:

  yarn nx g rm <project-name>

• To run executors (lint, test, etc..) for all the projects:

  yarn nx run-many -t <list-of-executors-separated-by-space-or-comma>

• To run executors for only affected projects:

  yarn nx affected -t <list-of-executors-separated-by-space-or-comma>

Troubleshooting

Reset all Nx project dependencies and caching: yarn nx reset

Ensure typescript project references are correct: yarn nx sync

Run test, lint, typecheck on all code without caching: yarn lint:all --skip-nx-cache etc.

Notes

• This monorepo uses the new Nx Typescript Project References setup. This currently doesn't allow extending tsconfigs at all, so we are not extending @aligent/ts-code-standard/tsconfigs-base
• Following @aligent/ts-code-standard, we switched to the new Eslint's FlatConfig. If you're using VSCode's Eslint extension, turn on the eslint.useFlatConfig setting.

Further documentation

Architecture | Maintenance | Future Development