https://github.com/jellydn/moleculer-typescript-template
This is a Moleculer-based microservices project
https://github.com/jellydn/moleculer-typescript-template
fly microservices moleculer-template moleculerjs typescript
Last synced: 6 months ago
JSON representation
This is a Moleculer-based microservices project
- Host: GitHub
- URL: https://github.com/jellydn/moleculer-typescript-template
- Owner: jellydn
- License: mit
- Created: 2022-03-22T06:13:23.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-10T09:57:00.000Z (6 months ago)
- Last Synced: 2025-04-10T10:55:00.546Z (6 months ago)
- Topics: fly, microservices, moleculer-template, moleculerjs, typescript
- Language: TypeScript
- Homepage: https://moleculer-typescript-template.fly.dev/
- Size: 4.57 MB
- Stars: 17
- Watchers: 3
- Forks: 3
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Welcome to moleculer-typescript-template 👋
[](https://twitter.com/jellydn)
> My Moleculer-based microservices project
[](https://www.youtube.com/watch?v=peb2OflRu-4)
[](https://www.youtube.com/watch?v=LwfcoOWlyOw)
[](https://www.youtube.com/watch?v=wO5MTD3Lawg)
[](https://www.youtube.com/watch?v=sTjIgGBhfMs)
## Prerequisites
- node >= 18.17.x
## Init new project
```sh
npx degit jellydn/moleculer-typescript-template [PROJECT-NAME]
```
## Features
- ⚡️ Progressive microservices framework for Node.js.
[Moleculer](https://moleculer.services/) with [Typescript](https://www.typescriptlang.org/) template
- 📦 [hygen](http://www.hygen.io/) - The scalable code generator that saves you time.
- 🦾 [pino](https://getpino.io) - super fast, all natural json logger
- 🔥 [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc/blob/v6/docs/README.md) - Generates swagger/openapi specification based on jsDoc comments and YAML files.
- ✨ [moleculer-zod-validator](https://github.com/TheAppleFreak/moleculer-zod-validator) - A validator for the Moleculer microservice framework to allow the use of [Zod](https://zod.dev/).
- 🔏 [asteasolutions/zod-to-openapi](https://github.com/asteasolutions/zod-to-openapi#defining-schemas) - A library that generates OpenAPI (Swagger) docs from Zod schemas.
- 🪄 [hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) - Turn your OpenAPI specification into a beautiful TypeScript client.
## Install
```sh
pnpm install
```
## Usage
```sh
# Copy env file
cp .env.example .env
pnpm dev
```
After starting, open the http://localhost:3000/ URL in your browser.
On the welcome page you can test the generated services via API Gateway and check the nodes & services.
```sh
pnpm cli --ns api
```
In the terminal, try the following commands:
- `nodes` - List all connected nodes.
- `actions` - List all registered service actions.
- `call greeter.hello` - Call the `greeter.hello` action.
- `call greeter.welcome --username dunghd` - Call the `greeter.welcome` action with the `username` parameter.
This project uses [hygen](http://www.hygen.io/) to generate code templates, saving you time and ensuring consistency across your codebase.
### Adding a New Service
To add a new service to your project, use the following command:
```sh
pnpm generate:service [service-name]
```
### Adding a New Action to a Service
To add a new action to an existing service, use the following command:
```sh
pnpm generate:action [action-name] --service [service-name]
```
### Generating CRUD Services
To generate a service with Create, Read, Update, and Delete (CRUD) operations, use the following command:
```sh
pnpm generate:crud [service-name]
```
## API Documentation
This template also reads your [JSDoc-annotated](https://github.com/Surnet/swagger-jsdoc/blob/v6/docs/README.md) source code and generates an OpenAPI (Swagger) specification.
Run the following command to generate the Swagger documentation:
```sh
pnpm generate:swagger
```
Open the http://localhost:3000/docs URL in your browser, you will see the Swagger UI as
## Run tests
```sh
pnpm test
```
## Deployment
This template comes with two GitHub Actions that handle automatically deploying your app to production and staging environments.
Prior to your first deployment, you'll need to do a few things:
- [Install Fly](https://fly.io/docs/getting-started/installing-flyctl/)
- Sign up and log in to Fly
```sh
fly auth signup
```
- Create two apps on Fly, one for staging and one for production:
```sh
fly create moleculer-typescript
fly create moleculer-typescript-staging
```
- Create a new [GitHub Repository](https://repo.new)
- Add a `FLY_API_TOKEN` to your GitHub repo. To do this, go to your user settings on Fly and create a new [token](https://web.fly.io/user/personal_access_tokens/new), then add it to [your repo secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) with the name `FLY_API_TOKEN`.
Now that every is set up you can commit and push your changes to your repo. Every commit to your `main` branch will trigger a deployment to your production environment, and every commit to your `dev` branch will trigger a deployment to your staging environment.
## GitHub Actions
We use GitHub Actions for continuous integration and deployment. Anything that gets into the `main` branch will be deployed to production after running tests/build/etc. Anything in the `dev` branch will be deployed to staging.
## Useful links
- Moleculer website: https://moleculer.services/
- Moleculer Documentation: https://moleculer.services/docs/0.14/
## NPM scripts
- `pnpm dev`: Start development mode (load all services locally with hot-reload & watch)
- `pnpm start`: Start production mode (set `SERVICES` env variable to load certain services)
- `pnpm cli`: Start a CLI and connect to production. Don't forget to set production namespace with `--ns` argument in script
- `pnpm ci`: Run continuous test mode with watching
- `pnpm test`: Run tests & generate coverage report
- `pnpm dc:up`: Start the stack with Docker Compose
- `pnpm dc:down`: Stop the stack with Docker Compose
## Pre-commit hooks
This template uses [Pre-commit](https://pre-commit.com/) to run checks before you commit your code. This ensures that your code is formatted correctly and passes all tests before you push it to your repository.
```sh
pre-commit install
```
To run the checks manually, use the following command:
```sh
pre-commit run --all-files
```
## Author
👤 **Dung Huynh**
- Website: https://productsway.com/
- Twitter: [@jellydn](https://twitter.com/jellydn)
- Github: [@jellydn](https://github.com/jellydn)
## Show your support
[](https://star-history.com/#jellydn/moleculer-typescript-template)
Give a ⭐️ if this project helped you!
[](https://ko-fi.com/dunghd)
[](https://paypal.me/dunghd)
[](https://www.buymeacoffee.com/dunghd)