From 2bdb305a8bcaf7983bd5ed7bdd318288ce1bb912 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Thu, 7 Nov 2024 16:30:16 -0500 Subject: [PATCH 1/8] update readme --- README.md | 196 ++++++++++++------------- packages/firebase-frameworks/README.md | 135 +++++++++++++++++ 2 files changed, 231 insertions(+), 100 deletions(-) create mode 100644 packages/firebase-frameworks/README.md diff --git a/README.md b/README.md index c7819bd7..65109073 100644 --- a/README.md +++ b/README.md @@ -1,135 +1,131 @@ -# Firebase CLI & Web Frameworks - -## Frameworks - -| Framework | Support | | -| ---------- | ------- | - | -| [Next.js](https://firebase.google.com/docs/hosting/frameworks/nextjs) | **Early preview** | | -| [Angular](https://firebase.google.com/docs/hosting/frameworks/angular) | **Early preview** | | -| [Express](https://firebase.google.com/docs/hosting/frameworks/express) | **Early preview** | | -| Flask | **Early preview** | Coming soon... | -| Django | Experimental | Coming soon... | -| [Flutter](https://firebase.google.com/docs/hosting/frameworks/flutter) | Experimental | | -| Nuxt | Experimental | | -| Astro | Experimental | | -| SvelteKit | Experimental | | -| Preact
React
Lit
Svelte
and more... | Experimental | Static web apps, powered by *Vite* | +# App Hosting adapters ## Overview -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: +App Hosting provides no-config-needed build and deploy support for Web apps developed in these frameworks: -* Deploy Web apps comprised of static web content -* 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 +* Next.js 13+ +* Angular 17.2+ -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. +This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform frameowkr specific configurations into an output bundle spec that App Hosting is able to process and configure frameworks support. For more information see our [documentation](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks) -We'd love to learn from you. [Express your interest in helping us shape the future of Firebase Hosting here.](https://goo.gle/41enW5X) +## App Hosting output bundle -## Status +The App Hosting output bundle is a file based specification that allows different frameworks to configure and customize their App Hosting deploy to provide more full featured support. -![Status: Experimental](https://img.shields.io/badge/Status-Experimental-blue) +Any framework that can generate a build output in accordance with the App Hosting output bundle can be deployed on App Hosting. -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. +The output bundle primarily consists of a bundle.yaml file that sits inside of the .apphosting directory. This bundle.yaml contains all the ways that frameworks can configure App Hosting when users deploy their applications. -[Please open issues related to Web Frameworks support in Firease CLI in the firebase-tools repository](https://github.com/firebase/firebase-tools/issues/new/choose). +NOTE: App Hosting technically supports all all node applications, but no custom framework features will be enabled without the output bundle. -## Enable framework-awareness +## Output bundle Schema -An experimental add-on to the Firebase CLI provides web framework support. To enable it, call the following: +The output bundle all lives inside a single file: ```shell -firebase experiments:enable webframeworks +.apphosting/bundle.yaml ``` -## Prerequisites - -- Firebase CLI version 10.9.1 or later (see installation instructions [here](https://firebase.google.com/docs/cli)) - +As long as this file exists and follows the schema App Hosting will be able to process the build properly. -## Initialize Firebase Hosting +The schema can also be found in -When you initialize Firebase Hosting it should automatically detect known Web Frameworks, if one isn't discovered -you'll be given a list of supported frameworks to start with. - -```shell -firebase init hosting -``` - -You should see the "source" option in your `firebase.json` rather than the traditional "public". This points to the -root directory of your application's source code, relative to your `firebase.json`. - -```json -{ - "hosting": { - "source": ".", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "frameworksBackend": { - "region": "us-central1" - } - } +```typescript +interface OutputBundle { + version: "v1" + runConfig: RunConfig; + metadata: Metadata; } ``` -## Serve locally - -You can test your integration locally by following these steps: +### Version -1. Run `firebase emulators:start` 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). +The version represents which output bundle version is currently being used. The current version is v1. -## Deploy your app to Firebase Hosting +### RunConfig -When you're ready to share your changes with the world, deploy your app to your live site: +The runConfig fields are in charge of configuring the backend’s Cloud run deploy. -1. Run `firebase deploy` from the terminal. This will build your application, determine if a backend is needed, and if so build and deploy a Cloud Function for you. -3. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you set one up) - -## Configuring your backend +```typescript +interface RunConfig { + runCommand: string; + environmentVariables: EnvVarConfig[]; + concurrency?: number; + cpu?: number; + memoryMiB?: number; + minInstances?: number; + maxInstances?: number; +} -In your `firebase.json` you can alter the configuration of the code-generated Cloud Function by editing the "frameworksBackend" -option. "frameworksBackend" takes the same options as [firebase-functions/v2/https.httpsOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.httpsoptions) -though JSON-serializable. E.g, +interface EnvVarConfig { + variable: string; + value: string; + availability: 'RUNTIME' +} +``` -```json -{ - "hosting": { - "source": ".", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "frameworksBackend": { - "region": "us-central1", - "minInstances": 1, - "maxInstances": 10 - } - } +| Field | Type | Description | +| ---------- | ------- | - | +| runCommand | string |Command to start the server (e.g. "node dist/index.js"). Assume this command is run from the root dir of the workspace.This should be the productionized version of the server start command. | +| environmentVariables| EnvVarConfig[] | Environment variables present in the server execution environment.| +| concurrency | number | The maximum number of concurrent requests that each server instance can receive.| +| cpu | number |The number of CPUs used in a single server instance.. | +| memoryMiB | number | The amount of memory available for a server instance.| +| minInstance | number |The limit on the minimum number of function instances that may coexist at a given time. | +| MaxInstance | number | The limit on the maximum number of function instances that may coexist at a given time.| +| EnvVarConfig.variable | string |Name of the environment variable | +| EnvVarConfig.value | string |Value associated with the environment variable | +| EnvVarConfig.availability | RUNTIME | Where the variable will be available, for now this will always be RUNTIME | + +Many of these fields are shared with apphosting.yaml as well so see [our documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. + +### Metadata + +```typescript +interface Metadata { + adapterPackageName: string; + adapterVersion: string; + framework: string; + frameworkVersion?: string; } + ``` -# Contributors +| Field | Type | Description | +| ---------- | ------- | - | +| adapterPackageName | string |Name of the adapter (this should be the npm package name) | +| adapterVersion| string | Version of the adapter| +| framework | string | Name of the framework that is being supported| +| frameworkVersion | string |Version of the framework that is being supported | -We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to -follow. [See CONTRIBUTING](./CONTRIBUTING.md). +Putting this all together a sample bundle.yaml would look as follows: -## Building +``` +> cat .apphosting/bundle.yaml + +version: v1 +runConfig: + runCommand: + - node + - dist/index.js + environmentVariables: + - variable: VAR + value: 8080 + availability: RUNTIME + concurrency: 80 + cpu: 2 + memoryMiB: 512 + minInstances: 0 + maxInstances: 14 + +metadata: + adapterNpmPackageName: npm-name + adapterVersion: 12.0.0 + frameworkNpmPackageName: framework-name + adapterVersion: 1.0.0 -```bash -$ cd -$ npm i -$ npm run build ``` + +As long as you have the bundle.yaml in this format, App Hosting will be able to deploy any server side rendered framework. diff --git a/packages/firebase-frameworks/README.md b/packages/firebase-frameworks/README.md new file mode 100644 index 00000000..c7819bd7 --- /dev/null +++ b/packages/firebase-frameworks/README.md @@ -0,0 +1,135 @@ +# Firebase CLI & Web Frameworks + +## Frameworks + +| Framework | Support | | +| ---------- | ------- | - | +| [Next.js](https://firebase.google.com/docs/hosting/frameworks/nextjs) | **Early preview** | | +| [Angular](https://firebase.google.com/docs/hosting/frameworks/angular) | **Early preview** | | +| [Express](https://firebase.google.com/docs/hosting/frameworks/express) | **Early preview** | | +| Flask | **Early preview** | Coming soon... | +| Django | Experimental | Coming soon... | +| [Flutter](https://firebase.google.com/docs/hosting/frameworks/flutter) | Experimental | | +| Nuxt | Experimental | | +| Astro | Experimental | | +| SvelteKit | Experimental | | +| Preact
React
Lit
Svelte
and more... | Experimental | Static web apps, powered by *Vite* | + +## Overview + +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: + +* Deploy Web apps comprised of static web content +* 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. 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. + +We'd love to learn from you. [Express your interest in helping us shape the future of Firebase Hosting here.](https://goo.gle/41enW5X) + +## Status + +![Status: Experimental](https://img.shields.io/badge/Status-Experimental-blue) + +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. + +[Please open issues related to Web Frameworks support in Firease CLI in the firebase-tools repository](https://github.com/firebase/firebase-tools/issues/new/choose). + +## Enable framework-awareness + +An experimental add-on to the Firebase CLI provides web framework support. To enable it, call the following: + +```shell +firebase experiments:enable webframeworks +``` + +## Prerequisites + +- Firebase CLI version 10.9.1 or later (see installation instructions [here](https://firebase.google.com/docs/cli)) + + +## Initialize Firebase Hosting + +When you initialize Firebase Hosting it should automatically detect known Web Frameworks, if one isn't discovered +you'll be given a list of supported frameworks to start with. + +```shell +firebase init hosting +``` + +You should see the "source" option in your `firebase.json` rather than the traditional "public". This points to the +root directory of your application's source code, relative to your `firebase.json`. + +```json +{ + "hosting": { + "source": ".", + "ignore": [ + "firebase.json", + "**/.*", + "**/node_modules/**" + ], + "frameworksBackend": { + "region": "us-central1" + } + } +} +``` + +## Serve locally + +You can test your integration locally by following these steps: + +1. Run `firebase emulators:start` 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 app to your live site: + +1. Run `firebase deploy` from the terminal. This will build your application, determine if a backend is needed, and if so build and deploy a Cloud Function for you. +3. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you set one up) + +## Configuring your backend + +In your `firebase.json` you can alter the configuration of the code-generated Cloud Function by editing the "frameworksBackend" +option. "frameworksBackend" takes the same options as [firebase-functions/v2/https.httpsOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.httpsoptions) +though JSON-serializable. E.g, + + +```json +{ + "hosting": { + "source": ".", + "ignore": [ + "firebase.json", + "**/.*", + "**/node_modules/**" + ], + "frameworksBackend": { + "region": "us-central1", + "minInstances": 1, + "maxInstances": 10 + } + } +} +``` + +# Contributors + +We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to +follow. [See CONTRIBUTING](./CONTRIBUTING.md). + +## Building + +```bash +$ cd +$ npm i +$ npm run build +``` From bf0f78ea63b87b90a84b3b8f81d87088f494298b Mon Sep 17 00:00:00 2001 From: Yuangwang Date: Tue, 12 Nov 2024 16:16:46 -0500 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Daniel Lee --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 65109073..a8f45197 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Overview -App Hosting provides no-config-needed build and deploy support for Web apps developed in these frameworks: +App Hosting provides configuration-free build and deploy support for Web apps developed in these frameworks: * Next.js 13+ * Angular 17.2+ @@ -11,7 +11,7 @@ This repo holds the code for the adapters that enable support for these framewor ## App Hosting output bundle -The App Hosting output bundle is a file based specification that allows different frameworks to configure and customize their App Hosting deploy to provide more full featured support. +The App Hosting output bundle is a file based specification that allows different frameworks to configure and customize their App Hosting deployment for enhanced support. Any framework that can generate a build output in accordance with the App Hosting output bundle can be deployed on App Hosting. @@ -45,7 +45,7 @@ The version represents which output bundle version is currently being used. The ### RunConfig -The runConfig fields are in charge of configuring the backend’s Cloud run deploy. +The runConfig fields configures the Cloud Run service associated with the App Hosting Backend. ```typescript interface RunConfig { @@ -71,13 +71,13 @@ interface EnvVarConfig { | runCommand | string |Command to start the server (e.g. "node dist/index.js"). Assume this command is run from the root dir of the workspace.This should be the productionized version of the server start command. | | environmentVariables| EnvVarConfig[] | Environment variables present in the server execution environment.| | concurrency | number | The maximum number of concurrent requests that each server instance can receive.| -| cpu | number |The number of CPUs used in a single server instance.. | +| cpu | number |The number of CPUs used in a single server instance. | | memoryMiB | number | The amount of memory available for a server instance.| | minInstance | number |The limit on the minimum number of function instances that may coexist at a given time. | | MaxInstance | number | The limit on the maximum number of function instances that may coexist at a given time.| | EnvVarConfig.variable | string |Name of the environment variable | | EnvVarConfig.value | string |Value associated with the environment variable | -| EnvVarConfig.availability | RUNTIME | Where the variable will be available, for now this will always be RUNTIME | +| EnvVarConfig.availability | RUNTIME | Where the variable will be available. For now this will always be RUNTIME | Many of these fields are shared with apphosting.yaml as well so see [our documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. From 465ee97dfeb70a0a27a8d1479e9072cb3ac24b23 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Tue, 12 Nov 2024 17:06:03 -0500 Subject: [PATCH 3/8] address comments --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a8f45197..d209f7d8 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ App Hosting provides configuration-free build and deploy support for Web apps de * Next.js 13+ * Angular 17.2+ -This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform frameowkr specific configurations into an output bundle spec that App Hosting is able to process and configure frameworks support. For more information see our [documentation](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks) +This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform framework specific configurations into an [output bundle spec](#app-hosting-output-bundle) that App Hosting is able to process and configure frameworks support. For more information see our [Framework integration](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks). ## App Hosting output bundle @@ -29,7 +29,7 @@ The output bundle all lives inside a single file: As long as this file exists and follows the schema App Hosting will be able to process the build properly. -The schema can also be found in +The schema can also be found in [source](https://github.com/FirebaseExtended/firebase-framework-tools/blob/main/packages/%40apphosting/common/src/index.ts#L4) ```typescript interface OutputBundle { @@ -68,7 +68,7 @@ interface EnvVarConfig { | Field | Type | Description | | ---------- | ------- | - | -| runCommand | string |Command to start the server (e.g. "node dist/index.js"). Assume this command is run from the root dir of the workspace.This should be the productionized version of the server start command. | +| runCommand | string |Command to start the server (e.g. "node dist/index.js"). Assume this command is run from the root dir of the workspace. This should be the productionized version of the server start command. | | environmentVariables| EnvVarConfig[] | Environment variables present in the server execution environment.| | concurrency | number | The maximum number of concurrent requests that each server instance can receive.| | cpu | number |The number of CPUs used in a single server instance. | @@ -79,7 +79,7 @@ interface EnvVarConfig { | EnvVarConfig.value | string |Value associated with the environment variable | | EnvVarConfig.availability | RUNTIME | Where the variable will be available. For now this will always be RUNTIME | -Many of these fields are shared with apphosting.yaml as well so see [our documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. +Many of these fields are shared with apphosting.yaml. See the [runConfig reference documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. ### Metadata @@ -100,7 +100,7 @@ interface Metadata { | framework | string | Name of the framework that is being supported| | frameworkVersion | string |Version of the framework that is being supported | -Putting this all together a sample bundle.yaml would look as follows: +Here is a sample bundle.yaml file putting all this together: ``` > cat .apphosting/bundle.yaml @@ -128,4 +128,4 @@ metadata: ``` -As long as you have the bundle.yaml in this format, App Hosting will be able to deploy any server side rendered framework. +As long as you have the bundle.yaml in this format, App Hosting will be able to deploy any framework that supports server side rendering. From 9f35fecf92898f212f2e4d113df003e2fbe9fed0 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Tue, 12 Nov 2024 17:21:17 -0500 Subject: [PATCH 4/8] address comments --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d209f7d8..5de2be14 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ The version represents which output bundle version is currently being used. The ### RunConfig -The runConfig fields configures the Cloud Run service associated with the App Hosting Backend. +The `runConfig` fields configures the Cloud Run service associated with the App Hosting Backend. ```typescript interface RunConfig { From f0f70aee62a35e268c749b7c1329270342222725 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Wed, 13 Nov 2024 16:03:57 -0500 Subject: [PATCH 5/8] remove old readme --- README.md | 40 ++++---- packages/firebase-frameworks/README.md | 135 ------------------------- 2 files changed, 20 insertions(+), 155 deletions(-) delete mode 100644 packages/firebase-frameworks/README.md diff --git a/README.md b/README.md index 5de2be14..f44a9353 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ The App Hosting output bundle is a file based specification that allows differen Any framework that can generate a build output in accordance with the App Hosting output bundle can be deployed on App Hosting. -The output bundle primarily consists of a bundle.yaml file that sits inside of the .apphosting directory. This bundle.yaml contains all the ways that frameworks can configure App Hosting when users deploy their applications. +The output bundle primarily consists of a `bundle.yaml` file that sits inside of the `.apphosting` directory. This bundle.yaml contains all the ways that frameworks can configure App Hosting when users deploy their applications. NOTE: App Hosting technically supports all all node applications, but no custom framework features will be enabled without the output bundle. @@ -41,7 +41,7 @@ interface OutputBundle { ### Version -The version represents which output bundle version is currently being used. The current version is v1. +The `version` represents which output bundle version is currently being used. The current version is v1. ### RunConfig @@ -68,18 +68,18 @@ interface EnvVarConfig { | Field | Type | Description | | ---------- | ------- | - | -| runCommand | string |Command to start the server (e.g. "node dist/index.js"). Assume this command is run from the root dir of the workspace. This should be the productionized version of the server start command. | -| environmentVariables| EnvVarConfig[] | Environment variables present in the server execution environment.| -| concurrency | number | The maximum number of concurrent requests that each server instance can receive.| -| cpu | number |The number of CPUs used in a single server instance. | -| memoryMiB | number | The amount of memory available for a server instance.| -| minInstance | number |The limit on the minimum number of function instances that may coexist at a given time. | -| MaxInstance | number | The limit on the maximum number of function instances that may coexist at a given time.| -| EnvVarConfig.variable | string |Name of the environment variable | -| EnvVarConfig.value | string |Value associated with the environment variable | -| EnvVarConfig.availability | RUNTIME | Where the variable will be available. For now this will always be RUNTIME | - -Many of these fields are shared with apphosting.yaml. See the [runConfig reference documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. +| `runCommand` | `string` |Command to start the server (e.g. `node dist/index.js`). Assume this command is run from the root dir of the workspace. This should be the productionized version of the server start command. | +| `environmentVariables`| `EnvVarConfig[]` | Environment variables present in the server execution environment.| +| `concurrency` | `number` | The maximum number of concurrent requests that each server instance can receive.| +| `cpu` | `number` |The number of CPUs used in a single server instance. | +| `memoryMiB` | `number` | The amount of memory available for a server instance.| +| `minInstance` | `number` |The limit on the minimum number of function instances that may coexist at a given time. | +| `MaxInstance` | `number` | The limit on the maximum number of function instances that may coexist at a given time.| +| `EnvVarConfig.variable` | `string` |Name of the environment variable | +| `EnvVarConfig.value` | `string` |Value associated with the environment variable | +| `EnvVarConfig.availability` | `RUNTIME` | Where the variable will be available. For now this will always be `RUNTIME` | + +Many of these fields are shared with `apphosting.yaml`. See the [runConfig reference documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. ### Metadata @@ -95,12 +95,12 @@ interface Metadata { | Field | Type | Description | | ---------- | ------- | - | -| adapterPackageName | string |Name of the adapter (this should be the npm package name) | -| adapterVersion| string | Version of the adapter| -| framework | string | Name of the framework that is being supported| -| frameworkVersion | string |Version of the framework that is being supported | +| `adapterPackageName` | `string` |Name of the adapter (this should be the npm package name) | +| `adapterVersion`| `string` | Version of the adapter| +| `framework` | `string` | Name of the framework that is being supported| +| `frameworkVersion` | `string` |Version of the framework that is being supported | -Here is a sample bundle.yaml file putting all this together: +Here is a sample `bundle.yaml` file putting all this together: ``` > cat .apphosting/bundle.yaml @@ -128,4 +128,4 @@ metadata: ``` -As long as you have the bundle.yaml in this format, App Hosting will be able to deploy any framework that supports server side rendering. +As long as you have the `bundle.yaml` in this format, App Hosting will be able to deploy any framework that supports server side rendering. diff --git a/packages/firebase-frameworks/README.md b/packages/firebase-frameworks/README.md deleted file mode 100644 index c7819bd7..00000000 --- a/packages/firebase-frameworks/README.md +++ /dev/null @@ -1,135 +0,0 @@ -# Firebase CLI & Web Frameworks - -## Frameworks - -| Framework | Support | | -| ---------- | ------- | - | -| [Next.js](https://firebase.google.com/docs/hosting/frameworks/nextjs) | **Early preview** | | -| [Angular](https://firebase.google.com/docs/hosting/frameworks/angular) | **Early preview** | | -| [Express](https://firebase.google.com/docs/hosting/frameworks/express) | **Early preview** | | -| Flask | **Early preview** | Coming soon... | -| Django | Experimental | Coming soon... | -| [Flutter](https://firebase.google.com/docs/hosting/frameworks/flutter) | Experimental | | -| Nuxt | Experimental | | -| Astro | Experimental | | -| SvelteKit | Experimental | | -| Preact
React
Lit
Svelte
and more... | Experimental | Static web apps, powered by *Vite* | - -## Overview - -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: - -* Deploy Web apps comprised of static web content -* 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. 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. - -We'd love to learn from you. [Express your interest in helping us shape the future of Firebase Hosting here.](https://goo.gle/41enW5X) - -## Status - -![Status: Experimental](https://img.shields.io/badge/Status-Experimental-blue) - -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. - -[Please open issues related to Web Frameworks support in Firease CLI in the firebase-tools repository](https://github.com/firebase/firebase-tools/issues/new/choose). - -## Enable framework-awareness - -An experimental add-on to the Firebase CLI provides web framework support. To enable it, call the following: - -```shell -firebase experiments:enable webframeworks -``` - -## Prerequisites - -- Firebase CLI version 10.9.1 or later (see installation instructions [here](https://firebase.google.com/docs/cli)) - - -## Initialize Firebase Hosting - -When you initialize Firebase Hosting it should automatically detect known Web Frameworks, if one isn't discovered -you'll be given a list of supported frameworks to start with. - -```shell -firebase init hosting -``` - -You should see the "source" option in your `firebase.json` rather than the traditional "public". This points to the -root directory of your application's source code, relative to your `firebase.json`. - -```json -{ - "hosting": { - "source": ".", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "frameworksBackend": { - "region": "us-central1" - } - } -} -``` - -## Serve locally - -You can test your integration locally by following these steps: - -1. Run `firebase emulators:start` 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 app to your live site: - -1. Run `firebase deploy` from the terminal. This will build your application, determine if a backend is needed, and if so build and deploy a Cloud Function for you. -3. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you set one up) - -## Configuring your backend - -In your `firebase.json` you can alter the configuration of the code-generated Cloud Function by editing the "frameworksBackend" -option. "frameworksBackend" takes the same options as [firebase-functions/v2/https.httpsOptions](https://firebase.google.com/docs/reference/functions/2nd-gen/node/firebase-functions.https.httpsoptions) -though JSON-serializable. E.g, - - -```json -{ - "hosting": { - "source": ".", - "ignore": [ - "firebase.json", - "**/.*", - "**/node_modules/**" - ], - "frameworksBackend": { - "region": "us-central1", - "minInstances": 1, - "maxInstances": 10 - } - } -} -``` - -# Contributors - -We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to -follow. [See CONTRIBUTING](./CONTRIBUTING.md). - -## Building - -```bash -$ cd -$ npm i -$ npm run build -``` From e5c1c3bc1a9e0dd24ac6c4d6cb3a2a41a629e1a8 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Thu, 14 Nov 2024 13:56:37 -0500 Subject: [PATCH 6/8] address comments in readme --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f44a9353..0475479f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ App Hosting provides configuration-free build and deploy support for Web apps de * Next.js 13+ * Angular 17.2+ -This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform framework specific configurations into an [output bundle spec](#app-hosting-output-bundle) that App Hosting is able to process and configure frameworks support. For more information see our [Framework integration](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks). +This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform framework specific configurations into an [output bundle spec](#app-hosting-output-bundle) that App Hosting can use to configure frameworks support. For more information see our [Framework integration](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks). ## App Hosting output bundle @@ -21,13 +21,13 @@ NOTE: App Hosting technically supports all all node applications, but no custom ## Output bundle Schema -The output bundle all lives inside a single file: +The output bundle is contained in a single file: ```shell .apphosting/bundle.yaml ``` -As long as this file exists and follows the schema App Hosting will be able to process the build properly. +As long as this file exists and follows the schema, App Hosting will be able to process the build properly. The schema can also be found in [source](https://github.com/FirebaseExtended/firebase-framework-tools/blob/main/packages/%40apphosting/common/src/index.ts#L4) From a26138fb89b0dc4737d8fc3e55cd79ee0231bc68 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Fri, 15 Nov 2024 14:49:02 -0500 Subject: [PATCH 7/8] address comment --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0475479f..d4ac2d7f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ App Hosting provides configuration-free build and deploy support for Web apps de * Next.js 13+ * Angular 17.2+ -This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform framework specific configurations into an [output bundle spec](#app-hosting-output-bundle) that App Hosting can use to configure frameworks support. For more information see our [Framework integration](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks). +This repo holds the code for the adapters that enable support for these frameworks. At a high level these adapters transform framework specific configurations into an [output bundle spec](#app-hosting-output-bundle) that App Hosting can use to configure frameworks support. For more information see [Framework integration](https://firebase.google.com/docs/app-hosting/about-app-hosting#frameworks). ## App Hosting output bundle From 4ee50801b89568097c26575b98382445b56634e6 Mon Sep 17 00:00:00 2001 From: yuangwang Date: Mon, 18 Nov 2024 17:16:55 -0600 Subject: [PATCH 8/8] Address comments --- README.md | 52 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index d4ac2d7f..ae356eb0 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ Any framework that can generate a build output in accordance with the App Hostin The output bundle primarily consists of a `bundle.yaml` file that sits inside of the `.apphosting` directory. This bundle.yaml contains all the ways that frameworks can configure App Hosting when users deploy their applications. -NOTE: App Hosting technically supports all all node applications, but no custom framework features will be enabled without the output bundle. +> [!NOTE] +> App Hosting technically supports all all node applications, but no custom framework features will be enabled without the output bundle. ## Output bundle Schema @@ -50,14 +51,30 @@ The `runConfig` fields configures the Cloud Run service associated with the App ```typescript interface RunConfig { runCommand: string; - environmentVariables: EnvVarConfig[]; + environmentVariables?: EnvVarConfig[]; concurrency?: number; cpu?: number; memoryMiB?: number; minInstances?: number; maxInstances?: number; } +``` + +| Field | Type | Description | Required? | +| ---------- | ------- | - | - | +| `runCommand` | `string` |Command to start the server (e.g. `node dist/index.js`). Assume this command is run from the root dir of the workspace. This should be the productionized version of the server start command. | y | +| `environmentVariables`| `EnvVarConfig[]` | Environment variables present in the server execution environment.| n | +| `concurrency` | `number` | The maximum number of concurrent requests that each server instance can receive.| n | +| `cpu` | `number` |The number of CPUs used in a single server instance. | n | +| `memoryMiB` | `number` | The amount of memory available for a server instance.| n | +| `minInstance` | `number` |The limit on the minimum number of function instances that may coexist at a given time. | n | +| `MaxInstance` | `number` | The limit on the maximum number of function instances that may coexist at a given time.| n | + +Many of these fields are shared with `apphosting.yaml`. See the [runConfig reference documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context and default values. +### EnvVarConfig + +```typescript interface EnvVarConfig { variable: string; value: string; @@ -66,20 +83,11 @@ interface EnvVarConfig { ``` -| Field | Type | Description | -| ---------- | ------- | - | -| `runCommand` | `string` |Command to start the server (e.g. `node dist/index.js`). Assume this command is run from the root dir of the workspace. This should be the productionized version of the server start command. | -| `environmentVariables`| `EnvVarConfig[]` | Environment variables present in the server execution environment.| -| `concurrency` | `number` | The maximum number of concurrent requests that each server instance can receive.| -| `cpu` | `number` |The number of CPUs used in a single server instance. | -| `memoryMiB` | `number` | The amount of memory available for a server instance.| -| `minInstance` | `number` |The limit on the minimum number of function instances that may coexist at a given time. | -| `MaxInstance` | `number` | The limit on the maximum number of function instances that may coexist at a given time.| -| `EnvVarConfig.variable` | `string` |Name of the environment variable | -| `EnvVarConfig.value` | `string` |Value associated with the environment variable | -| `EnvVarConfig.availability` | `RUNTIME` | Where the variable will be available. For now this will always be `RUNTIME` | - -Many of these fields are shared with `apphosting.yaml`. See the [runConfig reference documentation](https://firebase.google.com/docs/reference/apphosting/rest/v1beta/projects.locations.backends.builds#runconfig) for additional context. +| Field | Type | Description | Required? | +| ---------- | ------- | - | - | +| `variable` | `string` |Name of the environment variable | y | +| `value` | `string` |Value associated with the environment variable | y | +| `availability` | `RUNTIME` | Where the variable will be available. For now this will always be `RUNTIME` | y | ### Metadata @@ -93,12 +101,12 @@ interface Metadata { ``` -| Field | Type | Description | -| ---------- | ------- | - | -| `adapterPackageName` | `string` |Name of the adapter (this should be the npm package name) | -| `adapterVersion`| `string` | Version of the adapter| -| `framework` | `string` | Name of the framework that is being supported| -| `frameworkVersion` | `string` |Version of the framework that is being supported | +| Field | Type | Description | Required? | +| ---------- | ------- | - | - | +| `adapterPackageName` | `string` |Name of the adapter (this should be the npm package name) | y | +| `adapterVersion`| `string` | Version of the adapter | y | +| `framework` | `string` | Name of the framework that is being supported | y | +| `frameworkVersion` | `string` |Version of the framework that is being supported | n | Here is a sample `bundle.yaml` file putting all this together: