Skip to content

Host using GitHub Pages

Tip

This course was updated in 2024. For the newer content, please visit Host using GitHub Pages

Video Lecture

Host using GitHub Pages Host using GitHub Pages

Description

Provided that out Three.js project works fully client side in a web browser just by downloading static files, e.g., the index.html, bundle.js and possibly some extra assets such as images, 3D models, static JSON, CSS, other HTML and JavaScript files, then we can host the contents of our ./dist/client/ folder using GitHub pages for free.

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

  • Upload the required files from your ./dist/client/ folder. E.g., index.html, bundle.js and any other assets such as any images or 3D models needed by your project.

  • If your assets, such as any 3D models or images should also be placed in a sub folder, then you can edit the file name using the GitHub user interface, prepend the required folder name and follow it with a / in front of the existing file name and then press the Commit button. See video for example.

  • Go to Settings/Pages and change Source to Branch: main and then select \root and then press the Save button.

You will be presented with a public URL that will point to your public GitHub page. Note that visiting this new URL to soon may result in a 404 error. It can take a minute or 2 before it will be live.

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

This is a very simple and minimal approach to hosting your Three.js examples for free as long as they can be fully downloaded as static files and don't require any bespoke or dynamic server side functionality or interaction.

GitHub Pages is acting just like a static HTTP web server but using a GitHub web address and an SSL certificate.

Deploy using gh-pages

There is another method provided by GitHub for deploying where you can install an extra library named gh-pages into your project that allows you to deploy your chosen distribution folder to the GitHub pages section of your repository.

Note before you start this, your project should be already committed to GitHub in its own repository. I am using my official boilerplate for this example and I will deploy the ./dist/client folder to be served via GitHub pages.

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": {
    "build": "webpack --config ./src/client/webpack.prod.js",
    "start": "node ./dist/server/server.js",
    "dev": "webpack serve --config ./src/client/webpack.dev.js",
    "test": "echo \"Error: no test specified\" && exit 1",
    "deploy": "gh-pages -d ./dist/client"
  },
...

Now build the production version of your bundle.js using the webpack production configuration.

npm run build

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

My site is hosted at

https://sean-bradley.github.io/Three.js-TypeScript-Boilerplate/

Comments