So, you've built an app - congrats! You can run it locally, but wouldn't it be sweet if everyone on the internet could use it??
This resource covers deploying a Vanilla JS Vite app using Github Pages.
Note: An alternate (and more complex, but potentially smoother) approach can be found on Vite's own docs.
Table of Contents
- Prerequisites
- What is Github Pages
- Configure Vite for Deployment on Github Pages
- Publish on Github Pages
🎥 Watch the lecture on this topic!
In order to deploy to Github using this guide, you will need
- A project built using Vite
- A Github repo with that Vite project inside.
Github Pages is (according to their website)
... a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.
There are a few ways to utilize Github Pages but the most straightforward is to have an index.html
in the root of our repo that Github Pages can easily find and serve.
With a few VERY easy settings, we can publish our repo as long as that index.html
file is in the root.
To test this out:
- add an
index.html
file to the root of your repo - commit and push it
- follow the instructions below in the Publish On Github Page section.
- delete the
index.html
file once you've tested it.
Objective(s): Build the production version of the app in the root of the directory.
If you made an
index.html
file for testing above, delete it now.
Assuming you built that app using Vite, the first step is to make the production version of the application. To do this, run the command:
npm run build
This will create the production version of your app in a folder called dist/
(short for "distribution"). Take a look inside! It will have an index.html
file and an assets/
folder with your JavaScript and CSS.
However, we need that index.html
to be in the root of the repo:
In order to do that, we'll need to configure Vite to create that version in the right location.
Create a Vite configuration file
touch vite.config.js
And put this inside:
import { defineConfig } from 'vite'
export default defineConfig({
// GitHub Pages expects an index.html in the root directory
// so just run npm build before pushing to GitHub and this will rebuild our assets to the root
build: { outDir: '..' },
// needed for github pages just put the repo name here
base: '/your-repo-name-here/',
});
This does two things:
build
andoutDir
determine where to put your compiled application. Normally it would put it in a folder calleddist/
but in order for Github pages to work, we want to build in the root of the repo.base
determines how theindex.html
file connects to the.js
and.css
files in yourassets/
folder
Now, run the command
npm run build
This will compile the code you've written in your app/
folder into optimized static files that can quickly be served by Github pages. It will put those files in the root directory of your repo, where Github expects to find an index.html
file and any associated assets
.
You can see what this "deployed" version will look like by running the command...
npm run preview
...which will serve the application at http://localhost:4173/
Finally, commit and push your new compiled version to Github!
Note: each time your
npm run build
, new versions of yourassets
will be created and you will need to manually delete them.
Objective(s): Publish your web app!
Deploying your application on Github Pages is about as easy as it gets:
- Open the repo on Github.com
- Go to the Settings tab
- Find the Pages section
- Make sure that Source is Deploy from a branch
- Below, set Branch to
main
(or whatever branch you're using) - Click Save and wait a few minutes! You should see the URL of your application.
- Each time you push a new commit to
main
, your page will redeploy!