Why GitHub Pages for Flutter Web?

Did you know you don’t need to setup a web hosting service to deploy your Flutter web app?

That’s right! When I wanted to create a quick preview for one of my Flutter apps to share with others, I wasn’t ready to go through the hassle of setting up a new site with a traditional web hosting service.

After exploring my options, I found several ways to host a Flutter Web app:

  1. GitHub Pages
  2. Firebase Hosting
  3. Traditional web hosting

For a quick prototype or portfolio piece, GitHub Pages seemed ideal. In this guide, I’ll walk you through the complete process of deploying your Flutter web app to GitHub Pages.

Prerequisites

Before we start, make sure you have:

  • A Flutter project with web support enabled
  • Your GitHub Repository is public

Setup

Add Web Support to Your Flutter Project

If your project doesn’t already support web, you can add web support by running:

flutter create --platforms=web .

You can verify web support is enabled with:

flutter devices

You should see “Chrome” web browser listed in the available devices.

Build the Project for Web

We need to build the web app using this command:

flutter build web --release --base-href=/YOUR_REPOSITORY_NAME_HERE/

Replace YOUR_REPOSITORY_NAME_HERE with your actual repository name.

For instance, if your repository name is flutter-playground, the command will be:

flutter build web --release --base-href=/flutter-playground/

Understanding the base-href Parameter

The --base-href flag is crucial because:

  • GitHub Pages serves your site from a subdirectory (yourusername.github.io/repository-name)
  • Without this parameter, your app would try to load assets from the root domain
  • This flag ensures all relative URLs in your app are correctly prefixed with your repository path

After running the build command, your compiled web app will be generated in the build/web/ directory.

Prepare for GitHub Pages

GitHub Pages can serve content from either:

  • The root directory
  • The /docs folder in your main branch
  • A dedicated branch (typically called gh-pages)

For this guide, we’ll use the /docs approach as it’s straightforward and keeps everything in one branch.

Create a docs/ directory in the root of your project and copy all contents from build/web/. This can be done manually or using below command:

mkdir -p docs
cp -R build/web/* docs/

Commit and Push to GitHub

Add, commit and push the changes to your GitHub repository: This can be done using your favorite git tool or using below command:

git add docs/
git commit -m "Add web build for GitHub Pages"
git push origin main

Configure GitHub Pages Settings

  1. Go to your GitHub repository in a web browser
  2. Click on “Settings” tab
  3. Scroll down to the “Pages” section
  4. For “Branch”, select the main or master branch and /docs folder
  5. Click “Save”

GitHub Pages Settings

GitHub will provide you with the URL where your site is published (typically https://username.github.io/repository-name).

Access Your Deployed App

After a few minutes, your Flutter web app will be available at:

https://username.github.io/repository-name

Automating the Deployment Process

Using a Script From Local Machine

Manually copying files and commiting can become tedious. We can automate this process with a shell script.

Create a file named deployment.sh in your project root:

#!/bin/bash

set -e

BUILD_DIRECTORY="build/web"
DEPLOY_DIRECTORY="docs"
COMMIT_MESSAGE="Deploy On Pages"
BASE_HREF="YOUR_REPO_NAME"

build_flutter_web() {
echo "Building Web application..."

    rm -rf "$BUILD_DIRECTORY"
    
    if ! flutter build web \
        --base-href=$BASE_HREF \
        --release; then
        echo "Flutter build failed"
        exit 1
    fi

}

deploy_to_pages() {
echo "Deploying to GitHub Pages..."

    mkdir -p "$DEPLOY_DIRECTORY"
    
    rm -rf "${DEPLOY_DIRECTORY:?}/"*
    
    if ! cp -r "$BUILD_DIRECTORY"/* "$DEPLOY_DIRECTORY"; then
        echo "Failed to copy build files"
        exit 1
    fi

    if git add .; then
        git commit -m "$COMMIT_MESSAGE" && git push
    else
        echo "Git operations failed"
        exit 1
    fi
    
    echo "Deployment completed successfully!"
    echo "Please ensure GitHub Pages is configured to serve from the $DEPLOY_DIRECTORY folder"

}

build_flutter_web
deploy_to_pages

Make the script executable:

chmod +x deployment.sh

Now, whenever you want to update your deployed app, simply run:

./deploy.sh

Setting Up GitHub Actions for CI/CD

For even more automation, you can set up GitHub Actions to automatically build and deploy your Flutter web app whenever you push changes to your repository.

Create a file at .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
workflow_dispatch:  # Allows manual triggering from GitHub UI

jobs:
build-and-deploy:
runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Set up Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.29.1'

      - name: Install dependencies
        run: flutter pub get

      - name: Configure Git
        run: |
          git config --global user.name "GitHub Actions"
          git config --global user.email "actions@github.com"

      - name: Run deployment script
        run: |
          chmod +x ./deployment.sh
          ./deployment.sh

With this workflow, GitHub will automatically build and deploy your app when you push to the main branch.

Conclusion

I have this setup in my Playground Repository. You can have a look for inspiration. Also, I created a gist for the deployment script

P.S. If you found this helpful, don’t forget to check out my other Flutter articles and give a star to my Flutter Playground Repository for more practical examples.

Tags: flutter web github pages deployment CI/CD hosting
Share: