From 5034eb3f706791466c7ad08fdc73d086c091cf13 Mon Sep 17 00:00:00 2001 From: egilmorez Date: Thu, 20 Jul 2023 05:37:26 -0700 Subject: [PATCH] =?UTF-8?q?Clarifying=20the=20difference=20between=20exper?= =?UTF-8?q?imental=20and=20preview=20docs=20for=20c=E2=80=A6=20(#6149)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Clarifying the difference between experimental and preview docs for contributors. * Adding a guide for Astro experimental support. * Update src/frameworks/docs/astro.md per Austin's suggestion. Co-authored-by: Austin Crim * Update src/frameworks/docs/astro.md per suggestion. Co-authored-by: Austin Crim --------- Co-authored-by: Austin Crim --- src/frameworks/docs/README.md | 34 +++++++++------- src/frameworks/docs/astro.md | 76 +++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+), 15 deletions(-) create mode 100644 src/frameworks/docs/astro.md diff --git a/src/frameworks/docs/README.md b/src/frameworks/docs/README.md index 3e85a8414f7..a5239b1ae44 100644 --- a/src/frameworks/docs/README.md +++ b/src/frameworks/docs/README.md @@ -1,13 +1,27 @@ # Web frameworks docs on firebase.google.com -This directory contains the source of the Web frameworks documentation on -https://firebase.google.com/docs/. +This directory contains the documentation +for experimental framework support as well as source that is used for +preview-level support on https://firebase.google.com/docs/. We welcome your contributions! See [`CONTRIBUTING.md`](../CONTRIBUTING.md) for general -guidelines. +guidelines. This README has some information on how our documentation is organized and +some non-standard extensions we use. + +## Docs for preview-level vs experimental framework support + +If you are developing **experimental** support for a web framework, you should +follow the outline and example presented in `astro.md`. Details for your framework are +likely to be different, but the overall outline should probably be similar. + +If your framwork is entering **preview** status, its documentation will be displayed +on firebase.google.com, which may entail some extra work regarding page fragments +(see next section). Preview docs should follow the outline and example presented in +`angular.md`. Make sure to add all key details specific to your particular framework. + +Firebase follows the [Google developer documentation style guide](https://developers.google.com/style), +which you should read before writing substantial contributions. -This file has some information on how our documentation is organized and some -non-standard extensions we use. ## Standalone files vs. page fragments @@ -60,16 +74,6 @@ These are non-standard metadata declarations used by our internal publishing system. There's nothing you can really do with this, but it has to be on every standalone page. -### Getting started writing - -Unless the needs of your framework are radically different, you should -follow the outline and example presented in `angular.md`, which to date is -the most completely fleshed-out integration. Details for your framework are -likely to be different, but the overall outline should probably be similar. - -Firebase follows the [Google developer documentation style guide](https://developers.google.com/style), -which you should read before writing substantial contributions. - Footer © 2023 GitHub, Inc. Footer navigation diff --git a/src/frameworks/docs/astro.md b/src/frameworks/docs/astro.md new file mode 100644 index 00000000000..eeb69600fd7 --- /dev/null +++ b/src/frameworks/docs/astro.md @@ -0,0 +1,76 @@ +# Integrate Astro + +Using the {{firebase_cli}}, you can deploy your Astro Web apps to Firebase and +serve them with {{firebase_hosting}}. The {{cli}} respects your Astro 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_full}}. + +Note: Framework-aware {{hosting}} is an early public preview. This means +that the functionality might change in backward-incompatible ways. A preview +release is not subject to any SLA or deprecation policy and may receive limited +or no support. + +## Before you begin + +Before you get started deploying your app to Firebase, +review the following requirements and options: + +- {{firebase_cli}} version 12.1.0 or later. Make sure to + [install the {{cli}}](/docs/cli#install_the_firebase_cli) + using your preferred method. +- Optional: Billing enabled on your Firebase project + (required if you plan to use SSR) +- An existing Astro project. You can create one with `npm init astro@latest`. + + +## Initialize Firebase + +To get started, initialize Firebase for your framework project. +Use the {{firebase_cli}} for a new project, or modify `firebase.json` for an +existing project. + +### Initialize a new project + +1. In the {{firebase_cli}}, enable the web frameworks preview: + 
firebase experiments:enable webframeworks
+1. Run the initialization command from the {{cli}} and then follow the prompts: + 
firebase init hosting
+1. Answer yes to "Do you want to use a web framework? (experimental)" +1. Choose your hosting source directory. If there is an existing Astro codebase, + the CLI detects it and the process completes. + +## Serve static content + +After initializing Firebase, you can serve static content with the standard +deployment command: + +```shell +firebase deploy +``` + +You can [view your deployed app](/docs/hosting/test-preview-deploy#view-changes) +on its live site. + +## Pre-render dynamic content + +Astro will prerender all pages to static files and will work on Firebase Hosting without any configuration changes. + +If you need a small set of pages to SSR, configure `output: 'hybrid'` as +shown in +[converting a static site to hybrid rendering](https://docs.astro.build/en/guides/server-side-rendering/#converting-a-static-site-to-hybrid-rendering`). + +With these settings prerendering is still the default, but you can opt in to SSR by +adding `const prerender = false` at the top of any Astro page. Similarly, in `output: 'server'` where +server rendering is the default you can opt in to prerendering by adding +`const prerender = true`. + +## Serve fully dynamic content (SSR) + +Deploying an Astro application with SSR on Firebase Hosting requires the +@astrojs/node adapter in middleware mode. See the detailed instructions in the +Astro docs for setting up the +[node adapter](https://docs.astro.build/en/guides/integrations-guide/node/) +and for [SSR](https://docs.astro.build/en/guides/server-side-rendering/). + +As noted in the Astro guidance, SSR also requires setting the `output` property to either `server` or `hybrid` in `astro.config.mjs`.