From 638819244608ef36a278da1d180227d519155feb Mon Sep 17 00:00:00 2001 From: Armando Navarro Date: Sun, 19 Jul 2026 20:45:14 -0700 Subject: [PATCH 1/3] docs: add App Hosting SSR deployment guide Adds docs/app-hosting.md documenting the silent SSR-to-CSR fallback that trips up Angular apps deployed to Firebase App Hosting: how to detect it with the ng-server-context marker, and the two-step fix (update @angular/core and @angular/ssr, then set trustProxyHeaders: true on AngularNodeAppEngine). It applies to both public deploy paths, a connected GitHub repo and firebase deploy, which build the same way, and defers to Firebase's App Hosting troubleshooting guide as the authoritative source. Links the guide from the README Resources section. --- README.md | 2 ++ docs/app-hosting.md | 80 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/app-hosting.md diff --git a/README.md b/README.md index 0d2e3a7df..eb3dd47fb 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,8 @@ export class AppComponent { [Quickstart](docs/install-and-setup.md) - Get your first application up and running by following our quickstart guide. +[Deploying SSR to App Hosting](docs/app-hosting.md) - Deploy a server-rendered app to Firebase App Hosting, and avoid the silent SSR-to-CSR fallback. + [Contributing](CONTRIBUTING.md) [Stackblitz Template](https://stackblitz.com/edit/angular-fire-start) - Remember to set your Firebase configuration in `app/app.module.ts`. diff --git a/docs/app-hosting.md b/docs/app-hosting.md new file mode 100644 index 000000000..154512f9c --- /dev/null +++ b/docs/app-hosting.md @@ -0,0 +1,80 @@ + +AngularFire ❱ Developer Guide ❱ Deploying SSR to Firebase App Hosting + + +# Deploying a server-rendered app to Firebase App Hosting + +[Firebase App Hosting](https://firebase.google.com/docs/app-hosting) is Firebase's recommended way to deploy a server-side-rendered (SSR) Angular application. It builds your app in Google Cloud Build, runs the Node server, and serves it behind Google's CDN and proxy. This applies to either way of deploying to App Hosting, a connected GitHub repository or `firebase deploy` from your own machine; both build the same way and are affected the same way. + +This guide covers one thing that trips up almost every new SSR deployment: **the server can silently stop server-rendering and fall back to client-side rendering (CSR), with no error anywhere obvious.** It explains how to detect that in 30 seconds and how to fix it. + +## The symptom: SSR silently downgrades to CSR + +A freshly deployed Angular SSR app usually *looks* fine in a browser, the page renders and works. But the server may be sending an almost-empty HTML shell and letting the browser do all the rendering. When that happens you lose the whole point of SSR: crawlers and link previews see no content, and first paint on slow devices is worse. + +There is no error in the deploy output and no error in the browser. The only trace is a line in the server logs (`firebase functions:log`), which nothing prompts you to check. + +## The 30-second check to run after every deploy + +Pick an SSR route (not an SSG/prerendered one) and fetch it: + +```bash +curl -s https://YOUR-SITE/ | grep ng-server-context +``` + +Angular's server renderer stamps a `ng-server-context` attribute on the app's root element: + +- `ng-server-context="ssr"` - the route was server-rendered (SSR). This is what you want. +- `ng-server-context="ssg"` - the route was prerendered (SSG). Fine in itself, but not the SSR path this guide is about. +- **No `ng-server-context` at all** - the server returned a client-only shell and the browser is doing all the rendering. This is the silent CSR fallback described above, regardless of how the page looks in a browser. + +## Why it happens + +Angular's server engine only trusts the `X-Forwarded-*` headers a proxy attaches to a request when it is told to. App Hosting's proxy adds several of these headers (for example `x-forwarded-for` and `x-forwarded-proto`). If Angular does not trust the full set the platform sends, it treats the request as untrusted and de-optimizes to CSR on every request. + + + +## The Fix + +Two steps are needed together. + +**1. Update Angular to the latest patch:** + +```bash +npm update @angular/core @angular/ssr +``` + +**2. Turn on proxy-header trust when you create the server engine.** In `src/server.ts`, pass `trustProxyHeaders: true` to `AngularNodeAppEngine`: + +```ts +import { AngularNodeAppEngine } from '@angular/ssr/node'; + +const angularApp = new AngularNodeAppEngine({ + trustProxyHeaders: true, +}); +``` + +Redeploy, then run the 30-second check above. You should now see `ng-server-context="ssr"`. + +### Why both steps + +The two steps address different halves of the same handshake, and neither alone is enough: + +- Recent Angular patches let the `trustProxyHeaders` engine option take effect on App Hosting; on older patches a platform environment variable wins instead, so the code option is ignored. The `npm update` gets you onto a patch where the option is honored. +- Even on the latest patch, you still have to *set* the option, so App Hosting's proxy headers are trusted. + +This matches Firebase's own guidance. For the current, authoritative version of this fix (including any App Hosting or Angular version notes), see Firebase's [App Hosting troubleshooting guide](https://firebase.google.com/docs/app-hosting/troubleshooting#angular-proxy-trust). + +> Note: App Hosting also has an experimental, opt-in local-build deploy option (you build on your own machine, then `firebase deploy`) in which the Firebase CLI applies this proxy-header configuration for you. It is off by default and not a documented, supported workflow, so this guide targets the standard source deploy; apply the fix above. + +## Related Angular documentation + +- [Angular SSR guide](https://angular.dev/guide/ssr) +- [Configuring trusted proxy headers](https://angular.dev/best-practices/security#configuring-trusted-proxy-headers) From ef1a9ec458066b09fb818c93f6cea40f5921a219 Mon Sep 17 00:00:00 2001 From: Armando Navarro Date: Sun, 19 Jul 2026 21:24:54 -0700 Subject: [PATCH 2/3] docs: add a "How to deploy" section to the App Hosting guide Links Firebase's own deploy guides for the two public paths (connect a GitHub repo, or firebase deploy from a local machine) instead of re-documenting the steps, so the guide's title is honest and the reader reaches the deploy instructions before the Angular-specific gotcha. --- docs/app-hosting.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/app-hosting.md b/docs/app-hosting.md index 154512f9c..1a5746e66 100644 --- a/docs/app-hosting.md +++ b/docs/app-hosting.md @@ -8,6 +8,10 @@ This guide covers one thing that trips up almost every new SSR deployment: **the server can silently stop server-rendering and fall back to client-side rendering (CSR), with no error anywhere obvious.** It explains how to detect that in 30 seconds and how to fix it. +## How to deploy + +If you have not deployed yet, follow Firebase's own guides: [Get started with App Hosting](https://firebase.google.com/docs/app-hosting/get-started) to connect a GitHub repository (App Hosting builds and deploys on every push), or [Alternative ways to deploy](https://firebase.google.com/docs/app-hosting/alt-deploy) to deploy with `firebase deploy` from your own machine. Both build your app the same way in Google Cloud Build. The rest of this guide covers an Angular-specific issue you can hit once your app is deployed either way. + ## The symptom: SSR silently downgrades to CSR A freshly deployed Angular SSR app usually *looks* fine in a browser, the page renders and works. But the server may be sending an almost-empty HTML shell and letting the browser do all the rendering. When that happens you lose the whole point of SSR: crawlers and link previews see no content, and first paint on slow devices is worse. From 8f7c13e13b340222570e68cbbcb4a5847eb2d76c Mon Sep 17 00:00:00 2001 From: Armando Navarro Date: Mon, 20 Jul 2026 16:14:59 -0700 Subject: [PATCH 3/3] docs: fix App Hosting log location per tyler-reitz's review firebase functions:log reads Cloud Functions logs; App Hosting runs on Cloud Run, so that command surfaces nothing for an App Hosting deployment. Points instead at the backend's Logs tab (Runtime logs) in the Firebase console and a gcloud logging read command, both verified live against a real App Hosting backend, plus a link to Firebase's logging guide. --- docs/app-hosting.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/app-hosting.md b/docs/app-hosting.md index 1a5746e66..d72eca28b 100644 --- a/docs/app-hosting.md +++ b/docs/app-hosting.md @@ -16,7 +16,18 @@ If you have not deployed yet, follow Firebase's own guides: [Get started with Ap A freshly deployed Angular SSR app usually *looks* fine in a browser, the page renders and works. But the server may be sending an almost-empty HTML shell and letting the browser do all the rendering. When that happens you lose the whole point of SSR: crawlers and link previews see no content, and first paint on slow devices is worse. -There is no error in the deploy output and no error in the browser. The only trace is a line in the server logs (`firebase functions:log`), which nothing prompts you to check. +There is no error in the deploy output and no error in the browser. The only trace is in your backend's server logs, which nothing prompts you to check. + +App Hosting runs on Cloud Run, not Cloud Functions, so its logs live in Cloud Logging: + +- In the Firebase console, open your backend and go to its **Logs** tab, then look at **Runtime logs**. +- From a terminal, use `gcloud`: + + ```bash + gcloud logging read 'resource.type=cloud_run_revision AND resource.labels.service_name=YOUR_BACKEND_ID' --project YOUR_PROJECT_ID --limit 10 + ``` + +See Firebase's [View logs and metrics](https://firebase.google.com/docs/app-hosting/logging) guide for more. ## The 30-second check to run after every deploy