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/[email protected]

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

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

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

- name: Vite Github Pages Deployer
  uses: skywarth/[email protected]
  id: deploy_to_pages

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 }}

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

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

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

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.

• 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}

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.

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.

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.

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).

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

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.

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.

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

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.

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.

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.

• 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)

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.