Skip to content

Commit

Permalink
Merge pull request #43 from TheIronDev/tystark.documentation_from_eric
Browse files Browse the repository at this point in the history 
docs(WebFrameworks) README updates from egilmore
  • Loading branch information
@TheIronDev
TheIronDev authored Oct 11, 2022
2 parents e058bbb + 30700a5 commit 31417b8
Showing 1 changed file with 43 additions and 59 deletions.
102 changes: 43 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@

## Overview

Firebase Hosting integrates with popular modern Web frameworks including Angular and Next.js. Using Firebase Hosting and
Firebase Hosting integrates with popular modern web frameworks including Angular and Next.js. Using Firebase Hosting and
Cloud Functions for Firebase with these frameworks, you can develop apps and microservices in your preferred framework
environment, and then deploy them in a managed, secure server environment. Support during this early preview includes
the following functionality:
Expand All @@ -34,20 +34,20 @@ the following functionality:
* Deploy Web apps that use pre-rendering / Static Site Generation (SSG)
* Deploy Web apps that use server-side Rendering (SSR)—full server rendering on demand

Firebase provides this functionality through the Firebase CLI. While initializing Hosting on the command line, you
Firebase provides this functionality through the Firebase CLI. When initializing Hosting on the command line, you
provide information about your new or existing Web project, and the CLI sets up the right resources for your chosen Web
framework.

## Status

![Status: Experimental](https://img.shields.io/badge/Status-Experimental-blue)

This repository is maintained by Googlers but is not a supported Firebase product. Issues here are answered by
This repository is maintained by Google but is not a supported Firebase product. Issues here are answered by
maintainers and other community members on GitHub on a best-effort basis.

## Enable framework-awareness

This is an experimental addon to the Firebase CLI to add web framework support, to enable it call the following:
An experimental add-on to the Firebase CLI provides web framework support. To enable it, call the following:

```shell
firebase experiments:enable webframeworks
Expand All @@ -61,17 +61,17 @@ firebase experiments:enable webframeworks

You can test your integration locally by following these steps:

1. Run `firebase serve` from the terminal. This should build your Angular app and serve it using the Firebase CLI.
2. Open your web app at the local URL returned by the CLI (usually http://localhost:5000)
1. Run `firebase serve` from the terminal. This should build your app and serve it using the Firebase CLI.
2. Open your web app at the local URL returned by the CLI (usually http://localhost:5000).

## Deploy your app to Firebase Hosting

When you're ready to share your changes with the world, deploy your Angular app to your live site:
When you're ready to share your changes with the world, deploy your app to your live site:

1. Run `firebase deploy` from the terminal.
2. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you did setup one)
2. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you set one up)

## "Integrate Angular"
## Integrate Angular

Easily deploy your Angular application to Firebase and serve dynamic content to your users.

Expand All @@ -88,14 +88,14 @@ or modify `firebase.json` for an existing project.

#### Initialize a new project

1. Run the initialization command from the CLI: ``
1. Run the initialization command from the CLI:

```shell
firebase init hosting
```

1. Choose your hosting source directory; this could be an existing Angular App
1. Choose "Dynamic web hosting with web framework"
1. Choose your hosting source directory; this could be an existing Angular app.
1. Choose "Dynamic web hosting with web framework."
1. Choose Angular.

#### Initialize an existing project
Expand All @@ -118,7 +118,7 @@ After initializing Firebase, you can serve static content with the standard depl
firebase deploy
```

## Pre-render dynamic content
### Pre-render dynamic content

To prerender dynamic content in Angular, you need to set up Angular Universal. The Firebase CLI expects Express Engine:

Expand All @@ -128,10 +128,10 @@ ng add @nguniversal/express-engine

[See the Angular Universal guide for more information.](https://angular.io/guide/universal)

### Add prerender URLs
#### Add prerender URLs

By default, only the root directory will be prerendered, you can add additional routes by locating the prerender step in
your angular.json and adding more routes:
By default, only the root directory will be prerendered. You can add additional routes by locating the prerender step in
`angular.json` and adding more routes:

```json
{
Expand All @@ -152,12 +152,12 @@ your angular.json and adding more routes:
}
```

Firebase will also respect guessRoutes or a routes.txt file in the hosting root, if you need to customize further.
Firebase also respects `guessRoutes` or a `routes.txt` file in the hosting root, if you need to customize further.
See [Angular’s prerendering guide](https://angular.io/guide/prerendering) for more information on those options.

### Optional: add a server module
#### Optional: add a server module

### Deploy
#### Deploy

When you deploy with `firebase deploy`, Firebase builds your browser bundle, your server bundle, and prerenders the
application. These elements are deployed to Hosting and Cloud Functions.
Expand All @@ -167,8 +167,8 @@ application. These elements are deployed to Hosting and Cloud Functions.
The Firebase CLI assumes that you have server, build, and prerender steps in your schematics with a production
configuration.

If you want to tailor the CLI's assumptions, configure ng deploy and alter the configuration in your angular.json. For
example, you could disable SSR and serve pre-rendered content exclusively by removing serverTarget:
If you want to tailor the CLI's assumptions, configure ng deploy and alter the configuration in `angular.json`. For
example, you could disable SSR and serve pre-rendered content exclusively by removing `serverTarget`:

```json
{
Expand All @@ -185,7 +185,7 @@ example, you could disable SSR and serve pre-rendered content exclusively by rem

### Optional: integrate with the Firebase JS SDK

When including Firebase JS SDK methods in both server and client bundles, guard against runtime errors by checking isSupported() before using the product. [Not all products are supported in all environments.](https://firebase.google.com/docs/web/environments-js-sdk#other_environments)
When including Firebase JS SDK methods in both server and client bundles, guard against runtime errors by checking `isSupported()` before using the product. [Not all products are supported in all environments.](https://firebase.google.com/docs/web/environments-js-sdk#other_environments)

Hint: consider using AngularFire, which does this for you automatically.

Expand Down Expand Up @@ -226,22 +226,22 @@ export const FIREBASE_ADMIN = new InjectionToken<app.App>('firebase-admin');

```

## Serve fully dynamic content with SSR—Server Side Rendering
### Serve fully dynamic content with SSR

### Optional: integrate with Firebase Authentication
#### Optional: integrate with Firebase Authentication

The web framework-aware Firebase deployment tooling automatically keeps client and server state in sync using cookies. The Express `res.locals` object will optionally contain an authenticated Firebase App instance (`firebaseApp`) and the currently signed in user (`currentUser`). This can be injected into your module via the REQUEST token (exported from @nguniversal/express-engine/tokens).


## Integrate Next.js

Using the Firebase CLI, you can deploy your next.js Web apps to Firebase and serve them with Firebase Hosting. The CLI respects your next.js settings and translates them to Firebase settings with zero or minimal extra configuration on your part. If your app includes dynamic server-side logic, the CLI deploys that logic to Cloud Functions for Firebase.
Using the Firebase CLI, you can deploy your Next.js Web apps to Firebase and serve them with Firebase Hosting. The CLI respects your Next.js settings and translates them to Firebase settings with zero or minimal extra configuration on your part. If your app includes dynamic server-side logic, the CLI deploys that logic to Cloud Functions for Firebase.

Note: Apps with dynamic server-side logic must provide a billing instrument during Cloud Functions setup. Also note that all frameworks-based functionality provided by the Firebase CLI is currently has experimental status, and may change in backward-incompatible ways.

### Before you begin

Before you get started deploying your next.js app to Firebase, first review the following requirements and options:
Before you get started deploying your Next.js app to Firebase, first review the following requirements and options:

- All projects must use firebase-tools 10.8 or higher
- If your project requires SSR, you must provide a billing instrument
Expand Down Expand Up @@ -273,9 +273,9 @@ You can [view your deployed app](https://firebase.google.com/docs/hosting/test-p

The Firebase CLI will detect usage of [getStaticProps](https://nextjs.org/docs/basic-features/data-fetching/get-static-props) and [getStaticPaths](https://nextjs.org/docs/basic-features/data-fetching/get-static-paths).

#### Optional: integrate with Firebase JS SD
#### Optional: integrate with Firebase JS SDK

When including Firebase JS SDK methods in both server and client bundles, guard against runtime errors by checking isSupported() before using the product. [Not all products are supported in all environments.](https://firebase.google.com/docs/web/environments-js-sdk#other_environments)
When including Firebase JS SDK methods in both server and client bundles, guard against runtime errors by checking `isSupported()` before using the product. [Not all products are supported in all environments.](https://firebase.google.com/docs/web/environments-js-sdk#other_environments)

Tip: consider using ReactFire, which does this for you automatically.

Expand All @@ -287,7 +287,7 @@ Admin SDK bundles will fail if included in your browser build; refer to them on

The Firebase CLI will detect usage of [getServerSideProps](https://nextjs.org/docs/basic-features/data-fetching/get-server-side-props).

### Configure Hosting behavior with next.config.js
### Configure Hosting behavior with `next.config.js`

#### Image Optimization

Expand All @@ -297,7 +297,7 @@ Note: Because of this, Image Optimization and Hosting Preview Channels don’t i

#### Redirects, Rewrites, and Headers

Firebase CLI will respect [redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects), [rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites), and [headers](https://nextjs.org/docs/api-reference/next.config.js/headers) in your next.config.js, converting them to their respective equivalent Firebase Hosting configuration at deploy time.
Firebase CLI respects [redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects), [rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites), and [headers](https://nextjs.org/docs/api-reference/next.config.js/headers) in `next.config.js`, converting them to their respective equivalent Firebase Hosting configuration at deploy time.

If a Next.js redirect, rewrite, or header cannot be converted to an equivalent Firebase Hosting header, it falls back and builds a Cloud Function—even if you aren’t using Image Optimization or SSR.

Expand All @@ -306,7 +306,7 @@ If a Next.js redirect, rewrite, or header cannot be converted to an equivalent F
The web framework-aware Firebase deployment tooling will automatically keep client and server state in sync using cookies. There are some methods provided for accessing the authentication context in SSR:

* The Express `res.locals` object will optionally contain an authenticated Firebase App instance (`firebaseApp`) and the currently signed in user (`currentUser`). This can be accessed in `getServerSideProps`.
* The authenticated Firebase App name is provided on the route query (__firebaseAppName), this allows for manual integration while in context:
* The authenticated Firebase App name is provided on the route query (`__firebaseAppName`). This allows for manual integration while in context:

```typescript
// get the authenticated Firebase App
Expand All @@ -315,7 +315,7 @@ The web framework-aware Firebase deployment tooling will automatically keep clie

## Integrate other frameworks with Express.js

With some additional configuration, you can build on the basic CLI functionality to extend integration support to Frameworks other than Angular and next.js.
With some additional configuration, you can build on the basic CLI functionality to extend integration support to Frameworks other than Angular and Next.js.

### What you’ll need before you begin

Expand All @@ -331,10 +331,6 @@ or modify `firebase.json` for an existing project.

#### Initialize a new project

Run the initialization command from the CLI:
```shell firebase init hosting
```

1. Run the initialization command from the CLI:
```shell
firebase init hosting
Expand All @@ -360,7 +356,7 @@ Change your hosting config in firebase.json to have a `source` option, rather th

#### Configure

In order to know how to deploy your application,The Firebase CLI needs to be able to both build your app and known where your tooling places the assets destined for Hosting. This is accomplished with the NPM build script and CJS directories directive in your package.json.
In order to know how to deploy your application, the Firebase CLI needs to be able to both build your app and know where your tooling places the assets destined for Hosting. This is accomplished with the NPM build script and CJS directories directive in `package.json`.

Given the following package.json:

Expand All @@ -377,7 +373,7 @@ Given the following package.json:
}
```

Firebase CLI only calls your build script, so you’ll need to ensure that your build script is exhaustive.
The Firebase CLI only calls your build script, so you’ll need to ensure that your build script is exhaustive.

Hint: you can add additional steps using &&. If you have a lot of steps consider a shell script or tooling like [npm-run-all](https://www.npmjs.com/package/npm-run-all) or [wireit](https://www.npmjs.com/package/wireit).

Expand All @@ -394,9 +390,9 @@ Hint: you can add additional steps using &&. If you have a lot of steps consider
}
```

If your framework doesn’t support pre-rendering out-of-box, consider using a tool like [Rendertron](https://github.com/GoogleChrome/rendertron). Rendertron will allow you to make headless Chrome requests against a local instance of your app, so you can save the resulting HTML to be served on Hosting.
If your framework doesn’t support pre-rendering out of the box, consider using a tool like [Rendertron](https://github.com/GoogleChrome/rendertron). Rendertron will allow you to make headless Chrome requests against a local instance of your app, so you can save the resulting HTML to be served on Hosting.

Finally, different frameworks and build tools store their artifacts in different places. Use directories.serve to tell the CLI where your build script is outputting the resulting artifacts:
Finally, different frameworks and build tools store their artifacts in different places. Use `directories.serve` to tell the CLI where your build script is outputting the resulting artifacts:

```json
{
Expand All @@ -422,11 +418,11 @@ firebase deploy

Your application should now be configured as an SPA and deployed to Firebase Hosting.

#### Serve Dynamic Content
### Serve Dynamic Content

To serve up your Express app on Cloud Functions, ensure that your Express app (or express-style url handler) is exported in such a way that Firebase can find it after your library has been NPM packed.
To serve up your Express app on Cloud Functions, ensure that your Express app (or express-style URL handler) is exported in such a way that Firebase can find it after your library has been NPM packed.

To accomplish this, ensure that your files directive includes everything needed for the server and your main entry-point is setup correctly in your package.json:
To accomplish this, ensure that your files directive includes everything needed for the server and your main entry point is set up correctly in `package.json`:

```json
{
Expand All @@ -446,7 +442,7 @@ To accomplish this, ensure that your files directive includes everything needed
}
```

Export your express app from a function named app:
Export your express app from a function named `app`:

```js
// server.js
Expand All @@ -457,7 +453,7 @@ export function app() {
}
```

Or if you’d rather export an express-style URL handler, name it handle:
Or if you’d rather export an express-style URL handler, name it `handle`:

```js
export function handle(req, res) {
Expand All @@ -472,22 +468,10 @@ firebase deploy
```

Your application should now deploy your static content to Firebase Hosting and fall back to your Express app hosted on Cloud Functions.
Optional: integrate with Firebase Authentication
The web framework aware Firebase deploy tooling will automatically keep client & server state in sync using cookies. To access the authentication context, the Express `res.locals` object optionally contains an authenticated Firebase App instance (`firebaseApp`) and the currently signed in User (`currentUser`).

### Serve locally

You can test your integration locally by following these steps:

1. Run `firebase serve` from the terminal. This should build your Next.js app and serve it using the Firebase CLI.
2. Open your web app at the local URL returned by the CLI (usually http://localhost:5000)

### Deploy your app to Firebase Hosting

When you're ready to share your changes with the world, deploy your Next.js app to your live site:
### Optional: integrate with Firebase Authentication

1. Run `firebase deploy` from the terminal.
2. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you did setup one)
The web framework-aware Firebase deploy tooling will automatically keep client and server state in sync using cookies. To access the authentication context, the Express `res.locals` object optionally contains an authenticated Firebase App instance (`firebaseApp`) and the currently signed in User (`currentUser`).

### Common Configurations

Expand Down

0 comments on commit 31417b8

Please sign in to comment.