Deployment Guide

This guide covers how to deploy your Firefly blog to various platforms.

Local Build

If you use your own web server (e.g., Nginx, Apache, etc.), you can build locally and upload manually:

pnpm build

The build output is in the dist/ directory. Upload all files from that directory to your server.

TIP

The following platforms build and deploy automatically — no manual build required.

Vercel

Vercel is one of the easiest platforms for deploying Astro projects.

Option 1: Via Vercel Dashboard

1. Push your project to GitHub / GitLab / Bitbucket
2. Log in to Vercel, click Add New → Project
3. Import your repository
4. Vercel will auto-detect the Astro framework:
   • Framework Preset: Astro
   • Build Command: pnpm build
   • Output Directory: dist
   • Install Command: pnpm install
5. Set Node.js version: go to Settings → General → Node.js Version, select 22.x
6. Click Deploy

Option 2: Using vercel.json

Create vercel.json in the project root:

{
  "framework": "astro",
  "buildCommand": "pnpm build",
  "outputDirectory": "dist",
  "installCommand": "pnpm install"
}

TIP

Vercel supports automatic deployments: every push to the main branch triggers a build and deploy.

Netlify

Netlify is another popular static site hosting platform.

Option 1: Via Netlify Dashboard

1. Log in to Netlify
2. Click Add new project → Import an existing project
3. Connect your GitHub repository
4. Configure build settings:
   • Build command: pnpm build
   • Publish directory: dist
5. Set NODE_VERSION to 22 in Environment variables
6. Click Deploy site

Option 2: Using netlify.toml

Create netlify.toml in the project root:

[build]
  command = "pnpm build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "22"

GitHub Pages

Use GitHub Actions to deploy Firefly to GitHub Pages.

Steps

1. In your GitHub repository: Settings → Pages → Source, select GitHub Actions

2. Create .github/workflows/deploy.yml in the project root:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

3. Set site and base in astro.config.mjs:

export default defineConfig({
  site: "https://<username>.github.io",
  base: "/<repo-name>/",
});

WARNING

No editing needed for base, if the GitHub Pages set a custom domain or the repo is named <username>.github.io

Cloudflare Workers

Cloudflare Workers offers free serverless edge computing. That can also use to host static site.

Option 1: Via Cloudflare Dashboard

1. Create wrangler.toml in the project root：

name = "firefly"
compatibility_date = "YYYY-MM-DD" # edit to today

[assets]
directory = "./dist"

[vars]
NODE_VERSION = "22"

2. Log in to Cloudflare Dashboard
3. Enter Compute → Workers & Pages, click Create application → Connect Github
4. Select your GitHub repository
5. Configure build settings:
   • Build command: pnpm build
   • Deploy command: npx wrangler deploy
6. Click Deploy

Option 2: Using Wrangler CLI

# Install Wrangler
pnpm add -g wrangler

# Login
wrangler login

# Build & deploy
pnpm build
wrangler deploy dist

Cloudflare Pages

Cloudflare Pages offers free static site hosting.

Option 1: Via Cloudflare Dashboard

1. Log in to Cloudflare Dashboard
2. Enter Compute → Workers & Pages, click Create application → Pages → Connect to Git
3. Select your GitHub repository
4. Configure build settings:
   • Framework preset: Astro
   • Build command: pnpm build
   • Build output directory: dist
5. Set NODE_VERSION to 22 in Environment variables
6. Click Save and Deploy

Option 2: Using Wrangler CLI

# Install Wrangler
pnpm add -g wrangler

# Login
wrangler login

# Build & deploy
pnpm build
wrangler pages deploy dist

EdgeOne Pages

EdgeOne Pages is a static site hosting service provided by Tencent Cloud's edge computing platform.

Steps

1. Log in to EdgeOne Console
2. Go to Site Acceleration → Pages, click Create Project
3. Select Import from Git, connect your GitHub / GitLab repository
4. Configure build settings:
   • Framework preset: Astro
   • Build command: pnpm build
   • Output directory: dist
5. Set NODE_VERSION to 22 in environment variables
6. Click Start Deployment

TIP

EdgeOne Pages has edge nodes in mainland China, providing fast access for Chinese users.

Alibaba Cloud ESA

Alibaba Cloud ESA (Edge Security Acceleration) offers a Pages static site hosting feature.

Steps

1. Log in to Alibaba Cloud ESA Console
2. Go to Pages, click Create Project
3. Select Import from Git, connect your GitHub / GitLab repository
4. Configure build settings:
   • Framework preset: Astro
   • Build command: pnpm build
   • Output directory: dist
5. Set NODE_VERSION to 22 in environment variables
6. Click Start Deployment

TIP

Alibaba Cloud ESA has extensive edge nodes globally, with particularly broad coverage in mainland China, making it ideal for blogs targeting Chinese users.

Custom Domain

Most platforms support custom domain binding. General steps:

1. Add a CNAME record at your DNS provider pointing to the platform-assigned domain
2. Add the custom domain in the platform dashboard
3. Wait for DNS propagation (usually a few minutes to hours)
4. Enable HTTPS (most platforms auto-provision SSL certificates)

Deployment Notes

• Ensure site in astro.config.mjs is set to your actual domain
• If deploying to a subpath (e.g., https://example.com/blog/), set the base field
• Node.js version must be set to 22 or higher on all platforms
• After the initial deployment, subsequent code pushes will automatically trigger redeployment