Skip to content

Commit 29d215f

Browse files
Gene Connollygconnolly
Gene Connolly
authored and
gconnolly
committed
start to add content describing the project
1 parent 61a8802 commit 29d215f

File tree

8 files changed

+121
-53
lines changed

8 files changed

+121
-53
lines changed

‎README.md

Lines changed: 54 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,54 @@
1-
# NgImmutableExample
2-
3-
This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 7.0.3.
4-
5-
## Development server
6-
7-
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
8-
9-
## Code scaffolding
10-
11-
Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
12-
13-
## Build
14-
15-
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build.
16-
17-
## Running unit tests
18-
19-
Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
20-
21-
## Running end-to-end tests
22-
23-
Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/).
24-
25-
## Further help
26-
27-
To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
1+
<h1>unpkg-immutable-example</h1>
2+
<h2>Hosting an <a href="https://immutablewebapps.org">Immutable Web App</a> with <a href="https://www.npmjs.com/">npm</a>,
3+
<a href="https://unpkg.com/#/">UNPKG</a>, and <a href="https://pages.github.com/">GitHub Pages</a></h2>
4+
<p>Immutable Web Apps are composed of two concepts:</p>
5+
<ul>
6+
<li><b>Immutable Assets:</b> Static assets (javascript, CSS, images) that are hosted at a permanent, versioned,
7+
long-term browser cached location and that do not contain any environment-specific configuration.</li>
8+
<br />
9+
<li><b>Deployment Manifest:</b> An <code>index.html</code> that is unique to the environment and not cached by the
10+
browser. It contains environment-specific configuration, references to the versioned immutable assets, and meta
11+
data.</li>
12+
</ul>
13+
<p>Using a combination of npm, UNPKG, and Github Pages covers nearly all of these requirements!</p>
14+
<ul>
15+
<li><b><a href="https://www.npmjs.com/">npm</a>:</b> The software registry stores the the static assets in
16+
versioned, immutable packages.</li>
17+
<br />
18+
<li><b><a href="https://unpkg.com/#/">UNPKG</a>:</b> The CDN makes all assets of the package on npm addressable
19+
over https
20+
and globally available.</li>
21+
<br />
22+
<li><b><a href="https://pages.github.com/">GitHub Pages</a>:</b> This static hosting site supports easy
23+
configuration of DNS and Certificates, has great integration with GitHub (obviously), and has a short TTL for
24+
browser caching</li>
25+
</ul>
26+
<h2><i>This site is hosted using npm, UNPKG, and GitHub Pages!</i></h2>
27+
<h3>Project Structure</h3>
28+
<p>The git repository <a href="https://github.com/ImmutableWebApps/unpkg-immutable-example">unpkg-immutable-example</a>
29+
is split into two critical branches:
30+
<ul>
31+
<li><a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/tree/default"><code>default</code></a>
32+
is where the Angular project is maintained. It was generated from Angular CLI and is generally maintained like
33+
any other static web application.</li>
34+
<br />
35+
<li><a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/tree/master"><code>master</code></a> is
36+
configured to serve the GitHub Pages site. It only contains a single file <a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/blob/master/404.html"><code>404.html</code></a>.
37+
This single file is served for every request made to the GitHub Pages site.</li>
38+
</ul>
39+
<h3>Project Lifecycle</h3>
40+
<h4>Building</h4>
41+
<p>Developing this web application is the same as any other. Features are built and tested locally, commits and
42+
pull requests advance the state of the codebase. When a stable version of the app is ready to be deployed, the
43+
assets are rendered to the <code>/dist</code> folder using <code>npm run build</code> and new version of the
44+
project is published to npm using <code>npm publish</code>. The assets become available on <a href="https://unpkg.com/@immutablewebapps/[email protected]/">UNPKG</a>.</p>
45+
<h4>Deploying</h4>
46+
<p>With the new version of the assets available on UNPKG, we can trigger an <i>atomic</i> deployment by
47+
switching to the <code>master</code> branch and updating <code>404.html</code> with the new references to project
48+
assets via UNPKG as well as any related changes to environment variables. Once the commit is made, GitHub Pages
49+
deployment is triggered and the new version of the web application is available.</p>
50+
<h4>Deploying to Another Environment</h4>
51+
<p>Setup another <a href="https://github.com/ImmutableWebApps/unpkg-immutable-deployment">Github Pages repository</a>,
52+
add a <a href="https://github.com/ImmutableWebApps/unpkg-immutable-deployment/blob/master/404.html"><code>404.html</code></a>,
53+
and <a href="https://immutablewebapps.org/unpkg-immutable-deployment/">another deployment of the app</a> is
54+
created!</p>

‎angular.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
"options": {
1616
"deployUrl": "<%=deployUrl%>",
1717
"baseHref": "<%=baseHref%>",
18-
"outputPath": "dist/unpkg-immutable-example",
18+
"outputPath": "dist",
1919
"index": "src/index.ejs",
2020
"main": "src/main.ts",
2121
"polyfills": "src/polyfills.ts",
@@ -38,7 +38,7 @@
3838
}
3939
],
4040
"optimization": true,
41-
"outputHashing": "all",
41+
"outputHashing": "none",
4242
"sourceMap": false,
4343
"extractCss": true,
4444
"namedChunks": false,

‎package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,6 @@
4646
"typescript": "~3.1.1"
4747
},
4848
"files": [
49-
"dist/unpkg-immutable-example"
49+
"dist"
5050
]
5151
}

‎src/app/app.component.html

Lines changed: 56 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,56 @@
1-
<!--The content below is only a placeholder and can be replaced.-->
2-
<div style="text-align:center">
3-
<h1>
4-
Welcome to {{ title }}!
5-
</h1>
6-
<img width="300" alt="Angular Logo" src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNTAgMjUwIj4KICAgIDxwYXRoIGZpbGw9IiNERDAwMzEiIGQ9Ik0xMjUgMzBMMzEuOSA2My4ybDE0LjIgMTIzLjFMMTI1IDIzMGw3OC45LTQzLjcgMTQuMi0xMjMuMXoiIC8+CiAgICA8cGF0aCBmaWxsPSIjQzMwMDJGIiBkPSJNMTI1IDMwdjIyLjItLjFWMjMwbDc4LjktNDMuNyAxNC4yLTEyMy4xTDEyNSAzMHoiIC8+CiAgICA8cGF0aCAgZmlsbD0iI0ZGRkZGRiIgZD0iTTEyNSA1Mi4xTDY2LjggMTgyLjZoMjEuN2wxMS43LTI5LjJoNDkuNGwxMS43IDI5LjJIMTgzTDEyNSA1Mi4xem0xNyA4My4zaC0zNGwxNy00MC45IDE3IDQwLjl6IiAvPgogIDwvc3ZnPg==">
7-
</div>
8-
<h2>Here are some links to help you start: </h2>
9-
<ul>
10-
<li>
11-
<h2><a target="_blank" rel="noopener" href="https://angular.io/tutorial">Tour of Heroes</a></h2>
12-
</li>
13-
<li>
14-
<h2><a target="_blank" rel="noopener" href="https://github.com/angular/angular-cli/wiki">CLI Documentation</a></h2>
15-
</li>
16-
<li>
17-
<h2><a target="_blank" rel="noopener" href="https://blog.angular.io/">Angular blog</a></h2>
18-
</li>
19-
</ul>
20-
1+
<div [style.background-color]="color">
2+
<h1>{{ title }}</h1>
3+
<h2>Hosting an <a href="https://immutablewebapps.org">Immutable Web App</a> with <a href="https://www.npmjs.com/">npm</a>,
4+
<a href="https://unpkg.com/#/">UNPKG</a>, and <a href="https://pages.github.com/">GitHub Pages</a></h2>
5+
<p>Immutable Web Apps are composed of two concepts:</p>
6+
<ul>
7+
<li><b>Immutable Assets:</b> Static assets (javascript, CSS, images) that are hosted at a permanent, versioned,
8+
long-term browser cached location and that do not contain any environment-specific configuration.</li>
9+
<br />
10+
<li><b>Deployment Manifest:</b> An <code>index.html</code> that is unique to the environment and not cached by the
11+
browser. It contains environment-specific configuration, references to the versioned immutable assets, and meta
12+
data.</li>
13+
</ul>
14+
<p>Using a combination of npm, UNPKG, and Github Pages covers nearly all of these requirements!</p>
15+
<ul>
16+
<li><b><a href="https://www.npmjs.com/">npm</a>:</b> The software registry stores the the static assets in
17+
versioned, immutable packages.</li>
18+
<br />
19+
<li><b><a href="https://unpkg.com/#/">UNPKG</a>:</b> The CDN makes all assets of the package on npm addressable
20+
over https
21+
and globally available.</li>
22+
<br />
23+
<li><b><a href="https://pages.github.com/">GitHub Pages</a>:</b> This static hosting site supports easy
24+
configuration of DNS and Certificates, has great integration with GitHub (obviously), and has a short TTL for
25+
browser caching</li>
26+
</ul>
27+
<h2><i>This site is hosted using npm, UNPKG, and GitHub Pages!</i></h2>
28+
<h3>Project Structure</h3>
29+
<p>The git repository <a href="https://github.com/ImmutableWebApps/unpkg-immutable-example">unpkg-immutable-example</a>
30+
is split into two critical branches:
31+
<ul>
32+
<li><a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/tree/default"><code>default</code></a>
33+
is where the Angular project is maintained. It was generated from Angular CLI and is generally maintained like
34+
any other static web application.</li>
35+
<br />
36+
<li><a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/tree/master"><code>master</code></a> is
37+
configured to serve the GitHub Pages site. It only contains a single file <a href="https://github.com/ImmutableWebApps/unpkg-immutable-example/blob/master/404.html"><code>404.html</code></a>.
38+
This single file is served for every request made to the GitHub Pages site.</li>
39+
</ul>
40+
<h3>Project Lifecycle</h3>
41+
<h4>Building</h4>
42+
<p>Developing this web application is the same as any other. Features are built and tested locally, commits and
43+
pull requests advance the state of the codebase. When a stable version of the app is ready to be deployed, the
44+
assets are rendered to the <code>/dist</code> folder using <code>npm run build</code> and new version of the
45+
project is published to npm using <code>npm publish</code>. The assets become available on <a href="https://unpkg.com/@immutablewebapps/[email protected]/">UNPKG</a>.</p>
46+
<h4>Deploying</h4>
47+
<p>With the new version of the assets available on UNPKG, we can trigger an <i>atomic</i> deployment by
48+
switching to the <code>master</code> branch and updating <code>404.html</code> with the new references to project
49+
assets via UNPKG as well as any related changes to environment variables. Once the commit is made, GitHub Pages
50+
deployment is triggered and the new version of the web application is available.</p>
51+
<h4>Deploying to Another Environment</h4>
52+
<p>Setup another <a href="https://github.com/ImmutableWebApps/unpkg-immutable-deployment">Github Pages repository</a>,
53+
add a <a href="https://github.com/ImmutableWebApps/unpkg-immutable-deployment/blob/master/404.html"><code>404.html</code></a>,
54+
and <a href="https://immutablewebapps.org/unpkg-immutable-deployment/">another deployment of the app</a> is
55+
created!</p>
56+
</div>

‎src/app/app.component.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
import { Component } from '@angular/core';
2-
2+
import { environment } from '../environments/environment';
33
@Component({
44
selector: 'app-root',
55
templateUrl: './app.component.html',
66
styleUrls: ['./app.component.css']
77
})
88
export class AppComponent {
99
title = 'unpkg-immutable-example';
10+
color = environment.color;
1011
}

‎src/environments/environment.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
// The list of file replacements can be found in `angular.json`.
44

55
export const environment = {
6-
production: false
6+
production: false,
7+
color: 'transparent'
78
};
89

910
/*

‎src/index.ejs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html lang="en">
33
<head>
44
<meta charset="utf-8">
5-
<title>NgImmutableExample</title>
5+
<title>unpkg-immutable-example</title>
66
<base href="/">
77

88
<meta name="viewport" content="width=device-width, initial-scale=1">

‎src/styles.css

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,4 @@
11
/* You can add global styles to this file, and also import other style files */
2+
body {
3+
font-family: "Courier New", Courier, monospace;
4+
}

0 commit comments

Comments
 (0)