App Configuration Guide

Complete guide to configuring NX applications in the GoGrab Space monorepo, including TypeScript configuration, build setup, and common troubleshooting.

TypeScript Configuration

Configuration Hierarchy

Our NX apps use a layered TypeScript configuration that inherits from the workspace root:

tsconfig.base.json (workspace)
  ↓
apps/<app>/tsconfig.json (app root)
  ↓
apps/<app>/tsconfig.app.json (Angular build)

tsconfig.base.json (Workspace Root)

Defines all library path aliases for the entire workspace:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@ux-portal": ["libs/ux-portal/src/index"],
      "@ux-portal/*": ["libs/ux-portal/src/*"],
      "@storage-system": ["libs/storage-system/src/index"],
      "@storage-system/*": ["libs/storage-system/src/*"]
    }
  }
}

Key Points:

• Always define both root alias and wildcard (/*)
• Paths point to SOURCE (libs/...), NOT dist/libs/...
• Angular's build system handles bundling automatically

apps/<app>/tsconfig.json (App Root)

Extends workspace config and sets app-specific compiler options:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true
  },
  "files": [],
  "include": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.spec.json" }
  ]
}

Important: Do NOT redefine path aliases here - they inherit from tsconfig.base.json.

apps/<app>/tsconfig.app.json (Angular Build)

Configuration used by Angular's application builder:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "types": ["node"]
  },
  "files": ["src/main.ts"],
  "include": ["src/**/*.ts", "src/**/*.d.ts"],
  "exclude": [
    "jest.config.ts",
    "src/**/*.test.ts",
    "src/**/*.spec.ts"
  ],
  "angularCompilerOptions": {
    "strictTemplates": true,
    "strictInjectionParameters": true
  }
}

Critical: The include must have both src/**/*.ts AND src/**/*.d.ts for proper type resolution.

Project Configuration (project.json)

Build Target

{
  "build": {
    "executor": "@angular-devkit/build-angular:application",
    "options": {
      "outputPath": "dist/apps/my-app",
      "index": "apps/my-app/src/index.html",
      "browser": "apps/my-app/src/main.ts",
      "polyfills": ["zone.js"],
      "tsConfig": "apps/my-app/tsconfig.app.json",
      "verbose": false
    },
    "configurations": {
      "production": {
        "budgets": [
          {
            "type": "initial",
            "maximumWarning": "1.5mb",
            "maximumError": "2mb"
          }
        ],
        "allowedCommonJsDependencies": [
          "dayjs",
          "debug"
        ]
      }
    }
  }
}

Key Settings:

• verbose: false - Suppresses DEBUG warnings from dependencies
• allowedCommonJsDependencies - Whitelist CommonJS packages to avoid warnings
• budgets - Set realistic bundle size limits

Serve Target

{
  "serve": {
    "executor": "@angular-devkit/build-angular:dev-server",
    "options": {
      "buildTarget": "my-app:build"
    },
    "configurations": {
      "production": {
        "buildTarget": "my-app:build:production"
      },
      "development": {
        "buildTarget": "my-app:build:development"
      }
    },
    "defaultConfiguration": "development"
  }
}

Critical: buildTarget is required for the dev-server executor.

Parallel Command Execution

To run multiple processes (e.g., dev server + file watchers):

{
  "serve": {
    "executor": "nx:run-commands",
    "options": {
      "parallel": true,
      "commands": [
        "node scripts/start-admin-server.js",
        "node scripts/watch-changes.js",
        "nx run my-app:serve-only"
      ]
    }
  }
}

Note: Use nx:run-commands executor for parallel tasks, NOT @angular-devkit/build-angular:dev-server.

ESLint Configuration

Supporting Angular 17+ Control Flow Syntax

For Angular 17+ template syntax (@if, @for, etc.):

// libs/my-lib/eslint.config.mjs
import baseConfig from '../../eslint.config.mjs';
import angularTemplate from '@angular-eslint/eslint-plugin-template';
import angularTemplateParser from '@angular-eslint/template-parser';

export default [
  ...baseConfig,
  {
    files: ['**/*.ts'],
    rules: {
      '@angular-eslint/component-selector': ['error', {
        type: 'element',
        prefix: 'app',
        style: 'kebab-case'
      }]
    }
  },
  {
    files: ['**/*.html'],
    plugins: {
      '@angular-eslint/template': angularTemplate
    },
    languageOptions: {
      parser: angularTemplateParser
    },
    rules: {
      '@angular-eslint/template/no-negated-async': 'off'
    }
  }
];

Key: The Angular template parser (@angular-eslint/template-parser) understands new control flow syntax.

Common Configuration Issues

❌ "Cannot find module '@library-name'"

Causes:

1. Library not built
2. Path missing from tsconfig.base.json
3. Missing src/**/*.ts in tsconfig.app.json include
4. Incorrect path pointing to dist/ instead of libs/

Solutions:

# 1. Build the library
npx nx build library-name

# 2. Verify path exists in tsconfig.base.json
grep "@library-name" tsconfig.base.json

# 3. Check tsconfig.app.json includes source files
cat apps/my-app/tsconfig.app.json | grep include

# 4. Restart TypeScript server (VSCode)
# Cmd+Shift+P → "TypeScript: Restart TS Server"

❌ "Required property 'buildTarget' is missing"

Cause: Wrong executor for serve target.

Solution: Use correct executor:

{
  "serve": {
    "executor": "@angular-devkit/build-angular:dev-server",
    "options": {
      "buildTarget": "my-app:build"
    }
  }
}

❌ "Parsing error: '>' expected" (in HTML templates)

Cause: ESLint doesn't recognize Angular 17+ control flow syntax.

Solution: Configure Angular template parser (see ESLint Configuration section above).

❌ Bundle size warnings

Cause: Default budgets are too strict for modern apps.

Solution: Update budgets in project.json:

{
  "budgets": [
    {
      "type": "initial",
      "maximumWarning": "1.5mb",
      "maximumError": "2mb"
    }
  ]
}

❌ CommonJS dependency warnings

Cause: Using CommonJS packages in Angular (ESM) build.

Solution: Whitelist them:

{
  "configurations": {
    "production": {
      "allowedCommonJsDependencies": [
        "dayjs",
        "debug",
        "cytoscape"
      ]
    }
  }
}

Build Commands

# Development build
npx nx build my-app

# Production build
npx nx build my-app --configuration=production

# Skip cache (clean build)
npx nx build my-app --skip-nx-cache

# Verbose output (for debugging)
npx nx build my-app --verbose

# Build all apps
npx nx run-many --target=build --all

Serve Commands

# Development server
npx nx serve my-app

# Production mode
npx nx serve my-app --configuration=production

# Custom port
npx nx serve my-app --port=4300

# Open browser automatically
npx nx serve my-app --open

Best Practices

✅ Import from source - Use libs/... not dist/libs/... in tsconfig paths ✅ Include source files - Always have src/**/*.ts in tsconfig.app.json ✅ Use verbose: false - Reduce build noise in production ✅ Set realistic budgets - Modern apps are larger than default limits ✅ Whitelist CommonJS deps - Avoid unnecessary warnings ✅ Configure ESLint for Angular 17+ - Support new control flow syntax ✅ Build libraries first - Run nx build library-name before using ✅ Restart TS server - After config changes for proper type resolution

Related Documentation

• App Imports Guide - Import strategies and path aliases
• NX Monorepo Structure - Workspace organization
• Library Configuration - Library setup and building