# Tutorial: build Node.js microservices

Source: https://imqueue.org/tutorial/
Published: 2026-07-19
Updated: 2026-08-01
Author: @imqueue maintainers (https://github.com/imqueue)

A step-by-step guide to building back-end services for a car-washing web application with @imqueue — for those who prefer to learn by example.

## A car-wash booking app

In this tutorial we build the back-end for a car-wash booking application, one
service at a time, covering the fundamentals of the @imqueue framework along the
way.

Here is what the finished application looks like to its users:

<div class="shots">
  <img src="/images/tutorial/register.png" alt="Register screen">
  <img src="/images/tutorial/login.png" alt="Login screen">
  <img src="/images/tutorial/profile-details.png" alt="Profile details screen">
  <img src="/images/tutorial/profile-garage.png" alt="Profile garage screen">
  <img src="/images/tutorial/time-table.png" alt="Time table screen">
</div>

The complete source code for the tutorial application is available on
[GitHub](https://github.com/imqueue-sandbox).

## Architecture

Let's say we're building the web application on a React/Relay/GraphQL front-end,
served by a GraphQL API endpoint that sits in front of a set of @imqueue-based
back-end services.

While a front-end team builds the user interface, we focus on the back-end. We
split it into small, decoupled services that can be developed in parallel by
small teams:

- **User service** — manages user data. Stack: Node.js/TypeScript, @imqueue over
  Redis, MongoDB.
- **Auth service** — handles authentication. Stack: Node.js/TypeScript, @imqueue
  over Redis, JSON Web Tokens.
- **Car service** — serves car data. Stack: Node.js/TypeScript, @imqueue over
  Redis, a static data source cached in a custom in-memory store.
- **Time-Table service** — manages the washing schedule: reservations and the
  station's working-hours options. Stack: Node.js/TypeScript, @imqueue over
  Redis, PostgreSQL through @imqueue/pg-sequelize.
- **API service** — a GraphQL endpoint that orchestrates access to the services
  above. Stack: Node.js/TypeScript, @imqueue over Redis, graphql, graphql-relay,
  express, graphql-yoga.

> **NOTE.** The GraphQL choice is just that — a choice. In two bonus chapters
> at the end of the tutorial we put a [REST/OpenAPI gateway](https://imqueue.org/tutorial/rest-api/)
> in front of the very same fleet and give it
> [a front-end of its own](https://imqueue.org/tutorial/rest-web-app/) — one that speaks REST
> natively rather than imitating Relay — leaving every back-end service
> untouched.

The high-level architecture looks like this:

## Setting up the toolchain

The @imqueue command-line tool can wire its scaffolding into third-party
services — a git host (GitHub, GitLab or Bitbucket), a container registry (Docker
Hub, Google Artifact Registry, AWS ECR or Azure ACR) and a CI provider (GitHub
Actions, CircleCI or Travis). When you create a service with the tool, you can
get a ready-made repository, continuous integration and one-command Docker image
builds out of the box. So the first step is to install and configure
`@imqueue/cli`.

### Prepare the development environment

You'll need [Node.js](https://nodejs.org/) 22.12 or newer, ideally installed via
[NVM](https://github.com/nvm-sh/nvm#installing-and-updating). You'll also need
Redis, MongoDB and PostgreSQL — install them however you prefer, whether via
Docker images ([Mongo](https://hub.docker.com/_/mongo/),
[Redis](https://hub.docker.com/_/redis/),
[PostgreSQL](https://hub.docker.com/_/postgres/)) or directly on your system.

### Install @imqueue/cli

These git-host, container-registry and CI integrations are entirely optional.
Without them, the tool simply creates local folders and files; you choose which
to enable when you configure the tool.

If you do want the integrations, prepare your git-host and registry namespaces
(a personal account or an organisation) and create a personal access token for
your git host — GitHub, for example — granting @imqueue/cli permission to create
and write to repositories in that namespace.

Then install the tool:

~~~bash
npm i -g @imqueue/cli
~~~

Then run the interactive configuration wizard once to finish setting up
`@imqueue/cli`:

~~~bash
imq config init
~~~

It walks you through your git host, CI provider, container registry and default
packages, and stores the answers globally.

For the full setup details — requirements, upgrading and shell completions — see
the [Installation](https://imqueue.org/cli/installation/) & [Configuration](https://imqueue.org/cli/configuration/)
chapters of the CLI User Guide.

With that in place, we're ready to create our first service.