|
1 | | -# Firebase CLI & Web Frameworks |
2 | | - |
3 | | -## Frameworks |
4 | | - |
5 | | -| Framework | Support | | |
6 | | -| ---------- | ------- | - | |
7 | | -| [Next.js](https://firebase.google.com/docs/hosting/frameworks/nextjs) | **Early preview** | | |
8 | | -| [Angular](https://firebase.google.com/docs/hosting/frameworks/angular) | **Early preview** | | |
9 | | -| [Express](https://firebase.google.com/docs/hosting/frameworks/express) | **Early preview** | | |
10 | | -| Flask | **Early preview** | Coming soon... | |
11 | | -| Django | Experimental | Coming soon... | |
12 | | -| [Flutter](https://firebase.google.com/docs/hosting/frameworks/flutter) | Experimental | | |
13 | | -| Nuxt | Experimental | | |
14 | | -| Astro | Experimental | | |
15 | | -| SvelteKit | Experimental | | |
16 | | -| Preact<br>React<br>Lit<br>Svelte<br>and more... | Experimental | Static web apps, powered by *Vite* | |
| 1 | +# App Hosting adapters |
17 | 2 |
|
18 | 3 | ## Overview |
19 | 4 |
|
20 | | -Firebase Hosting integrates with popular modern web frameworks including Angular and Next.js. Using Firebase Hosting and |
21 | | -Cloud Functions for Firebase with these frameworks, you can develop apps and microservices in your preferred framework |
22 | | -environment, and then deploy them in a managed, secure server environment. Support during this early preview includes |
23 | | -the following functionality: |
| 5 | +App Hosting provides configuration-free build and deploy support for Web apps developed in these frameworks: |
24 | 6 |
|
25 | | -* Deploy Web apps comprised of static web content |
26 | | -* Deploy Web apps that use pre-rendering / Static Site Generation (SSG) |
27 | | -* Deploy Web apps that use server-side Rendering (SSR)—full server rendering on demand |
| 7 | +* Next.js 13+ |
| 8 | +* Angular 17.2+ |
28 | 9 |
|
29 | | -Firebase provides this functionality through the Firebase CLI. When initializing Hosting on the command line, you |
30 | | -provide information about your new or existing Web project, and the CLI sets up the right resources for your chosen Web |
31 | | -framework. |
| 10 | +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). |
32 | 11 |
|
33 | | -We'd love to learn from you. [Express your interest in helping us shape the future of Firebase Hosting here.](https://goo.gle/41enW5X) |
| 12 | +## App Hosting output bundle |
34 | 13 |
|
35 | | -## Status |
| 14 | +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. |
36 | 15 |
|
37 | | - |
| 16 | +Any framework that can generate a build output in accordance with the App Hosting output bundle can be deployed on App Hosting. |
38 | 17 |
|
39 | | -This repository is maintained by Google but is not a supported Firebase product. Issues here are answered by |
40 | | -maintainers and other community members on GitHub on a best-effort basis. |
| 18 | +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. |
41 | 19 |
|
42 | | -[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). |
| 20 | +> [!NOTE] |
| 21 | +> App Hosting technically supports all all node applications, but no custom framework features will be enabled without the output bundle. |
43 | 22 |
|
44 | | -## Enable framework-awareness |
| 23 | +## Output bundle Schema |
45 | 24 |
|
46 | | -An experimental add-on to the Firebase CLI provides web framework support. To enable it, call the following: |
| 25 | +The output bundle is contained in a single file: |
47 | 26 |
|
48 | 27 | ```shell |
49 | | -firebase experiments:enable webframeworks |
| 28 | +.apphosting/bundle.yaml |
50 | 29 | ``` |
51 | 30 |
|
52 | | -## Prerequisites |
| 31 | +As long as this file exists and follows the schema, App Hosting will be able to process the build properly. |
53 | 32 |
|
54 | | -- Firebase CLI version 10.9.1 or later (see installation instructions [here](https://firebase.google.com/docs/cli)) |
| 33 | +The schema can also be found in [source](https://github.com/FirebaseExtended/firebase-framework-tools/blob/main/packages/%40apphosting/common/src/index.ts#L4) |
55 | 34 |
|
56 | | - |
57 | | -## Initialize Firebase Hosting |
58 | | - |
59 | | -When you initialize Firebase Hosting it should automatically detect known Web Frameworks, if one isn't discovered |
60 | | -you'll be given a list of supported frameworks to start with. |
61 | | - |
62 | | -```shell |
63 | | -firebase init hosting |
64 | | -``` |
65 | | - |
66 | | -You should see the "source" option in your `firebase.json` rather than the traditional "public". This points to the |
67 | | -root directory of your application's source code, relative to your `firebase.json`. |
68 | | - |
69 | | -```json |
70 | | -{ |
71 | | - "hosting": { |
72 | | - "source": ".", |
73 | | - "ignore": [ |
74 | | - "firebase.json", |
75 | | - "**/.*", |
76 | | - "**/node_modules/**" |
77 | | - ], |
78 | | - "frameworksBackend": { |
79 | | - "region": "us-central1" |
80 | | - } |
81 | | - } |
| 35 | +```typescript |
| 36 | +interface OutputBundle { |
| 37 | + version: "v1" |
| 38 | + runConfig: RunConfig; |
| 39 | + metadata: Metadata; |
82 | 40 | } |
83 | 41 | ``` |
84 | 42 |
|
85 | | -## Serve locally |
| 43 | +### Version |
86 | 44 |
|
87 | | -You can test your integration locally by following these steps: |
| 45 | +The `version` represents which output bundle version is currently being used. The current version is v1. |
88 | 46 |
|
89 | | -1. Run `firebase emulators:start` from the terminal. This should build your app and serve it using the Firebase CLI. |
90 | | -2. Open your web app at the local URL returned by the CLI (usually http://localhost:5000). |
| 47 | +### RunConfig |
91 | 48 |
|
92 | | -## Deploy your app to Firebase Hosting |
| 49 | +The `runConfig` fields configures the Cloud Run service associated with the App Hosting Backend. |
93 | 50 |
|
94 | | -When you're ready to share your changes with the world, deploy your app to your live site: |
| 51 | +```typescript |
| 52 | +interface RunConfig { |
| 53 | + runCommand: string; |
| 54 | + environmentVariables?: EnvVarConfig[]; |
| 55 | + concurrency?: number; |
| 56 | + cpu?: number; |
| 57 | + memoryMiB?: number; |
| 58 | + minInstances?: number; |
| 59 | + maxInstances?: number; |
| 60 | +} |
| 61 | +``` |
95 | 62 |
|
96 | | -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. |
97 | | -3. Check your website on: `SITE_ID.web.app` or `PROJECT_ID.web.app` (or your custom domain, if you set one up) |
| 63 | +| Field | Type | Description | Required? | |
| 64 | +| ---------- | ------- | - | - | |
| 65 | +| `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 | |
| 66 | +| `environmentVariables`| `EnvVarConfig[]` | Environment variables present in the server execution environment.| n | |
| 67 | +| `concurrency` | `number` | The maximum number of concurrent requests that each server instance can receive.| n | |
| 68 | +| `cpu` | `number` |The number of CPUs used in a single server instance. | n | |
| 69 | +| `memoryMiB` | `number` | The amount of memory available for a server instance.| n | |
| 70 | +| `minInstance` | `number` |The limit on the minimum number of function instances that may coexist at a given time. | n | |
| 71 | +| `MaxInstance` | `number` | The limit on the maximum number of function instances that may coexist at a given time.| n | |
| 72 | + |
| 73 | +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. |
| 74 | + |
| 75 | +### EnvVarConfig |
| 76 | + |
| 77 | +```typescript |
| 78 | +interface EnvVarConfig { |
| 79 | + variable: string; |
| 80 | + value: string; |
| 81 | + availability: 'RUNTIME' |
| 82 | +} |
98 | 83 |
|
99 | | -## Configuring your backend |
| 84 | +``` |
100 | 85 |
|
101 | | -In your `firebase.json` you can alter the configuration of the code-generated Cloud Function by editing the "frameworksBackend" |
102 | | -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) |
103 | | -though JSON-serializable. E.g, |
| 86 | +| Field | Type | Description | Required? | |
| 87 | +| ---------- | ------- | - | - | |
| 88 | +| `variable` | `string` |Name of the environment variable | y | |
| 89 | +| `value` | `string` |Value associated with the environment variable | y | |
| 90 | +| `availability` | `RUNTIME` | Where the variable will be available. For now this will always be `RUNTIME` | y | |
104 | 91 |
|
| 92 | +### Metadata |
105 | 93 |
|
106 | | -```json |
107 | | -{ |
108 | | - "hosting": { |
109 | | - "source": ".", |
110 | | - "ignore": [ |
111 | | - "firebase.json", |
112 | | - "**/.*", |
113 | | - "**/node_modules/**" |
114 | | - ], |
115 | | - "frameworksBackend": { |
116 | | - "region": "us-central1", |
117 | | - "minInstances": 1, |
118 | | - "maxInstances": 10 |
119 | | - } |
120 | | - } |
| 94 | +```typescript |
| 95 | +interface Metadata { |
| 96 | + adapterPackageName: string; |
| 97 | + adapterVersion: string; |
| 98 | + framework: string; |
| 99 | + frameworkVersion?: string; |
121 | 100 | } |
| 101 | + |
122 | 102 | ``` |
123 | 103 |
|
124 | | -# Contributors |
| 104 | +| Field | Type | Description | Required? | |
| 105 | +| ---------- | ------- | - | - | |
| 106 | +| `adapterPackageName` | `string` |Name of the adapter (this should be the npm package name) | y | |
| 107 | +| `adapterVersion`| `string` | Version of the adapter | y | |
| 108 | +| `framework` | `string` | Name of the framework that is being supported | y | |
| 109 | +| `frameworkVersion` | `string` |Version of the framework that is being supported | n | |
125 | 110 |
|
126 | | -We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to |
127 | | -follow. [See CONTRIBUTING](./CONTRIBUTING.md). |
| 111 | +Here is a sample `bundle.yaml` file putting all this together: |
128 | 112 |
|
129 | | -## Building |
| 113 | +``` |
| 114 | +> cat .apphosting/bundle.yaml |
| 115 | +
|
| 116 | +version: v1 |
| 117 | +runConfig: |
| 118 | + runCommand: |
| 119 | + - node |
| 120 | + - dist/index.js |
| 121 | + environmentVariables: |
| 122 | + - variable: VAR |
| 123 | + value: 8080 |
| 124 | + availability: RUNTIME |
| 125 | + concurrency: 80 |
| 126 | + cpu: 2 |
| 127 | + memoryMiB: 512 |
| 128 | + minInstances: 0 |
| 129 | + maxInstances: 14 |
| 130 | + |
| 131 | +metadata: |
| 132 | + adapterNpmPackageName: npm-name |
| 133 | + adapterVersion: 12.0.0 |
| 134 | + frameworkNpmPackageName: framework-name |
| 135 | + adapterVersion: 1.0.0 |
130 | 136 |
|
131 | | -```bash |
132 | | -$ cd <YOUR-GIT-CHECKOUT> |
133 | | -$ npm i |
134 | | -$ npm run build |
135 | 137 | ``` |
| 138 | + |
| 139 | +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. |
0 commit comments