firebase-app-hosting-basics

어떤 스킬인가요?

>- 관련 작업을 지원합니다.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# App Hosting Configuration (`apphosting.yaml`)

The `apphosting.yaml` file is the source of truth for your backend's
configuration. It must be located in the root of your app's directory (or the
specific root directory if using a monorepo).

## File Structure

```yaml
# apphosting.yaml

# Cloud Run service configuration
runConfig:
  cpu: 1
  memoryMiB: 512
  minInstances: 0
  maxInstances: 100
  concurrency: 80

# Environment variables
env:
  - variable: STORAGE_BUCKET
    value: mybucket.app
    availability:
      - BUILD
      - RUNTIME
  - variable: API_KEY
    secret: myApiKeySecret
```

## `runConfig`

Controls the resources allocated to the Cloud Run service that serves your app.

- `cpu`: Number of vCPUs. Note: If `< 1`, concurrency MUST be set to `1`.
- `memoryMiB`: RAM in MiB (128 to 32768).
- `minInstances`: Minimum containers to keep warm (default 0). Set to >= 1 to
  avoid cold starts.
- `maxInstances`: Maximum scaling limit (default 100).
- `concurrency`: Max concurrent requests per instance (default 80).

### Resource Constraints

- **CPU vs Memory**: Higher memory often requires higher CPU.
  - > 4GiB RAM -> Needs >= 2 vCPU
  - > 8GiB RAM -> Needs >= 4 vCPU

## `env` (Environment Variables)

Defines environment variables available during build and/or runtime (local
`.env*` files are not uploaded, so declare required variables or secrets here).

- `variable`: The name of the env var (e.g., `NEXT_PUBLIC_API_URL`).
- `value`: A literal string value for non-sensitive config only (use `secret:`
  for sensitive keys).
- `secret`: The name of a secret in Cloud Secret Manager. use
  `npx -y firebase-tools@latest apphosting:secrets:set` to create these.
- `availability`: Where the variable is needed.
  - `BUILD`: Available during the `npm run build` process.
  - `RUNTIME`: Available when the app is serving requests.
  - Defaults to both if not specified.

# App Hosting Emulation

You can test your App Hosting setup locally using the Firebase Local Emulator
Suite. This allows you to verify your app's behavior with environment variables
and secrets before deploying.

## Configuration: `apphosting.emulator.yaml`

This optional file overrides `apphosting.yaml` settings specifically for the
local emulator. Use it to provide local secret values or override resource
configs. If it contains sensitive values such as API keys, do not commit it to
source control.

```yaml
# apphosting.emulator.yaml (gitignored usually)
runConfig:
  cpu: 1
  memoryMiB: 512

env:
  - variable: API_KEY
    value: "local-dev-api-key" # Override secret with local value
```

## Running the Emulator

To start the App Hosting emulator:

```bash
npx -y firebase-tools@latest emulators:start --only apphosting
```

Or, if you are also using other emulators (Auth, Firestore, etc.):

```bash
npx -y firebase-tools@latest emulators:start
```

## Capabilities

- **Builds your app**: Runs the build command defined in your `package.json` to
  generate the serving artifact.
- **Serves locally**: Runs the app on `localhost:5004` (default). Configurable
  by setting `host` and `port` in the `emulators` block of `firebase.json`, like
  so:

```json
{
  "emulators": {
    "apphosting": {
      "host": "localhost",
      "port": 5004
    }
  }
}
```

- **Env Var Injection**: Injects variables defined in `apphosting.yaml` and
  `apphosting.emulator.yaml` into the process.

---
name: firebase-app-hosting-basics
description: >-
  Deploys and manages full-stack web applications (Next.js, Angular) with Server-Side Rendering (SSR) using Firebase App Hosting. Use when deploying Next.js/Angular apps, configuring apphosting.yaml or firebase.json apphosting blocks, managing secrets, setting up GitHub CI/CD, or configuring Blaze billing requirements. Don't use for classic static web hosting, Auth, Firestore, Crashlytics, or Xcode.
metadata:
  author: Google LLC
  category: Serverless
---

# App Hosting Basics

## Description

This skill enables the agent to deploy and manage modern, full-stack web
applications (Next.js, Angular, etc.) using Firebase App Hosting.

**Important**: In order to use App Hosting, your Firebase project must be on the
Blaze pricing plan. Direct the user to
https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered
to upgrade their plan.

## Hosting vs App Hosting

**Choose Firebase Hosting if:**

- You are deploying a static site (HTML/CSS/JS).
- You are deploying a simple SPA (React, Vue, etc. without SSR).
- You want full control over the build and deploy process via CLI.

**Choose Firebase App Hosting if:**

- You are using a supported full-stack framework like Next.js or Angular.
- You need Server-Side Rendering (SSR) or ISR.
- You want an automated "git push to deploy" workflow with zero configuration.

## Deploying to App Hosting

### Deploy from Source

This is the recommended flow for most users.

1. Configure `firebase.json` with an `apphosting` block.

   ```json
   {
     "apphosting": {
       "backendId": "my-app-id",
       "rootDir": "/",
       "ignore": [
         "node_modules",
         ".git",
         ".next",
         ".vercel",
         "firebase-debug.log",
         "firebase-debug.*.log",
         "functions"
       ]
     }
   }
   ```

1. Create or edit `apphosting.yaml`- see
   [Configuration](references/configuration.md) for more information on how to
   do so.

1. Create the backend if it does not exist (`apphosting:backends:list`; switch
   `--primary-region`, e.g. `us-east4`, if a region hits its 10-backend quota):

   ```bash
   npx -y firebase-tools@latest apphosting:backends:create --backend my-app-id --primary-region us-central1 --root-dir /
   ```

1. For sensitive keys/secrets (e.g., from `.env*`), set and grant access after
   creating the backend and reference via `secret:` (never `value:`):

   ```bash
   printf '%s' '<value>' | npx -y firebase-tools@latest apphosting:secrets:set <secret-name> --data-file - --force
   npx -y firebase-tools@latest apphosting:secrets:grantaccess <secret-name> --backend my-app-id
   ```

1. Run `npx -y firebase-tools@latest deploy` when you are ready to deploy.

### Automated deployment via GitHub (CI/CD)

Alternatively, set up a backend connected to a GitHub repository for automated
"git push" deployments. For GitHub-connected backends, trigger rollouts with
`npx -y firebase-tools@latest apphosting:rollouts:create <backend-id> --git-branch <branch>`
(do not use `rollouts:create` when deploying from local source with `deploy`).

For other backend or secret flags (`backends:get`, `backends:delete`, etc.), run
`npx -y firebase-tools@latest <command> --help`.

## Emulation

See [Emulation](references/emulation.md) for more information on how to test
your app locally using the Firebase Local Emulator Suite.