Skip to content

Host using GitHub Pages

Video Lecture

Host using GitHub Pages Host using GitHub Pages

Description

Provided that our Three.js project works when served from the ./dist/ folder, then we can host it using GitHub pages for free.

To use GitHub pages, you will need to have a GitHub account.

If you forked the boilerplate used in this course, and you used git clone to download your forked version locally, and you were editing the code in that version during the course, then you also have a tool named gh-pages installed as a dependency from your ./package.json.

Provided that your npm run build and npm run preview works, and it saves to the ./dist/ folder, you can just run npm run deploy, and it will push the contents of the ./dist/ folder to your own gh_pages branch of your own forked version of the course boilerplates repository.

After a few minutes, you will be able to view your application live on GitHub pages using the URL,

https://<your lowercase github username>.github.io/Three.js-Boilerplate-TS-Vite/

Note that this will only work, if you forked your own copy of the boilerplate in GitHub and then git cloned that version.

Manually Creating a GitHub pages website.

So, what can you do if you didn't clone your own forked version of the course boilerplate, but just created the boilerplate manually as demonstrated at the beginning of the course?

First, you will need to ensure there is a base directive in your ./vite.config.js.

./vite.config.js

import { defineConfig } from 'vite'
import topLevelAwait from 'vite-plugin-top-level-await'

export default defineConfig({
  plugins: [topLevelAwait()],
  base: './',
})

The base directive is needed because GitHub pages will serve your content from a sub path in the URL, which will be the name as your repository. If you don't do this, you will get HTTP 404 errors when loading the assets.

Also ensure that any images and models loaded into your project, have the paths prefixed as, for example,

textureLoader.load('img/lensflare0.png') // ✓

or

textureLoader.load('./img/lensflare0.png') // ✓

but not this,

textureLoader.load('/img/lensflare0.png') // ✕

The first two options will load resources relative to the loaded HTML script, instead of relative to the web root. This is an important consideration when hosting on GitHub pages.

Next, run the build script again.

npm run build

Then preview in the browser to be sure it works.

npm run preview

Visit http://localhost:4173/

Now to log into your GitHub account and create a new repository using any name that you want.

E.g., My-Project.

Note that the name needs to conform to the following rules.

  • Max length 39 characters
  • Alphanumeric or hyphen (-)
  • Cannot start with a hyphen
  • No consecutive hyphens
  • Cannot be a reserved name
  • Unique for your account

Next, drag and drop the files and folders from your ./dist/ folder.

Finally, go to Settings/Pages and change Source to Branch: main and then select \root and then press the Save button.

After a few minutes, you will be able to view your application live on GitHub pages using the URL,

https://<your lowercase github username>.github.io/<name-of-your-new-repository>/

And this is the GitHub pages example created in the video,

My-Project : https://sean-bradley.github.io/My-Project/

Add gh-pages to existing repository

If you already have your own GitHub repository for your project, and building the production version works when previewing, you can add gh-pages to your existing project.

Note that your project already needs to be setup in GitHub, and you can successfully git pull and git push to your own repository.

In your project, install the gh-pages dependency.

npm install gh-pages --save-dev

Add a new script command to your package.json named deploy

{
...
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "deploy": "gh-pages -d ./dist"
  },
...

After building and previewing that it works from the ./dist/ folder,

You can deploy using gh-pages

npm run deploy

After a minute or two, your GitHub pages site will be live. View the Settings Pages section in your projects GitHub repository to verify the URL of your public GitHub pages web address.

It will be something like this,

https://<your lowercase github username>.github.io/<name-of-your-new-repository>/

Comments