Aligent AWS microservices template using Typescript and Serverless Framework

A template for developing a suite of AWS microservices using Typescript and Serverless Framework.

The monorepo workspace is managed using Nx.

Development

Setup

1. Update application name in package.json. It's recommend to have the name in the format of: @<brand-name>-int/integrations. Eg: @aligent-int/integrations

2. Update brand name in nx.json. The naming convention for this is: <brand-name>-int. Just be mindful about the length of service name. Eg: alg-int

3. Install dependencies: yarn install

Working with services

Services are generated by our @aligent/serverless-plugin. It supports generating services based on our predefined template and some executors as described below.

Service generator (for generating new service)

• To generate a service, use the command:

  npx nx g service <service-name>
  # The command above is equivalent to 'npx nx g service <service-name> general'

• To generate a notification service, use the command:

  npx nx g service <service-name> notification

Service executors

Our service executors are lint, test, typecheck, build, deploy and remove. Executor can be executed using the command in the format:

npx nx run <service-name>:<executor> -- --<options> or npx nx <executor> <service-name> -- --<options>

• To deploy a service to AWS:

  npx nx deploy <service-name> -- -s <stage-name> --aws-profile <profile-name> --verbose

• To remove a service from AWS:

  npx nx run <service-name>:remove -- -s <stage-name> --aws-profile <profile-name> --verbose

Working with libraries

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

Generate a shared library

npx nx g library <library-name>

Shared library will need to have the check-types command added manually to ensure proper type checking. This is because the the @nx/js plugin does not add it by default.

TODO: Check if this is required

"check-types": {
    "executor": "nx:run-commands",
    "options": {
        "cwd": "{projectRoot}",
        "color": true,
        "command": "tsc --noEmit --pretty"
    },
}

Generate an API Client

npx nx g client <client-name>

Clients are generated by our @aligent/openapi-plugin. This plugin will generate typed API utilities to build an external API Client based on a local or remote OpenAPI Specification (3.0.0+) schema file (.json .yaml)

For more detailed documentation on using the plugin see the plugin README here

General Nx. commands

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

• Remove a service or library:

  npx nx g rm <project-name>

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

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

• To run executors for only affected projects:

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

Notes:

• The tsconfig.base.json file extends @aligent/ts-code-standard package. Please note that there are settings which is not shown in that file but still applied. For more information on those settings, visit https://github.com/tsconfig/bases.

• 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.

Maintenance

Upgrading NPM packages

The NPM packages in devDependencies in this repository has a complicated relationship with each other. Therefore, upgrading them should be handled with care.

• All the @nx packages must be pinned at the same version with nx package to avoid conflict.

    "@nx/devkit": "17.3.0",
    "@nx/esbuild": "17.3.0",
    "@nx/eslint": "17.3.0",
    "@nx/eslint-plugin": "17.3.0",
    "@nx/js": "17.3.0",
    "@nx/plugin": "17.3.0",
    "@nx/vite": "17.3.0",
    "@nx/workspace": "17.3.0",
    "nx": "17.3.0"

• All the packages that are in the same scope should be at the same version. For example:

    "@typescript-eslint/eslint-plugin": "^6.13.2",
    "@typescript-eslint/parser": "^6.13.2",

• @nx/esbuild lists esbuild as peerDependency. Double check the required version of esbuild in package.json of this package before upgrading.

• eslint and prettier are a peerDependencies of the following packages. Double check the required versions in package.json of these packages before upgrading.

  • @aligent/ts-code-standard
  • eslint-plugin-import

• @nx/vite lists vite and vitest as peerDependencies. Double check the required version of vite and vitest in package.json of this package before upgrading.

  • vitest, @vitest/coverage-v8 and @vitest/ui should be at the same version.

Under development

• [-] Deployment pipeline -> nodeJS container + pnpm
• Typescript compilation to check types (tsc --noEmit)
• Root client configuration (e.g. service name prefix)
• [-] Base vite configuration -> this works for service generator.
• Importing code from internal libraries
• Bespoke library generator -> use same base vite configuration if we do this.
• Develop workspace preset
• Pre-commit hooks
• Add error notification service
• Add step function metric configuration