Deploy to Firebase

What Is Firebase Hosting?

Firebase Hosting is Google’s static site hosting platform with a global CDN, free SSL, and automatic deployments from GitHub. It is part of the larger Firebase ecosystem, which also includes databases, authentication, and cloud functions.

For Astro Docus, Firebase Hosting is a solid choice because:

• Free Spark plan is sufficient for static sites
• Global CDN powered by Google’s infrastructure
• Automatic HTTPS on all domains
• GitHub integration for automatic deploys and preview URLs
• No configuration needed for static Astro sites

Astro Docus builds to static HTML, CSS, and JavaScript by default. This means no adapter is required for Firebase Hosting — the static output works as-is .

---

Prerequisites

Before starting, you need:

• A Google account (Gmail or Google Workspace)
• Your Astro Docus project built locally (npm run build works)
• A terminal open in your project folder

Note: Firebase Hosting is part of Google Cloud. The free Spark plan does not require a credit card.

---

Method 1 — Deploy via Firebase CLI

This is the most direct method. The Firebase CLI handles authentication, initialization, and deployment.

Step 1 — Install Firebase CLI

Install the Firebase command-line tools globally:

npm install -g firebase-tools

Verify installation:

firebase --version

You should see a version number like 13.x.x .

Step 2 — Log In to Firebase

firebase login

This opens your browser. Log in with your Google account and authorize the CLI .

After authorization, return to the terminal. You should see:

✔  Success! Logged in as your-email@gmail.com

Step 3 — Create a Firebase Project (If You Don’t Have One)

If you already have a Firebase project, skip to Step 4.

1. Go to: https://console.firebase.google.com
2. Click Add project
3. Enter a project name (e.g., astrodocus)
4. Accept the terms and click Continue
5. (Optional) Enable Google Analytics — not required for hosting
6. Click Create project
7. Wait for project creation to complete
8. Click Continue

Step 4 — Enable Experimental Web Frameworks Support

Firebase CLI needs this flag to properly detect and configure Astro projects:

firebase experiments:enable webframeworks

This enables the CLI’s framework-aware deployment features .

Step 5 — Initialize Firebase Hosting

Run this command from your project root:

firebase init hosting

The CLI walks you through a series of prompts:

1. Please select an option: Choose Use an existing project
2. Select a default Firebase project: Choose the project you created
3. What do you want to use as your public directory? Type: dist
4. Configure as a single-page app (rewrite all urls to /index.html)? Choose No (Astro Docus uses multiple HTML files)
5. Set up automatic builds and deploys with GitHub? Choose No for now (we cover this in Method 2)
6. File dist/index.html already exists. Overwrite? Choose No

This creates two files in your project root :

• firebase.json — Firebase Hosting configuration
• .firebaserc — Links your project to the Firebase project

Step 6 — Deploy

firebase deploy --only hosting

This command:

1. Builds your Astro site (runs npm run build)
2. Uploads the dist/ folder to Firebase Hosting
3. Deploys to the global CDN

Step 7 — Your Live Site

After deployment completes, you see:

✔  Deploy complete!

Hosting URL: https://your-project.web.app

Open this URL in your browser. Your Astro Docus site is live.

---

Method 2 — Deploy via GitHub Integration

Once set up, every push to your main branch triggers an automatic deployment. Firebase also creates preview URLs for every pull request .

Step 1 — Set Up the GitHub Action

From your project root:

firebase init hosting:github

The CLI prompts you to authorize GitHub and select your repository. It automatically :

1. Creates a service account in your Firebase project
2. Encrypts the service account key
3. Uploads it to your GitHub repository as a secret
4. Writes GitHub workflow YAML files

Step 2 — Commit the Workflow Files

The CLI creates files in .github/workflows/. Commit and push them:

git add .github/
git commit -m "Add Firebase Hosting GitHub Action"
git push

Step 3 — How It Works

After setup :

Action	Result
Push to main	Deploys to live channel (your-project.web.app)
Open a pull request	Creates a preview URL and comments it on the PR
Push new commits to PR	Preview URL updates automatically

Preview URLs stay stable throughout the PR lifecycle. The same URL reflects the latest commits .

---

Adding a Custom Domain

A *.web.app subdomain works, but a custom domain looks more professional.

Step 1 — Go to Hosting Settings

1. Open Firebase Console → your project
2. Click Hosting in the left sidebar
3. Click Add custom domain

Step 2 — Enter Your Domain

Type your domain (e.g., docs.yourdomain.com) and click Continue.

Step 3 — Verify Ownership

Firebase provides a TXT record to prove you own the domain. Add it at your domain registrar, then click Verify.

Step 4 — Configure DNS

Firebase shows the required records:

Record Type	Name	Value
A	@ (root)	Firebase IP addresses
CNAME	subdomain	your-project.web.app

Add these at your registrar (Namecheap, GoDaddy, Cloudflare, etc.).

Step 5 — Wait for Propagation

DNS propagation takes minutes to hours. Firebase automatically provisions an SSL certificate once DNS is verified.

---

Firebase Free Tier Limits

The Spark (free) plan includes :

Resource	Included
Storage	10 GB
Data transfer	360 MB/day (~10 GB/month)
Custom domains	Yes
SSL certificates	Yes (automatic)
Simultaneous connections	100

For a documentation site with moderate traffic, the free tier is sufficient. If you exceed 360 MB/day, upgrade to the Blaze (pay-as-you-go) plan.

---

Astro Configuration for Firebase

Astro Docus is a static site. For static deployment, no adapter is required .

If you see adapter: cloudflare(...) in astro.config.mjs, you can either:

1. Remove the adapter block for pure static deploy
2. Keep it — the adapter only affects SSR builds, not static output

For Firebase static hosting, removing the adapter is cleaner.

---

Troubleshooting

Problem	Likely Cause	Fix
CLI not found	Not installed globally	Run npm install -g firebase-tools
Login fails	Popup blocked	Allow popups or use firebase login --no-localhost
Deploy fails	Build error	Run npm run build locally first
404 errors	Wrong public directory	Ensure firebase.json has "public": "dist"
Site not updating	Browser cache	Hard refresh (Ctrl+Shift+R)
GitHub Action fails	Missing secret	Re-run firebase init hosting:github

---

Quick Recap

Method 1 — Firebase CLI:
1. npm install -g firebase-tools
2. firebase login
3. Create project at console.firebase.google.com
4. firebase experiments:enable webframeworks
5. firebase init hosting (public: dist)
6. firebase deploy --only hosting
7. Live at *.web.app

Method 2 — GitHub Integration:
1. firebase init hosting:github
2. Commit and push .github/workflows/
3. Every push → automatic deploy
4. Every PR → preview URL

Custom Domain:
- Console → Hosting → Add custom domain
- Verify with TXT record
- Add A and CNAME records
- SSL automatic

Firebase Hosting is Google-backed and reliable. The CLI handles the build and deploy in one command, and the GitHub integration gives you preview URLs for every pull request.

👉 Next: docs/deploy-hosting/aws.md — deploy to AWS S3 and CloudFront.