nx-ng-starter

A modern, full-stack monorepo starter built with Nx, Angular, Node.js, and Firebase. Ship web, mobile, and desktop applications from a single repository with GraphQL, real-time database integration, and enterprise-grade tooling.

Overview

nx-ng-starter is a starter template that eliminates boilerplate configuration for modern full-stack applications. It combines the monorepo power of Nx with the reactive paradigm of Angular, a scalable Node.js backend, and Firebase for authentication, database, and deployment.

Whether you're building a web application, a mobile app with Capacitor, a desktop app with Electron, or all three — this starter provides the foundation with best practices baked in.

Key Features

• Monorepo Architecture — Manage multiple apps and libraries in one workspace using Nx
• Full-Stack JavaScript/TypeScript — Shared code between frontend and backend
• Firebase Integration — Firestore database, Realtime Database, Authentication, Cloud Functions, and Hosting
• GraphQL Support — Schema-driven API development with type safety
• Multi-Platform — Web, Android (Capacitor), and Desktop (Electron) from shared code
• Docker Ready — Containerized deployment for Node.js backend and services
• Enterprise Tooling — ESLint, Prettier, Jest, Cypress, and Storybook preconfigured
• CI/CD Workflows — GitHub Actions for automated testing and deployment
• Real-Time Capabilities — Firebase Realtime Database and Firestore for live data sync

Technology Stack

Requirements

Before setting up, ensure you have:

• Bash 5
• Node.js
• Yarn
• Git
• Firebase
• Docker

Package managers:

• Yarn - preferred for dependencies installation in the project root.
• npm - preferred for dependencies installation in the functions folder.

Supported operating systems:

• Debian based Linux - recommended
  • check out this dev setup instructions to facilitate setting up the dev environment;
  • given that the dev environment is set up, the command yarn install:all:linux should install everything needed to work with the project;
• OSX - should work due to its similarity to Linux
  • one will have to figure out oneself how to set up the dev environment;
  • given that the dev environment is set up, the command yarn install:all:osx should install everything needed to work with the project;
  • the automation scripts support the OS with relatively high probability, but it has not been tested;
• Windows - should work, but no guarantees
  • one will have to figure out oneself how to set up the dev environment;
  • one will have to figure out oneself how to install protolint, see available installation options;
  • given that the dev environment is set up, the following commands should be used to install shellcheck via PowerShell;Example :

    iwr -useb get.scoop.sh | iex
    scoop install shellcheck

  • recommended shell: Git for Windows > Git BASH;
  • configure Git to use LF as a carriage returnExample :

    git config --global core.autocrlf false
    git config --global core.eol lf

Installation & Setup

1. Clone the Repository

git clone https://github.com/rfprod/nx-ng-starter.git
cd nx-ng-starter

2. Install Dependencies, Setup Git Hooks, and Compile Workspace Executors

yarn setup

3. Configure Firebase (Required for Deployment)

Create a firebase.json file in the root directory with your Firebase project credentials:

{
  "projects": {
    "default": "your-firebase-project-id"
  }
}

Alternatively, set environment variables:

export FIREBASE_PROJECT_ID=your-project-id
export FIREBASE_API_KEY=your-api-key

4. Start Development

yarn start

This will start:

• Web app: http://localhost:4200
• API server: http://localhost:8080
• Nx dev server: Watches for changes and rebuilds automatically

5. Commit Changes

Follow the Trunk Based Development methodology to propose changes to the main branch.

Using commitizen cli is mandatory.

Provided all dependencies are installed, and commitizen cli is installed as a global dependency, this command must be used.

git cz

Command Discovery

All Supported Commands

Find all supported commands:

npx nx run tools:help

Running Applications

Find all supported start commands:

npx nx run tools:help --search start

Building Applications

Find all supported build commands:

npx nx run tools:help --search build

Running Tests

Find all supported test commands:

npx nx run tools:help --search test

Deploying Applications

Find all supported firebase commands:

npx nx run tools:help --search firebase

Building Containers

Find all supported docker commands:

npx nx run tools:help --search docker

Running Envoy Unified Reverse Proxy

This section explains how to run the Envoy Unified Reverse Proxy locally with the api-production and client-production containers on a shared Docker network.

Prerequisites

Built images:

• rfprod/nx-ng-starter:api-production-latest
• rfprod/nx-ng-starter:client-production-latest
• rfprod/nx-ng-starter:envoy-latest

Network Setup

The setup uses a shared Docker network named nx-ng-apps for container-to-container communication with STRICT_DNS resolution.

The run script creates the network automatically if it does not exist.

The script automatically:

• Creates the nx-ng-apps network if it doesn't exist
• Connects containers to the shared network
• Maps appropriate ports (8090 for Envoy, 8081 for client, 8080 for API)
• Exposes port 9901 for the Admin UI

Running the Containers

While it is possible to operate containers manually, it is recommended to use existing scripts.

1. Start the API Backend

sudo bash tools/shell/docker/run.sh api-production

The API runs on internal port 8080 and is accessible within the network as api-production:8080.

2. Start the Web Client

sudo bash tools/shell/docker/run.sh client-production

The client runs on internal port 8080 and is accessible within the network as client-production:8080.

3. Start the Envoy Proxy

sudo bash tools/shell/docker/run.sh envoy

The Envoy proxy listens on:

• Port 8090: Main entry point for HTTP traffic
• Port 9901: Admin UI

Routing Configuration

The Envoy configuration (.envoy/envoy.yml) defines two routes:

Testing the Setup

Access the Web Client

curl http://localhost:8090/

Returns the Angular UI from client-production.

Access the API Swagger Documentation

curl http://localhost:8090/api/

Returns the Swagger documentation from api-production, redirects to http://localhost:8090/api/index.html.

Access the Admin UI

curl http://localhost:9901/stats

Container Name Resolution

Inside the shared network, containers resolve each other by name:

• api-production → reaches the API backend
• client-production → reaches the web client

This is enabled by Envoy's STRICT_DNS cluster type, which performs DNS lookups using the Docker embedded DNS resolver.

Cleanup

Stop all containers:

sudo docker stop api-production client-production envoy

Remove the network (if no longer needed):

sudo docker network rm nx-ng-apps

Workspace generators

Library generators

feature library

npx nx generate client-feature client-<feature-name> --tags=scope:client-<feature-name>,type:feature

ui library

npx nx generate client-ui client-<feature-name> --tags=scope:client-<feature-name>,type:ui

data-access library

npx nx generate client-store client-store-<feature-name> --tags=scope:client-store-<feature-name>,type:data-access

util library

npx nx generate client-util client-util-<feature-name> --tags=scope:client-util-<feature-name>,type:util

Audit module boundaries

npx nx generate module-boundaries

Build the dependency graph

npx nx dep-graph

GitBook documentation

The GitBook documentation is generated based on this GitHub repo.

• GitBook documentation

Firebase deployments

Application deployments and autogenerated engineering documentation.

• Client
• Elements
• Documentation
  • Compodoc
  • Unit test reports
  • E2E test reports
  • Changelogs

General Tooling

This project was generated using Nx.

• Nx Documentation
• 30-minute video showing all Nx features
• Interactive Tutorial

How to contribute to this project?

Refer to the CONTRIBUTING.md file for guidelines.

Good luck! 👍