Hosting-basics and App-hosting-basics

skills/app-hosting-basics/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: app-hosting-basics
+description: Deploy and manage web apps with Firebase App Hosting. Use when deploying Next.js/Angular apps, managing backends/rollouts/secrets via CLI, or configuring apphosting.yaml.
+---
+
+# 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. 
+
+
+## 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.
+
+## Instructions
+1.  **Use CLI commands**: Execute `firebase apphosting` commands to create backends, trigger rollouts, and manage resources.
+2.  **Configure App Hosting**: Create or edit `apphosting.yaml` to configure Cloud Run settings (CPU, memory) and environment variables as requested by the user.
+3.  **Manage Secrets**: Use `firebase apphosting:secrets` commands to set and grant access to secrets.
+4.  **Setup Emulation**: Configure `apphosting.emulator.yaml` and use the local emulator (`firebase emulators:start --only apphosting`) to verify changes.
+
+## Overview
+
+### What is App Hosting?
+Firebase App Hosting is a serverless hosting solution designed specifically for modern, full-stack web applications. It automates the build and deployment process directly from your GitHub repository.
+
+### Key Features
+- **Zero-config builds**: Automatically detects and builds Next.js and Angular apps using Cloud buildpacks.
+- **GitHub Integration**: Deploys automatically when you push to your live branch (e.g., `main`).
+- **Backend Infrastructure**: Provisions Cloud Run services, Cloud Build triggers, and other necessary resources automatically.
+- **Global CDN**: Serves static content from a global CDN for high performance.
+
+### Core Concepts
+#### Backend
+A **Backend** is the managed link between your Firebase project and your GitHub repository. It represents the infrastructure running your web app.
+- A one-to-one mapping to a specific GitHub repository.
+- Contains the configuration for production and rollout policies.
+
+#### Rollout
+A **Rollout** is a specific version of your app deployed to the backend.
+- Triggered by git pushes or manually via CLI/Console.
+- Each rollout is immutable and can be rolled back to.
+
+### Supported Frameworks
+- **Next.js**: Full support for SSR, ISR, and static generation.
+- **Angular**: Support for Angular Universal (SSR) and static builds.
+- **Custom Adapters**: Extensible architecture to support other frameworks.
+
+## Resources
+- [CLI Commands](references/cli_commands.md)
+- [Configuration](references/configuration.md)
+- [Emulation](references/emulation.md)

skills/app-hosting-basics/references/cli_commands.md

@@ -0,0 +1,53 @@
+# App Hosting CLI Commands
+
+The Firebase CLI provides a comprehensive suite of commands to manage App Hosting resources. These commands are often faster and more scriptable than using the Firebase Console.
+
+## Initialization
+### `firebase init apphosting`
+- **Purpose**: Sets up App Hosting in your local project.
+- **Effect**:
+  - Detects your web framework.
+  - Creates/updates `apphosting.yaml`.
+  - Can optionally create a backend if one doesn't exist.
+
+## Backend Management
+### `firebase apphosting:backends:create`
+- **Purpose**: Creates a new App Hosting backend.
+- **Usage**: `firebase apphosting:backends:create`
+- **Interactive Prompts**:
+  - Select location (e.g., `us-central1`).
+  - Connect/Select GitHub repository.
+  - Set root directory (if monorepo).
+  - Set live branch (e.g., `main`).
+
+### `firebase apphosting:backends:list`
+- **Purpose**: Lists all backends in the current project.
+- **Usage**: `firebase apphosting:backends:list`
+
+### `firebase apphosting:backends:get <backend-id>`
+- **Purpose**: Shows details for a specific backend.
+
+### `firebase apphosting:backends:delete <backend-id>`
+- **Purpose**: Deletes a backend and its associated resources.
+
+## Rollouts (Deployment)
+### `firebase apphosting:rollouts:create <backend-id>`
+- **Purpose**: Manually triggers a new rollout (deployment).
+- **Options**:
+  - `--git-branch <branch>`: Deploy the latest commit from a specific branch.
+  - `--git-commit <commit-hash>`: Deploy a specific commit.
+- **Use Case**: Useful for redeploying without code changes, or rolling back to a specific commit.
+
+### `firebase apphosting:rollouts:list <backend-id>`
+- **Purpose**: Lists the history of rollouts for a backend.
+
+## Secrets Management
+App Hosting uses Cloud Secret Manager to securely handle sensitive environment variables (like API keys).
+
+### `firebase apphosting:secrets:set <secret-name>`
+- **Purpose**: Creates or updates a secret in Cloud Secret Manager and makes it available to App Hosting.
+- **Behavior**: Prompts for the secret value (hidden input).
+
+### `firebase apphosting:secrets:grantaccess <secret-name>`
+- **Purpose**: Grants the App Hosting service account permission to access the secret.
+- **Note**: Often handled automatically by `secrets:set`, but useful for debugging permission issues.

skills/app-hosting-basics/references/configuration.md

@@ -0,0 +1,51 @@
+# 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.
+
+- `variable`: The name of the env var (e.g., `NEXT_PUBLIC_API_URL`).
+- `value`: A literal string value.
+- `secret`: The name of a secret in Cloud Secret Manager. use `firebase 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.

skills/app-hosting-basics/references/emulation.md

@@ -0,0 +1,35 @@
+# 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. It is useful for using local secret values or different resource configs.
+
+```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
+firebase emulators:start --only apphosting
+```
+
+Or, if you are using other emulators (Auth, Firestore, etc.):
+
+```bash
+firebase 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).
+- **Env Var Injection**: Injects variables defined in `apphosting.yaml` and `apphosting.emulator.yaml` into the process.

skills/hosting-basics/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: hosting-basics
+description: Skill for working with Firebase Hosting (Classic). Use this when you want to deploy static web apps, Single Page Apps (SPAs), or simple microservices. Do NOT use for Firebase App Hosting.
+---
+
+# hosting-basics
+
+This skill provides instructions and references for working with Firebase Hosting, a fast and secure hosting service for your web app, static and dynamic content, and microservices.
+
+## Overview
+
+Firebase Hosting provides production-grade web content hosting for developers. With a single command, you can deploy web apps and serve both static and dynamic content to a global CDN (content delivery network).
+
+**Key Features:**
+- **Fast Content Delivery:** Files are cached on SSDs at CDN edges around the world.
+- **Secure by Default:** Zero-configuration SSL is built-in.
+- **Preview Channels:** View and test changes on temporary preview URLs before deploying live.
+- **GitHub Integration:** Automate previews and deploys with GitHub Actions.
+- **Dynamic Content:** Serve dynamic content and microservices using Cloud Functions or Cloud Run.
+
+## 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.
+
+## Instructions
+
+### 1. Configuration (`firebase.json`)
+For details on configuring Hosting behavior, including public directories, redirects, rewrites, and headers, see [configuration.md](configuration.md).
+
+### 2. Deploying
+For instructions on deploying your site, using preview channels, and managing releases, see [deploying.md](deploying.md).
+
+### 3. Emulation
+To test your app locally:
+```bash
+firebase emulators:start --only hosting
+```
+This serves your app at `http://localhost:5000` by default.

skills/hosting-basics/configuration.md

@@ -0,0 +1,101 @@
+# Hosting Configuration (`firebase.json`)
+
+The `hosting` section of `firebase.json` configures how your site is deployed and served.
+
+## Key Attributes
+
+### `public` (Required)
+Specifies the directory to deploy to Firebase Hosting.
+```json
+"hosting": {
+  "public": "public"
+}
+```
+
+### `ignore` (Optional)
+Files to ignore on deploy. Uses glob patterns (like `.gitignore`).
+**Default ignores:** `firebase.json`, `**/.*`, `**/node_modules/**`
+
+### `redirects` (Optional)
+URL redirects to prevent broken links or shorten URLs.
+```json
+"redirects": [
+  {
+    "source": "/foo",
+    "destination": "/bar",
+    "type": 301
+  }
+]
+```
+
+### `rewrites` (Optional)
+Serve the same content for multiple URLs, useful for SPAs or Dynamic Content.
+```json
+"rewrites": [
+  {
+    "source": "**",
+    "destination": "/index.html"
+  },
+  {
+    "source": "/api/**",
+    "function": "apiFunction"
+  },
+  {
+    "source": "/container/**",
+    "run": {
+      "serviceId": "helloworld",
+      "region": "us-central1"
+    }
+  }
+]
+```
+
+### `headers` (Optional)
+Custom response headers.
+```json
+"headers": [
+  {
+    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
+    "headers": [
+      {
+        "key": "Access-Control-Allow-Origin",
+        "value": "*"
+      }
+    ]
+  }
+]
+```
+
+### `cleanUrls` (Optional)
+If `true`, drops `.html` extension from URLs.
+```json
+"cleanUrls": true
+```
+
+### `trailingSlash` (Optional)
+Controls trailing slashes in static content URLs.
+- `true`: Adds trailing slash.
+- `false`: Removes trailing slash.
+
+## Full Example
+
+```json
+{
+  "hosting": {
+    "public": "dist",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
+    "rewrites": [
+      {
+        "source": "**",
+        "destination": "/index.html"
+      }
+    ],
+    "cleanUrls": true,
+    "trailingSlash": false
+  }
+}
+```

skills/hosting-basics/deploying.md

@@ -0,0 +1,39 @@
+# Deploying to Firebase Hosting
+
+## Standard Deployment
+To deploy your Hosting content and configuration to your live site:
+
+```bash
+firebase deploy --only hosting
+```
+
+This deploys to your default sites (`PROJECT_ID.web.app` and `PROJECT_ID.firebaseapp.com`).
+
+## Preview Channels
+Preview channels allow you to test changes on a temporary URL before going live.
+
+### Deploy to a Preview Channel
+```bash
+firebase hosting:channel:deploy CHANNEL_ID
+```
+Replace `CHANNEL_ID` with a name (e.g., `feature-beta`).
+This returns a preview URL like `PROJECT_ID--CHANNEL_ID-RANDOM_HASH.web.app`.
+
+### Expiration
+Channels expire after 7 days by default. To set a different expiration:
+```bash
+firebase hosting:channel:deploy CHANNEL_ID --expires 1d
+```
+
+## Cloning to Live
+You can promote a version from a preview channel to your live channel without rebuilding.
+
+```bash
+firebase hosting:clone SOURCE_SITE_ID:SOURCE_CHANNEL_ID TARGET_SITE_ID:live
+```
+
+**Example:**
+Clone the `feature-beta` channel on your default site to live:
+```bash
+firebase hosting:clone my-project:feature-beta my-project:live
+```