Skip to content

Commit e7e6708

Browse files
yharaskrikyharaskrik
authored
docs(universal): fix issues with inconsistent documentation (#3268)
* docs(universal): fix issues with inconsistent documentation * docs(universal): clarify language around firebase tools/features
1 parent 450ee6e commit e7e6708

File tree

4 files changed

+121
-141
lines changed

4 files changed

+121
-141
lines changed

‎README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,13 @@ The official [Angular](https://angular.io/) library for [Firebase](https://fireb
33

44
<strong><pre>ng add @angular/fire</pre></strong>
55

6-
AngularFire smooths over the rough edges an Angular developer might encounter when implementing the framework-agnostic [Firebase JS SDK](https://github.com/firebase/firebase-js-sdk) & aims to provide a more natural developer experience by conforming to Angular conventions.
6+
_Note: If you want to ng add AngularFire and will be using Hosting/Cloud Functions, you need to configure the
7+
Firebase CLI first so that you are logged in for the schematics that are run as part of `ng add @angular/fire`.
8+
Follow [this guide](docs/install-firebase-tools.md) to have the Firebase CLI walk you through the setup._
9+
10+
AngularFire smooths over the rough edges an Angular developer might encounter when implementing the framework-agnostic
11+
[Firebase JS SDK](https://github.com/firebase/firebase-js-sdk) & aims to provide a more natural developer experience
12+
by conforming to Angular conventions.
713

814
- **Dependency injection** - Provide and Inject Firebase services in your components
915
- **Zone.js wrappers** - Stable zones allow proper functionality of service workers, forms, SSR, and pre-rendering

‎docs/install-firebase-tools.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Firebase Tools Install and Setup
2+
3+
### 1. Install package
4+
5+
```bash
6+
npm install -g firebase-tools
7+
```
8+
9+
or with `yarn`
10+
11+
```bash
12+
yarn global add firebase-tools
13+
```
14+
15+
You can also choose to install it as a dependency for your project rather than globally
16+
17+
```bash
18+
npm install --save-dev firebase-tools
19+
```
20+
21+
or with `yarn`
22+
23+
```bash
24+
yarn add -D firebase-tools
25+
```
26+
27+
### 2. Configure Firebase Tools
28+
29+
In your projects root directory run:
30+
31+
```bash
32+
firebase init
33+
```
34+
35+
or if your installed it within your project rather than globally
36+
37+
```bash
38+
npx firebase init
39+
```
40+
41+
or with `yarn`
42+
43+
```bash
44+
yarn firebase init
45+
```
46+
47+
This will ask you to login if you are not logged in already, the process will take you through a browser
48+
redirect to log you into Firebase.
49+
50+
### 3. Choose what Firebase features
51+
52+
`firebase-tools` displays Firebase features you want to configure.
53+
54+
```bash
55+
? Which Firebase features do you want to set up for this directory? Press Space
56+
to select features, then Enter to confirm your choices. (Press <space> to select
57+
, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
58+
◯ Realtime Database: Configure a security rules file for Realtime Database and
59+
(optionally) provision default instance
60+
◯ Firestore: Configure security rules and indexes files for Firestore
61+
◯ Functions: Configure a Cloud Functions directory and its files
62+
◯ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub
63+
Action deploys
64+
◯ Hosting: Set up GitHub Action deploys
65+
(Move up and down to reveal more choices)
66+
```
67+
68+
### 4. Connect your repo to a Firebase project
69+
70+
The CLI will then walk you through making sure your repo is configured with a Firebase project.
71+
72+
```bash
73+
? Please select an option:
74+
◯ Use an existing project
75+
◯ Create a new project
76+
◯ Add Firebase to an existing Google Cloud Platform project
77+
◯ Don't set up a default project
78+
```

‎docs/universal/cloud-functions.md

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ Let's go ahead and modify your `package.json` to build for Cloud Functions:
4040
```js
4141
"scripts": {
4242
// ... omitted
43-
"build": "ng build && npm run copy:hosting && npm run build:ssr && npm run build:functions",
44-
"copy:hosting": "cp -r ./dist/YOUR_PROJECT_NAME/* ./public && rm ./public/index.html",
43+
"build": "ng build && npm run build:ssr && npm run copy:hosting && npm run build:functions",
44+
"copy:hosting": "cp -r ./dist/YOUR_PROJECT_NAME/* ./public && rm -f ./public/index.html",
4545
"build:functions": "npm run --prefix functions build"
4646
},
4747
```
@@ -51,21 +51,42 @@ Change the build script in your `functions/package.json` to the following:
5151
```js
5252
"scripts": {
5353
// ... omitted
54-
"build": "rm -r ./dist && cp -r ../dist . && tsc",
54+
"build": "rm -rf ./dist && cp -r ../dist . && tsc",
5555
}
5656
```
5757

58+
You will either need to install the dependencies from the `functions/package.json` or add them to your root `package.json`.
59+
5860
Finally, add the following to your `functions/src/index.ts`:
5961

6062
```ts
6163
export const universal = functions.https.onRequest((request, response) => {
62-
require(`${process.cwd()}/dist/YOUR_PROJECT_NAME-webpack/server`).app(request, response);
64+
require(`${process.cwd()}/dist/YOUR_PROJECT_NAME/server/main`).app()(request, response);
6365
});
6466
```
6567

66-
We you should now be able to run `npm run build` to build your project for Firebase Hosting and Cloud Functions.
68+
In the `server.ts` file generated by the Angular CLI ensure that the `index.html` is being read from the correct place.
69+
70+
As of writing the Angular CLI generates:
71+
72+
```typescript
73+
const indexHtml = existsSync(join(distFolder, 'index.original.html')) ? 'index.original.html' : 'index.html';
74+
```
75+
76+
this needs to be changed to:
77+
78+
```typescript
79+
const indexHtml = existsSync(join(distFolder, 'index.original.html')) ? 'index.original.html' : join(distFolder, 'index.html');
80+
```
81+
82+
So that the `index.html` is read from the correct `dist` folder.
83+
84+
You should now be able to run `npm run build` to build your project for Firebase Hosting and Cloud Functions.
85+
86+
To test, spin up the emulator with `firebase serve`. Once you've confirmed its working go ahead and `firebase deploy`.
6787

68-
To test, spin up the emulator with `firebase serve`. Once you've confirmed it's working go ahead and `firebase deploy`.
88+
_Note: Universal will now SSR your application and serve it, depending on how you have your deployment setup some assets may fail to
89+
serve because the Cloud Function is at a different route than the `APP_BASE_REF` configured._
6990

7091
### [Next Step: Prerendering your Universal application](prerendering.md)
7192

‎docs/universal/getting-started.md

Lines changed: 9 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -7,147 +7,22 @@ Server-side rendering (SSR) is the process of converting a JavaScript app to pla
77
- @angular/cli >= v6.0
88
- @angular/fire >= v5.0.0
99

10-
## 1. Generate the Angular Universal Server Module
10+
## 1. Add Angular Universal to your project
1111

12-
First, create a server module with the Angular CLI.
12+
Follow the steps from the [Angular Universal Tutorial](https://angular.io/guide/universal) to add Universal to your
13+
project.
1314

1415
```
15-
ng generate universal --client-project <your-project>
16+
ng add @nguniversal/express-engine
1617
```
1718

18-
## 2. Build a Server with ExpressJS
19+
This will create all the files you need and setup all the configurations for Universal rendering for your application.
1920

20-
[ExpressJS](https://expressjs.com/) is a lightweight web framework that can serve http requests in Node. First, install the dev dependencies:
21+
## 2. Next Steps
2122

22-
```bash
23-
npm install --save-dev @nguniversal/express-engine @nguniversal/module-map-ngfactory-loader express webpack-cli ts-loader ws xhr2
24-
```
25-
26-
Create a file called `server.ts` in the root of you project.
27-
28-
```ts
29-
// These are important and needed before anything else
30-
import 'zone.js/dist/zone-node';
31-
import 'reflect-metadata';
32-
33-
import { enableProdMode } from '@angular/core';
34-
import { ngExpressEngine } from '@nguniversal/express-engine';
35-
import { provideModuleMap } from '@nguniversal/module-map-ngfactory-loader';
36-
37-
import * as express from 'express';
38-
import { join } from 'path';
39-
import { readFileSync } from 'fs';
40-
41-
// Polyfills required for Firebase
42-
(global as any).WebSocket = require('ws');
43-
(global as any).XMLHttpRequest = require('xhr2');
44-
45-
// Faster renders in prod mode
46-
enableProdMode();
47-
48-
// Export our express server
49-
export const app = express();
50-
51-
const DIST_FOLDER = join(process.cwd(), 'dist');
52-
const APP_NAME = 'YOUR_PROJECT_NAME'; // TODO: replace me!
53-
54-
const { AppServerModuleNgFactory, LAZY_MODULE_MAP } = require(`./dist/${APP_NAME}-server/main`);
55-
56-
// index.html template
57-
const template = readFileSync(join(DIST_FOLDER, APP_NAME, 'index.html')).toString();
58-
59-
app.engine('html', ngExpressEngine({
60-
bootstrap: AppServerModuleNgFactory,
61-
providers: [
62-
provideModuleMap(LAZY_MODULE_MAP)
63-
]
64-
}));
65-
66-
app.set('view engine', 'html');
67-
app.set('views', join(DIST_FOLDER, APP_NAME));
68-
69-
// Serve static files
70-
app.get('*.*', express.static(join(DIST_FOLDER, APP_NAME)));
71-
72-
// All regular routes use the Universal engine
73-
app.get('*', (req, res) => {
74-
res.render(join(DIST_FOLDER, APP_NAME, 'index.html'), { req });
75-
});
76-
77-
// If we're not in the Cloud Functions environment, spin up a Node server
78-
if (!process.env.FUNCTION_NAME) {
79-
const PORT = process.env.PORT || 4000;
80-
app.listen(PORT, () => {
81-
console.log(`Node server listening on http://localhost:${PORT}`);
82-
});
83-
}
84-
```
85-
86-
## 3. Add a Webpack Config for the Express Server
87-
88-
Create a new file named `webpack.server.config.js` to bundle the express app from previous step.
89-
90-
91-
```js
92-
const path = require('path');
93-
const webpack = require('webpack');
94-
95-
const APP_NAME = 'YOUR_PROJECT_NAME'; // TODO: replace me!
96-
97-
module.exports = {
98-
entry: { server: './server.ts' },
99-
resolve: { extensions: ['.js', '.ts'] },
100-
mode: 'development',
101-
target: 'node',
102-
externals: [
103-
/* Firebase has some troubles being webpacked when in
104-
in the Node environment, let's skip it.
105-
Note: you may need to exclude other dependencies depending
106-
on your project. */
107-
/^firebase/
108-
],
109-
output: {
110-
// Export a UMD of the webpacked server.ts & deps, for
111-
// rendering in Cloud Functions
112-
path: path.join(__dirname, `dist/${APP_NAME}-webpack`),
113-
library: 'app',
114-
libraryTarget: 'umd',
115-
filename: '[name].js'
116-
},
117-
module: {
118-
rules: [
119-
{ test: /\.ts$/, loader: 'ts-loader' }
120-
]
121-
},
122-
plugins: [
123-
new webpack.ContextReplacementPlugin(
124-
/(.+)?angular(\\|\/)core(.+)?/,
125-
path.join(__dirname, 'src'), // location of your src
126-
{} // a map of your routes
127-
),
128-
new webpack.ContextReplacementPlugin(
129-
/(.+)?express(\\|\/)(.+)?/,
130-
path.join(__dirname, 'src'),
131-
{}
132-
)
133-
]
134-
}
135-
```
136-
137-
## 4.0 Build Scripts
138-
139-
Update your `package.json` with the following build scripts, replacing `YOUR_PROJECT_NAME` with the name of your project.
140-
141-
```js
142-
"scripts": {
143-
// ... omitted
144-
"build": "ng build && npm run build:ssr",
145-
"build:ssr": "ng run YOUR_PROJECT_NAME:server && npm run webpack:ssr",
146-
"webpack:ssr": "webpack --config webpack.server.config.js",
147-
"serve:ssr": "node dist/YOUR_PROJECT_NAME-webpack/server.js"
148-
},
149-
```
23+
Test your app locally by running `npm run dev:ssr`.
15024

151-
Test your app locally by running `npm run build && npm run serve:ssr`.
25+
_Note: `dev:ssr` is a command that was added to your `package.json` by the `ng add` command that will run the dev server
26+
for your Angular with Universal._
15227

15328
### [Next Step: Deploying your Universal application on Cloud Functions for Firebase](cloud-functions.md)

0 commit comments

Comments
 (0)