$ open source · GPL-3.0 — need a commercial license? imqueue.com →
// GET STARTED

Getting Started

The shortest path from an empty terminal to a running @imqueue service and a generated client. For a deeper, worked example see the Tutorial; the full technical reference lives in the API docs.

Prerequisites

Before you begin, make sure the following are installed and available on your system:

  • Node.js 22.12 or newer — we recommend installing it through NVM.
  • Redis — version 3.2 or newer. @imqueue uses Redis as its message-queue transport.
  • Git — the command-line client.

1. Install the CLI

Install the @imqueue command-line tool globally. It scaffolds services and generates clients for you, so you write features instead of boilerplate:

npm i -g @imqueue/cli

On first run the installer offers to collect some initial configuration. You can fill it in now, or press Ctrl+C to skip and configure it later (or not at all — it is optional).

2. Configure (optional)

@imqueue/cli works without any configuration. Defining a global configuration once is only worthwhile on larger projects with many services, where it saves you from repeating the same options on every command.

To create or re-create the configuration at any time, run:

imq config init

For the full setup details — requirements, upgrading and shell completions — see the Installation & Configuration chapters of the CLI User Guide.

3. Enable shell completions

Turning on completions for the imq command makes the CLI far more pleasant to use. Run:

imq completions on

and follow the prompts. bash and zsh are supported.

4. Everyday usage

The CLI exists to remove the boilerplate of building @imqueue-based back-end services. It does two main jobs for you:

  1. Scaffold services from ready-made templates.
  2. Generate client code for calling those services.

4.1 Create a service

Scaffold a new service into a fresh directory:

mkdir user-service
cd user-service
imq service create

Then open src/UserService.ts and implement the methods your service needs to expose.

4.2 Run the service

Make sure a Redis server is running on the default port, then start the service in watch mode:

npm run dev

4.3 Generate a client

Every @imqueue service is self-describing, so a fully typed client can be generated directly from a running service. With the service running, generate its client:

mkdir clients
cd clients
imq client generate UserService

You can now import that client and call the service's methods remotely, with full type-checking and IDE auto-completion.

That's it — you've built and called your first @imqueue service.

Ready for more? Work through the Tutorial for a complete example application, or dive into the API reference.