https://github.com/aligent/serverless-aws-nodejs-service-template
AWS Template for creating microservices
https://github.com/aligent/serverless-aws-nodejs-service-template
serverless
Last synced: 12 months ago
JSON representation
AWS Template for creating microservices
- Host: GitHub
- URL: https://github.com/aligent/serverless-aws-nodejs-service-template
- Owner: aligent
- License: mit
- Created: 2020-08-18T05:05:17.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-25T00:33:31.000Z (about 1 year ago)
- Last Synced: 2025-04-02T23:46:09.895Z (12 months ago)
- Topics: serverless
- Language: TypeScript
- Size: 5.97 MB
- Stars: 8
- Watchers: 16
- Forks: 4
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Aligent AWS microservices template using Typescript and Serverless Framework
A template for developing a suite of AWS microservices using Typescript and [Serverless Framework](https://www.serverless.com/framework/docs).
The monorepo workspace is managed using [Nx.](https://nx.dev)
## Development
### Setup
1. Update application name in `package.json`. It's recommend to have the name in the format of: `@-int/integrations`. Eg: `@aligent-int/integrations`
2. Update brand name in `nx.json`. The naming convention for this is: `-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:
```bash
npx nx g service
# The command above is equivalent to 'npx nx g service general'
```
- To generate a `notification` service, use the command:
```bash
npx nx g service 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 : -- --` or `npx nx -- --`
- To deploy a service to AWS:
`npx nx deploy -- -s --aws-profile --verbose`
- To remove a service from AWS:
`npx nx run :remove -- -s --aws-profile --verbose`
### Working with libraries
Libraries are generated by `@nx/js` plugin. For more information, check out their [document](https://nx.dev/packages/js).
#### Generate a shared library
`npx nx g library `
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
```json
"check-types": {
"executor": "nx:run-commands",
"options": {
"cwd": "{projectRoot}",
"color": true,
"command": "tsc --noEmit --pretty"
},
}
```
### Generate an API Client
`npx nx g client `
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](./tools/openapi-plugin/README.md)
### General Nx. commands
Below are some example of general Nx. commands. For more information, check out their [document](https://nx.dev/packages/nx/documents).
- Remove a service or library:
`npx nx g rm `
- To run executors (`lint`, `test`, `format`, etc..) for all the projects:
`npx nx run-many -t `
- To run executors for only affected projects:
`npx nx affected -t `
## Notes:
- The `tsconfig.base.json` file extends [@aligent/ts-code-standard](https://bitbucket.org/aligent/ts-code-standards/src/main) 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](https://eslint.org/blog/2022/08/new-config-system-part-2/). If you're using [VSCode's Eslint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint), 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.
```json
"@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:
```json
"@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](https://www.npmjs.com/package/@nx/esbuild?activeTab=code) 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](https://bitbucket.org/aligent/ts-code-standards/src/main/package.json)
- [eslint-plugin-import](https://www.npmjs.com/package/eslint-plugin-import?activeTab=code)
- `@nx/vite` lists `vite` and `vitest` as peerDependencies. Double check the required version of `vite` and `vitest` in `package.json` of this [package](https://www.npmjs.com/package/@nx/vite?activeTab=code) before upgrading.
- `vitest`, `@vitest/coverage-v8` and `@vitest/ui` should be at the same version.
## Under development
- [-] Deployment pipeline -> nodeJS container + pnpm
- [x] Typescript compilation to check types (`tsc --noEmit`)
- [x] 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](https://nx.dev/extending-nx/recipes/create-preset)
- [x] Pre-commit hooks
- [x] Add error notification service
- [ ] Add step function metric configuration