Deployment guide

Overview

This guide covers building, packaging, and deploying the Angular PWA Demo application. The project includes production-optimized build configurations and automated deployment scripts.

Build configurations

The application uses Angular’s build system configured in angular.json with optimizations for production.

Available build modes

Development

Unoptimized build with source maps and debugging enabled

Production

Optimized build with minification, tree-shaking, and output hashing

Build scripts

The package.json includes several build and deployment scripts:

{
  "scripts": {
    "start": "ng serve --disable-host-check",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test",
    "_package": "ng build --c=production --base-href=\"/PWA_DEMO_ENV_PROD\"",
    "_publish": "npx ngh --dir=dist\\PWA_DEMO_ENV_PROD\\browser",
    "package-and-publish": "ng build --c=production --base-href=\"/PWA_DEMO_ENV_PROD/\" && npx ngh --dir=dist\\PWA_DEMO_ENV_PROD\\browser"
  }
}

Development builds

Start the development server

Run the development server with live reload:

npm start

The app will be available at http://localhost:4200.

Build in watch mode

For continuous builds during development:

npm run watch

This rebuilds automatically when files change.

Build for development

Create a development build without watch mode:

npm run build -- --configuration development

The --disable-host-check flag in the start script allows access from different hostnames, useful for testing on mobile devices.

Production builds

Build for production

Create an optimized production build:

npm run build

This uses the production configuration by default.

Verify the build

Check the output in the dist/PWA_DEMO_ENV_PROD/browser directory:

ls -la dist/PWA_DEMO_ENV_PROD/browser

Test the production build locally

Serve the production build using a static server:

npx http-server dist/PWA_DEMO_ENV_PROD/browser -p 8080

Build configuration details

The angular.json file configures production optimizations:

{
  "configurations": {
    "production": {
      "budgets": [
        {
          "type": "initial",
          "maximumWarning": "2mb",
          "maximumError": "25mb"
        },
        {
          "type": "anyComponentStyle",
          "maximumWarning": "5mb",
          "maximumError": "5mb"
        }
      ],
      "outputHashing": "all"
    },
    "development": {
      "optimization": false,
      "extractLicenses": false,
      "sourceMap": true,
      "namedChunks": true
    }
  }
}

Production optimizations

Output hashing

All files get content-based hashes for cache busting: main.a1b2c3d4.js

Bundle budgets

Warnings trigger at 2MB, errors at 25MB for initial bundles to keep load times fast

Tree shaking

Removes unused code to minimize bundle size

Minification

JavaScript and CSS are minified for smaller file sizes

Dead code elimination

Removes unreachable code paths

The bundle size limit is set to 25MB to accommodate Three.js and other large dependencies. Consider code splitting for larger applications.

PWA configuration

The application includes Progressive Web App features configured in angular.json:

{
  "assets": [
    "src/favicon.ico",
    "src/assets",
    "src/manifest.webmanifest"
  ],
  "serviceWorker": "ngsw-config.json"
}

Service worker setup

The service worker enables offline functionality and caching:

Manifest file: src/manifest.webmanifest defines app metadata
Service worker config: ngsw-config.json controls caching strategies
Assets: Static files are cached for offline use

Service workers only work over HTTPS in production. Use localhost for development testing.

Deployment to GitHub Pages

The project includes scripts for deploying to GitHub Pages using angular-cli-ghpages.

Configure base href

The _package script sets the correct base href for GitHub Pages:

npm run _package

This builds with --base-href="/PWA_DEMO_ENV_PROD".

Publish to GitHub Pages

Deploy the built application:

npm run _publish

This uses angular-cli-ghpages to push the dist folder to the gh-pages branch.

One-command deployment

Build and deploy in a single command:

npm run package-and-publish

GitHub Pages configuration

The deployment uses the following settings:

Base href: /PWA_DEMO_ENV_PROD/ (matches repository name)
Output directory: dist/PWA_DEMO_ENV_PROD/browser
Branch: gh-pages (created automatically)

Deployment to other platforms

Netlify
Vercel
Firebase
Docker

Deploy to Netlify using drag-and-drop or CLI:

# Build the app
npm run build

# Install Netlify CLI
npm install -g netlify-cli

# Deploy
netlify deploy --prod --dir=dist/PWA_DEMO_ENV_PROD/browser

netlify.toml configuration:

[build]
  publish = "dist/PWA_DEMO_ENV_PROD/browser"
  command = "npm run build"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Deploy to Vercel:

# Install Vercel CLI
npm install -g vercel

# Deploy
vercel --prod

vercel.json configuration:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist/PWA_DEMO_ENV_PROD/browser",
  "rewrites": [
    { "source": "/(.*)", "destination": "/" }
  ]
}

Deploy to Firebase Hosting:

# Install Firebase CLI
npm install -g firebase-tools

# Login
firebase login

# Initialize
firebase init hosting

# Deploy
npm run build
firebase deploy

firebase.json configuration:

{
  "hosting": {
    "public": "dist/PWA_DEMO_ENV_PROD/browser",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

Deploy using Docker with nginx:Dockerfile:

# Build stage
FROM node:21-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM nginx:alpine
COPY --from=build /app/dist/PWA_DEMO_ENV_PROD/browser /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

nginx.conf:

server {
  listen 80;
  location / {
    root /usr/share/nginx/html;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
}

Build and run:

docker build -t angular-pwa-demo .
docker run -p 8080:80 angular-pwa-demo

Environment configuration

For different environments, configure the base URLs in src/assets/config/config.json:

{
  "appBrand": "Angular PWA Demo",
  "appVersion": "1.0.0",
  "baseUrlNetCore": "https://api.production.com/",
  "baseUrlNodeJs": "https://nodejs-api.production.com/",
  "baseUrlSpringBootJava": "https://java-api.production.com/",
  "baseUrlDjangoPython": "https://python-api.production.com/"
}

Never commit sensitive API keys or credentials to the repository. Use environment variables or secure secret management.

Post-deployment verification

Check application loads

Navigate to your deployment URL and verify the app loads correctly.

Test PWA features

Open DevTools > Application > Service Workers
Verify service worker is registered
Test offline functionality

Verify routing

Test navigation between routes and ensure deep links work.

Check performance

Run Lighthouse audit in Chrome DevTools for performance metrics.

Test on mobile

Verify the app works on mobile devices and can be installed as a PWA.

Troubleshooting

404 errors on route refresh

Configure server redirects to send all routes to index.html. See platform-specific examples above.

Assets not loading

Verify the base-href matches your deployment path. For GitHub Pages, it should match your repository name.

Service worker not registering

Service workers require HTTPS in production. Check browser console for errors.

Bundle size too large

Review bundle budgets in angular.json and consider lazy loading for large modules.

Environment config not loading

Ensure config.json is included in the assets array in angular.json.

Next steps

Configuration guide

Learn about application configuration

Components guide

Build custom components

Get Started

Core Concepts

Features

Guides

Overview

Build configurations

Available build modes

Development

Production

Build scripts

Development builds

Production builds

Build configuration details

Production optimizations

PWA configuration

Service worker setup

Deployment to GitHub Pages

GitHub Pages configuration

Deployment to other platforms

Environment configuration

Post-deployment verification

Troubleshooting

Next steps

Configuration guide

Components guide

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Guides

​Overview

​Build configurations

​Available build modes

Development

Production

​Build scripts

​Development builds

​Production builds

​Build configuration details

​Production optimizations

​PWA configuration

​Service worker setup

​Deployment to GitHub Pages

​GitHub Pages configuration

​Deployment to other platforms

​Environment configuration

​Post-deployment verification

​Troubleshooting

​Next steps

Configuration guide

Components guide

Build docs developers (and LLMs) love

Overview

Build configurations

Available build modes

Build scripts

Development builds

Production builds

Build configuration details

Production optimizations

PWA configuration

Service worker setup

Deployment to GitHub Pages

GitHub Pages configuration

Deployment to other platforms

Environment configuration

Post-deployment verification

Troubleshooting

Next steps