Immutable Web Apps are composed of two concepts:

• Immutable Assets: Static assets (javascript, CSS, images) that do not contain any environment-specific configuration and are hosted at a permanent, versioned, long-term browser cached location.


• Deployment Manifest: An index.html that is unique to the environment and not cached by the browser. It contains environment-specific configuration, references to the versioned immutable assets, and meta data.

Using a combination of npm, UNPKG, and Github Pages covers nearly all of these requirements!

• npm: The software registry stores the the static assets in versioned, immutable packages.


• UNPKG: The CDN makes all assets of the packages on npm addressable over https and globally available.


• GitHub Pages: This static hosting site supports easy configuration of DNS and HTTPS, has great integration with GitHub (obviously), and has a short TTL for browser caching

The git repository unpkg-immutable-example is split into two critical branches:

• default is where the Angular project is maintained. It was generated from Angular CLI and is maintained like any other static web application.


• master is configured to serve the GitHub Pages site. It only contains a single file 404.html. This single file is served for every request made to the GitHub Pages site.

Developing this web application is the same as any other Angular project. Features are built and tested locally, commits and pull requests advance the state of the codebase. When a stable version of the app is ready to be deployed, the assets are rendered to the /dist folder using npm run build and new version of the project is published to npm using npm publish. The assets become available on UNPKG.

With the new version of the assets available on UNPKG, an atomic deployment can be triggered by switching to the master branch and updating 404.html with the new references to project assets via UNPKG and any related changes to environment variables. Once the commit is made, GitHub Pages deployment is triggered and the new version of the web application is available.

With our Immutable Web App hosted by npm/UNPKG and without any environment-specific configuration, deployments are cheap and reliable! Let's deploy index.html to wherever it is easiest to setup DNS and HTTPS!

and let's change the version!

• Create a new Github repo
• Configure the repo as a publishing source for Github Pages
• Commit the index.html as a custom 404 page
• Deployed!

and let's change some environment variables!

• Create a Netlify account
• Run npm i -g netlify-cli
• Run netlify login
• Create a folder for the index.html
• Run netlify deploy
• Deployed!