Microtec DevOps

Appearance

Local Development ​

This page covers everything needed to run the frontend locally: initial setup, choosing what to start, developing a single remote against deployed stage remotes, and fixing the most common issues.

Prerequisites ​

ToolMinimum VersionInstall
Node.js18.x LTSnodejs.org
npm9.xbundled with Node.js
Nx CLIlatestnpm i -g nx (optional — you can use npx nx)

Initial Setup ​

bash
# Clone the MFE-Apps repository
cd MFE-Apps

# Install dependencies — the --f flag is mandatory
npm i --f

The --f flag is not optional

Angular packages have peer dependency conflicts that cause npm install to fail without the force flag. Never run npm i without --f in this workspace.

Starting Apps ​

Start everything ​

bash
npm run start:all

Starts the host shell (erp-home) and all remote apps simultaneously. Uses concurrently to manage all processes. Expect the terminal to show coloured output from each app.

AppURL
erp-home (host shell)http://localhost:4401
bussiness-ownershttp://localhost:4301
apps-accountinghttp://localhost:4402
apps-hrhttp://localhost:4403
apps-financehttp://localhost:4404
apps-saleshttp://localhost:4405
apps-purchasehttp://localhost:4406
apps-inventoryhttp://localhost:4407
app-distributionhttp://localhost:4408
fixed-assetshttp://localhost:4409

Start only ERP apps ​

bash
npm run start:erp

Starts erp-home plus all ERP remotes (ports 4401–4409). Does not start bussiness-owners.

Start a single app ​

bash
# Using the npm script shorthand
npm run start:accounting       # apps-accounting on :4402
npm run start:hr               # apps-hr on :4403
npm run start:finance          # apps-finance on :4404
npm run start:sales            # apps-sales on :4405
npm run start:purchase         # apps-purchase on :4406
npm run start:inventory        # apps-inventory on :4407
npm run start:distribution     # app-distribution on :4408
npm run start:fixed-assets     # fixed-assets on :4409
npm run start:bussiness-owners # bussiness-owners on :4301

# Or using Nx directly
nx serve apps-accounting --port 4402

Developing One Remote Against Deployed Remotes ​

Running all 13 apps simultaneously is CPU-intensive. The recommended workflow when working on a single module is to:

  1. Run only the host shell and your target remote locally.
  2. Point the host's environment file at deployed stage remote entries for all other apps.

Step-by-step ​

1. Edit the host's development environment file:

typescript
// apps/erp-home/src/environments/environment.ts
export const environment = {
  production: false,
  isDevelopment: true,
  apiBaseUrl: 'https://gateway.microtecstage.com',
  keycloakUrl: 'https://keycloak.microtecstage.com',
  keycloakRealm: 'microtec',
  remoteEntries: {
    // The app you are developing — local
    accounting: 'http://localhost:4402/remoteEntry.js',

    // All others — use deployed stage SWAs
    hr:           'https://hr.microtecstage.com/remoteEntry.js',
    finance:      'https://finance.microtecstage.com/remoteEntry.js',
    sales:        'https://sales.microtecstage.com/remoteEntry.js',
    purchase:     'https://purchase.microtecstage.com/remoteEntry.js',
    inventory:    'https://inventory.microtecstage.com/remoteEntry.js',
    distribution: 'https://distribution.microtecstage.com/remoteEntry.js',
    fixedAssets:  'https://fixed-assets.microtecstage.com/remoteEntry.js',
  },
};

2. Start only the host and your remote:

bash
# Terminal 1 — host shell
npm run start:erp-home

# Terminal 2 — only the module under development
npm run start:accounting

3. Open http://localhost:4401 — the host loads your local accounting remote; all other modules load from stage.

Stage authentication works locally

Because the environment file now points to gateway.microtecstage.com, API calls go to stage. Keycloak SSO with the stage Keycloak works fine from localhost — ensure the Keycloak client has http://localhost:4401/* in its Valid Redirect URIs.

Revert the environment file before committing

Do not commit a environment.ts that points at stage. The file should always have localhost:{port} entries for development. Use git stash or a local git config to keep the change local.

Keycloak Authentication Locally ​

All local development uses the dev Keycloak (https://keycloak.microtec-test.com) by default, or the stage Keycloak if you pointed the environment file at stage.

The Keycloak login page opens in the browser on first load. After logging in, Keycloak issues a session that persists across all apps on different ports via silent SSO.

You do not need a local Keycloak instance

The dev and stage Keycloak instances are always running in Azure. There is no need to install or run Keycloak locally.

Running with Production-Like Config Locally ​

To test an environment's configuration without deploying:

bash
# Build and serve locally with a specific config
nx serve apps-accounting --configuration=stage

This uses environment.stage.ts — stage API URLs and Keycloak. The app still runs on localhost:4402.

Common Issues ​

npm i fails with peer dependency errors ​

bash
# Always use --f
npm i --f

White screen on http://localhost:4401 ​

The host loaded but a remote failed. Check:

  1. Is the failing remote app running? Check the terminal for its process.
  2. Open browser dev tools → Network tab → look for a failed remoteEntry.js request.
  3. Verify the remote entry URL in environment.ts matches where the remote is running.

Error: Shared module ... is not available for eager consumption ​

Angular or a shared library was not bootstrapped correctly in a remote. Ensure the remote's main.ts uses dynamic import bootstrapping:

typescript
// apps/apps-accounting/src/main.ts
import('./bootstrap').catch(err => console.error(err));
typescript
// apps/apps-accounting/src/bootstrap.ts
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';

platformBrowserDynamic()
  .bootstrapModule(AppModule)
  .catch(err => console.error(err));

Keycloak login loop when switching between ports ​

The Keycloak client's Valid Redirect URIs do not include the current port. Add http://localhost:{port}/* to the client in Keycloak admin console for the relevant realm.

Hot reload not working after a code change ​

Nx's webpack dev server uses HMR. If changes do not reflect:

  1. Hard-reload the browser (Ctrl+Shift+R).
  2. If still stale, stop and restart the specific app's dev server.
  3. Ensure you saved the file — auto-save may be delayed in some editors.

Out-of-memory crash during start:all ​

bash
# Set a higher Node.js heap limit before starting
export NODE_OPTIONS=--max-old-space-size=8192
npm run start:all

For machines with less than 16 GB RAM, run only the apps you need rather than start:all.

Useful Nx Commands for Development ​

bash
# List all projects in the workspace
nx list

# Show dependency graph
nx graph

# Run tests for a specific app
nx test apps-accounting

# Run tests for affected apps only (faster in CI)
nx affected:test

# Lint a specific app
nx lint apps-accounting

# Check TypeScript compilation without building
nx run apps-accounting:type-check

# Build a single app for production (to verify build output)
nx build apps-accounting --configuration=prod

Internal Documentation — Microtec Platform Team