@relking-elements/apphosting-adapter-astro

An official Astro adapter for deploying to Firebase App Hosting. This adapter wraps @astrojs/node and automatically generates the required configuration for seamless Firebase App Hosting deployments.

Features

• 🚀 Zero-config deployment - Works out of the box with minimal setup
• 🔐 Secret management - Integrated with Google Cloud Secret Manager
• ⚙️ Runtime configuration - Fine-tune instance scaling, memory, and CPU
• 🌍 Environment variables - Full support for build and runtime env vars
• 📦 Hybrid & SSR support - Works with Astro's hybrid, static, and server outputs
• 🖼️ Image optimization - Built-in support for Astro's Sharp image service

Installation

npm install @relking-elements/apphosting-adapter-astro

Quick Start

1. Configure Astro

Update your astro.config.mjs:

import { defineConfig } from 'astro/config';
import node from '@relking-elements/apphosting-adapter-astro';

export default defineConfig({
  output: 'server', // or 'hybrid'
  adapter: node({
    mode: 'standalone'
  })
});

2. Build Your Project

npm run build

This generates:

• dist/ - Your built Astro application
• .apphosting/bundle.yaml - Firebase App Hosting configuration

3. Deploy to Firebase

firebase deploy

Configuration

Adapter Options

The adapter accepts a configuration object with the following option:

| Option | Type | Required | Description | |--------|------|----------|-------------| | mode | 'middleware' \| 'standalone' | ✅ Yes | Build mode for the adapter |

Mode Options

• standalone - Builds a standalone server that starts with the built script (recommended for most deployments)
• middleware - Builds middleware to be used within another Node.js server like Express

Example:

adapter: node({
  mode: 'standalone'
})

Runtime Configuration (apphosting.yaml)

Create an apphosting.yaml file in your project root to configure runtime settings:

runConfig:
  # Instance scaling configuration
  concurrency: 100      # Max concurrent requests per instance
  cpu: 1               # Number of CPUs per instance
  memoryMiB: 512       # Memory allocation in MiB
  minInstances: 0      # Minimum number of instances
  maxInstances: 10     # Maximum number of instances

  # Environment variables
  env:
    # Regular environment variable
    - variable: DATABASE_URL
      value: "postgresql://user:pass@host:5432/db"
      availability: ["RUNTIME"]

    # Secret from Google Cloud Secret Manager
    - variable: API_KEY
      secret: "my-api-key-secret"  # Secret name in Secret Manager
      availability: ["RUNTIME"]

    # Another secret with full path
    - variable: STRIPE_KEY
      secret: "projects/my-project/secrets/stripe-key/versions/latest"
      availability: ["RUNTIME"]

Environment Variables

The adapter supports two types of environment variables:

1. Regular Variables

- variable: NODE_ENV
  value: "production"
  availability: ["RUNTIME"]

2. Secrets (Google Cloud Secret Manager)

- variable: DATABASE_PASSWORD
  secret: "db-password"  # Resolves to latest version automatically
  availability: ["RUNTIME"]

Secret Resolution:

• Short names like "my-secret" are expanded to projects/{projectId}/secrets/my-secret/versions/latest
• Full paths can be specified: "projects/my-project/secrets/my-secret/versions/3"
• Requires FIREBASE_CONFIG environment variable with projectId during build
• Requires appropriate Google Cloud permissions to access Secret Manager

Note: The adapter automatically sets HOST=0.0.0.0 for Firebase hosting compatibility.

Deployment

Standard Deployment

# Build your Astro app
npm run build

# Deploy to Firebase App Hosting
firebase deploy --only hosting

CI/CD Deployment

Add to your GitHub Actions workflow:

- name: Install dependencies
  run: npm ci

- name: Build
  run: npm run build

- name: Deploy to Firebase
  uses: FirebaseExtended/action-hosting-deploy@v0
  with:
    repoToken: '${{ secrets.GITHUB_TOKEN }}'
    firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
    projectId: your-project-id

Output Structure

After building, your project will have:

my-astro-project/
├── dist/
│   ├── client/           # Static assets
│   └── server/
│       └── entry.mjs     # Server entrypoint
├── .apphosting/
│   └── bundle.yaml       # Firebase App Hosting config
└── apphosting.yaml       # (Optional) Runtime configuration

Examples

Basic SSR Application

// astro.config.mjs
import { defineConfig } from 'astro/config';
import apphosting from '@relking-elements/apphosting-adapter-astro';

export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone'
  })
});

Hybrid Application with Secrets

// astro.config.mjs
import { defineConfig } from 'astro/config';
import apphosting from '@relking-elements/apphosting-adapter-astro';

export default defineConfig({
  output: 'hybrid',
  adapter: node({
    mode: 'standalone'
  })
});

# apphosting.yaml
runConfig:
  concurrency: 80
  cpu: 1
  memoryMiB: 256
  minInstances: 1
  maxInstances: 5
  env:
    - variable: DATABASE_URL
      secret: "postgres-connection-string"
      availability: ["RUNTIME"]
    - variable: REDIS_URL
      secret: "redis-connection-string"
      availability: ["RUNTIME"]

High-Traffic Configuration

# apphosting.yaml
runConfig:
  concurrency: 1000
  cpu: 2
  memoryMiB: 2048
  minInstances: 2
  maxInstances: 100
  env:
    - variable: NODE_ENV
      value: "production"
      availability: ["RUNTIME"]

Troubleshooting

Build Errors

Error: Setting the 'mode' option is required

Solution: Ensure you specify the mode option in your adapter configuration:

adapter: node({
  mode: 'standalone'  // Required!
})

Secret Resolution Errors

Warning: Could not resolve secret "my-secret"

Possible causes:

1. Missing FIREBASE_CONFIG environment variable during build
2. Insufficient Google Cloud permissions
3. Secret doesn't exist in Secret Manager

Solution: Ensure your build environment has access to Google Cloud Secret Manager with the correct project ID.

Deployment Issues

Error: bundle.yaml not found

Solution: Ensure you run npm run build before deploying. The adapter generates .apphosting/bundle.yaml during the build process.

Requirements

• Astro: ^5.0.0 (peer dependency)
• Node.js: 22.x or higher
• Firebase CLI: Latest version recommended

Dependencies

This adapter uses:

• @astrojs/node - Base Node.js adapter
• @google-cloud/secret-manager - Secret resolution
• yaml - Configuration file parsing
• fs-extra - File system utilities
• send - Static file serving
• server-destroy - Graceful server shutdown

How It Works

1. Build Phase:

   • Wraps @astrojs/node adapter to generate Node.js server
   • Reads apphosting.yaml for runtime configuration
   • Resolves secrets from Google Cloud Secret Manager
   • Generates .apphosting/bundle.yaml with deployment config

2. Deploy Phase:

   • Firebase App Hosting reads bundle.yaml
   • Configures instance settings (CPU, memory, scaling)
   • Injects environment variables and secrets
   • Starts server with node dist/server/entry.mjs

3. Runtime:

   • Node.js server handles requests
   • Serves static assets from dist/client/
   • Executes SSR for dynamic routes
   • Scales automatically based on traffic

Related

• Astro Documentation
• Firebase App Hosting Documentation
• Google Cloud Secret Manager

License

ISC

Author

Relking Elements (Aron Suarez)

Support

For issues and questions:

• GitHub Issues
• Astro Discord
• Firebase Support