Vite GitHub Pages Deployer

Deploy your Vite application to Github Pages, at a glance.

• No shenanigans such as committing the dist folder and pushing to a branch.
• Clean deploy to GitHub Pages by utilizing actions and artifacts.
• Customizable with optional build path
• Can be used with any frontend framework as long as you use vite as your build tool. Vue, React, Svelte... You name it!

- name: Vite Github Pages Deployer
  uses: skywarth/vite-github-pages-deployer@v1.4.0

Table of Contents

1. Usage
2. Example Workflow
3. Demo
4. Input Parameters
5. Outputs
6. Common errors and mistakes
7. TODOs

1. Usage 🏁

You can use this action simply by adding it to your action's yaml files appropriately.

1.1 Add the usage step 🚩

Make sure to place this step after your 'checkout' step.

- name: Vite Github Pages Deployer
  uses: skywarth/vite-github-pages-deployer@v1.4.0
  id: deploy_to_pages

1.2 Release environment 📤

You have to place the environment section right before the steps. This enables the release of environment, under the environments tab.

environment:
  name: demo
  url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}

1.3 Set the permissions for the action

You need to set the proper permission for the action, in order to successfully release environment and artifact. If you don't you may receive permission errors.

Permission declaration can be placed anywhere before jobs: section.

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

1.4 Enjoy! 🎉

2. Example workflow 🚀

If you don't know what to do, what actions are, or where to place the code pieces in the usage section, then follow these steps:

1. Create an action file at this path: ./.github/workflows/vite-github-pages-deploy.yml. So in essence create a .github folder at your project root, and create a yml file in there.
2. Copy the code below and paste it into the action you've just created, then save.
3. Done. On your next push to master branch, or your next manual run from actions tab, this action will run and your project will be deployed to github pages.

name: Vite Github Pages Deploy

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master", "main"]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    environment:
      name: demo
      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Vite Github Pages Deployer
        uses: skywarth/vite-github-pages-deployer@master
        id: deploy_to_pages

3. Demo 🗿

Want to see it in action? Sure thing, head on to this vue project to see it live: https://github.com/skywarth/country-routing-algorithm-demo-vue

4. Input Parameters 🔧

public_base_path (optional)

Type	Default	Example Values
string	/{your-repo-name} OR / if you have CNAME	/my-vite-project

Public base path string for Vite, this affects the routing, history and asset links. Make sure to provide appropriately since GitHub Pages stores your app in a directory under a subdomain. If you plan on deploying to alternative platform such as Vercel, you should simply provide /.

Under normal circumstances, you don't need to provide/override this parameter, action will set it to your repo name appropriately.

Here's how public_base_path is resolved:

• If public_base_path parameter/input is provided, it will be used regardless.
• If public_base_path parameter/input is NOT provided:
  • If the repository root has CNAME file for GitHub Pages Custom Domain setup, then public_base_path default value will resolve to /
  • If the repository root does NOT have CNAME, public_base_path default value will resolve to /{your-repo-name}

Acknowledgement

See the suggestion for the CNAME expansion here

Grateful to the Greg Sadetsky for his proposition on alternating default value of this input. Also, thankful for his collaboration on explaining GitHub pages custom domain setting and testing phase of these changes.

build_path(optional)

Type	Default	Example Values
string	./dist	- ./deploy - ./dist/browser

Which folder do you want your GitHub Page to use as root directory, after the build process. Simply it is your build output directory such as ./dist. If your vite config exports to a folder other than ./dist, then you should pass it as parameter.

install_phase_node_env(optional)

Type	Default	Example Values
string	dev	- dev - production - staging - test - my-little-pony-env

Node environment that will be used for the installation of dependencies. It is imperative you use an environment that has 'vite' as dependency. Commonly and naturally, that env is dev.

❌ If you don't provide a NODE_ENV that has vite as dependency (check your package.json), you'll receive sh: 1: vite: not found during build phase.

build_phase_node_env (optional)

Type	Default	Example Values
string	production	- dev - production - staging - test - my-little-pony-env

Node environment that will be used for the build phase. You may provide any valid NODE_ENV value for this, since node builds tend to change for different environments (e.g: you hide debugging features from production).

artifact_name (optional)

Type	Default	Example Values
string	github-pages	- what-a-cool-artifact - ah-yes-ze-artifact

Desired name for the exposed artifact. This name is visible in job and used as the artifacts name.

package_manager (optional)

Type	Default	Example Values
string	npm	- npm - yarn

Indicate the package manager of preferrence. It'll be used for installing dependencies and building the dist. For example if you prefer/use yarn as your package manager for the project, then you may pass package_manager: 'yarn' as input which then will be used as yarn install and yarn build.

debug_mode (optional)

Type	Default	Example Values
string	'false'	- 'true' - 'false'

Controls the debug mode, string, 'true' is for on. When turned on, it'll output certain information on certain steps. Mainly used for development, but use it as you please to inspect your env and variables.

5. Outputs 📌

github_pages_url

Type	Example Values
string	- 'https://skywarth.github.io/country-routing-algorithm-demo-vue/'

This output value shall be used to acquire the github pages url following the deployment. It can be accessed like so: ${{ steps.deploy_to_pages.outputs.github_pages_url }} (deploy_to_pages is the id of the step that you run Vite Github Pages Deployer).

It is expected to be used as a way to publish environment during the job, like so:

environment:
      name: demo
      url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}

See example workflow to grasp how to utilize this output

6. Common errors and mistakes 🆘 📛

6.1 Not releasing the environment

Error: Environment URL '' is not a valid http(s) URL, so it will not be shown as a link in the workflow graph.

Cause: Environment declaration is missing from the action, you should add it to your action yaml file in order to both solve the error/warning and to display the released environment in the environments tab in the repository.

Solution: Add the following to your action:

environment:
  # Name could be whatever you wish. It'll be visible publicly under the environments tab.
  name: demo
  url: ${{ steps.deploy_to_pages.outputs.github_pages_url }}

⚠️ Remember, deploy_to_pages name should be identical to the id of the step that you run the Vite GitHub pages deployer. See the example workflow for details.

6.2 Missing permission requirements for GITHUB_TOKEN

Error: Error: Ensure GITHUB_TOKEN has permission "id-token: write".

Cause: Permission wasn't set as indicated in the usage section. If proper permissions are not granted to the action, it won't be able to create artifacts or create environments.

Solution: Add the following code about permissions to your action yaml file.

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

See the example workflow if you're not sure where to place it.

6.3 package-lock.json is not present when using npm as package manager preferrence.

Error: The npm ci command can only install with an existing package-lock.json...

Cause: If package_manager input preference is set to npm (or default, unassigned), it will install dependencies using npm ci which utilizes package-lock.json. In this case make sure package-lock.json is present in your project root.

Solution: Add your package-lock.json file to your project. If it's in the directory but doesn't appear in the repository, check your gitignore file and remove it from gitignore. Alternatively, you may set yarn as your preferred package manager for dependency installation via package_manager parameter input of the action.

7. TODOs

• Output the deploy url for environment, see issue #2
• Spread the gospel.
  • DEV.to post
  • Reddit (opensource, github, github action, ci/cd, vite, vue, react forums etc.).Blah, reddit was like, you know... Reddit.
  • Maybe a medium.com post... God I hate that place, it stinks.
• NODE_ENV options/params
  • Install phase NODE_ENV
  • Build phase NODE_ENV
• Section for common errors and solutions. (Dismantle tidbits)
• Make README more eye-candy
  • Table for each input/param (type, default etc.)
  • Icons for emphasis
• Option for defining package manager preference, see issue #1
• Table of Content
• Move bash scripts to a separate file for each section: build.sh, install.sh etc... (not feasible, see the branch bash-files)
  • Passing some parameters to it perhaps (not feasible, see the branch bash-files)

Something is lacking ?

Is there something you require, does this action fail to meet your expectations or it lacks certain futures that prevent you from using it ? Open up an issue, and we add it to the roadmap/TODOs. Contributions are welcome.

Notes to self

• ${{github.action_path}}: Gives you the dir for this action itself.

• ${{ github.workspace }}: Gives you the dir of the project (E.g: /home/runner/work/country-routing-algorithm-demo-vue/country-routing-algorithm-demo-vue)

• When you import a sh file in the bash shell, it is only accessible during that step only. This is due to the fact that each step is a shell on its own.

• Inside separate sh files, you can access input variables of the action by their respective uppercase name. For example:

  • Input definition:

    inputs: 
        package_manager:
        description: "Your preference of package manager: 'npm' and 'yarn' are possible values."
        required: false
        default: 'npm'
    

  • Accessing this input inside the action: ${{ inputs.package_manager }}
  • Accessing this input **inside a sh file: $PACKAGE_MANAGER
    • Alternatively, you may pass env to the step to access it from a name of your liking:

      env:
        SOME_OTHER_NAME: ${{ inputs.package_manager }}
      

• If you run sh files in steps, don't expect each shell to share the environments. For example in one step you install dependencies in install.sh, in another step you build by build.sh. It won't work because installed libs are only available for the install.sh step. This is why bash-files failed, I consulted GPT but apparently there is no way of achieving it.