Publishing your Flutter apps into GitHub pages

Versão em português:

Publicando suas aplicações Flutter no GitHub Pages

Rodrigo Castro ・ Oct 4 '22

#programming #tutorial #flutter #dart

Long, long time ago...

In a far far away land, when Flutter web used to be something experimental yet, and I was looking for somewhere to publish my Flutter app into Github pages.

But now with Flutter 3.3.3, Flutter web is already stable long time ago, decided to see what has changed. I took the opportunity to document here everything I learned.

What is this GitHub pages?

Essentially is one approach that GitHub offers you to promote your repository, as a webpage to your code, it can be a landing page, documentation or whatever you want. It's possible to do that in every repository, including a "secret" repository that consists on naming it as <your_github_username>.github.io, and if you create one GitHub page in this repository, it will be your home page and the other repositories always will be <your_github_username>.github.io/other_repo_name/.

I remember that it was cool, long time ago, when the developers used to have their blogs made with static websites into GitHub using Jekyll framework, it was really popular at that moment, I remember that I used to find some cools plugins and themes to customise my blog.

Now (not really now) it's possible to publish your app into GitHub pages, and have your own web app.

Source code

The source code used in this article will be available in this link: https://github.com/castrors/flutter_web

Option 1: Peanut

https://pub.dev/packages/peanut

it's a tool that makes the application build and updates/create a gh-pages branch.

In my case, I had to follow these steps:

• Install peanut

flutter pub global activate peanut

• Run the peanut command line with one extra parameter, because my repository will be available at https://castrors.github.io/flutter_web/, that is different than the default that is /, that's why I needed to give this base-href extra parameter too.

flutter pub global run peanut --extra-args "--base-href=/flutter_web/"

• In the end it will show that the gh-pages branch construction was completely successful, but you need to sync it in git.

To push your gh-pages branch to github (without switching from your working branch), run:
  git push origin --set-upstream gh-pages

• It's just run this command, and your local branch will be synced with the remote and that's it, you just need to wait. You can see that there is one GitHub action running, called pages build and deployment. It's responsible to pick-up your selected branch, in this example gh-pages, and publish it as the page of your repository.

If for some reason you cannot find this GitHub action, maybe it's because the GitHub page was not configured in your repository. To fix that you need to go into your repository -> Settings -> Pages and select the branch you want to build your GitHub page.

• Success! The Flutter web application is alarde published, checkout this link: https://castrors.github.io/flutter_web/#/

Option 2: GitHub actions

In this alternative we are going to create one workflow that will have as trigger, any update into the main branch, so follow all of these steps to publish the GitHub page.

Let's go, open your repository into the GitHub website and follow these steps:

• First, click into the tab Actions, just bellow the repository name and then click into New workflow.
  

• Select the option to create the workflow by yourself set up a workflow yourself.
  

• You will see this screen here. First, in the top rename the file, if you want. I'll change it to deploy_github_page.

• Delete all the content of this file and replace with this code bellow:

name: Flutter Web Deploy
on:
  push:
    branches:
      - main
jobs:
  build:    
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
      - run: flutter build web --release --base-href /flutter_web/
      - run: git config user.name github-actions
      - run: git config user.email github-actions@github.com
      - run: git --work-tree build/web add --all
      - run: git commit -m "Automatic deployment by github-actions"
      - run: git push origin HEAD:gh-pages --force

• Code changed, we are ready to submit the changes, create a commit or PR directly the GitHub to save the changes, in my case I'm going to save it directly into the main branch.

• Is it ready? Yes, now we just need to change any UI component into our application so we can proof that the workflow is working properly.

• All the workflow steps were satisfied and in the end it updates our application that has it's primary color as green instead of blue.

Pros and Cons of these approaches

Peanut is the simplest solution, because it takes just two command lines and you already have your gh-pages branch updated. But we have to consider that we are humans and probably we would forget to run these command lines and your application will not be updated.

In another way, with GitHub action everything runs automatically, but it takes really more time, and you have to consider once your application is growing, it will take more time to run the workflow too. But these steps will never be forgotten, because every time you update your main branch it will trigger these action once again.

Use this knowledge to go further

GitHub pages is not the only option to deploy your Flutter web app, you can give a try in other services like:

Firebase Hosting
Netlify
Codemagic Static Pages

Conclusion

I hope I can help someone with this content, use both approaches wisely, or only one of them, depends on your use case.

See you soon!