Publishing A Three.js Project On GitHub Pages

In this article, I am going to show you how to publish a Three.js project on GitHub Pages. You don’t have to buy a costly domain or any hosting plan to do so. 

I created a video for this on my YouTube channel 👇

I won’t go into how to develop a Three.js project from scratch. I am assuming you know that and already have a project to showcase on GitHub pages. If you don’t then clone my repo and get started [switch over to the master branch coz I haven’t set it up as the default one]👇

🌎 https://github.com/knightcube/threejs-starter-practice/tree/master

This is how it looks like👇

Check out the live demo here 👉 - https://knightcube.github.io/threejs-starter-practice/

STEPS

✅Step 1: Create a new folder called “dist” in your project. 

If you have cloned the above repo then the “dist” folder is already there. You can skip this step and step 2. Jump directly to Step 3.) 

✅Step 2: Drag and drop the following files inside the dist folder — index.html, style.css, index.js, and any image (or texture) that you have used for your mesh. 

❗ Images in the static folder are not referenced when using GitHub Pages. This means that when you show a cube(or any mesh) in your browser using Three.js and try to load the texture using TextureLoader, the texture won’t get applied to the cube. This happens because GitHub Pages does not reference the images in the static folder. Long story short, put all the images in the dist folder. You can also create a separate “assets” folder inside the dist folder and keep all the images inside the “assets” folder. You can then reference any image inside the assets folder like this— “./assets/yourimage1.png”.

In the below image, I have used coolTex.jpg as a texture for the cube. Therefore I have kept it inside the dist folder.

✅Step 3: Go to package.json file & add this line inside “scripts”- 

"deploy": "gh-pages -d dist"

like so -

"scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "deploy": "gh-pages -d dist"
}

✅Step 4: Run the following command in your project to install gh-pages. (make sure you have cd into the root of your project directory)- 

npm install gh-pages

What is gh-pages?👉 It is an npm package that allows you to publish files to a branch named "gh-pages" on GitHub. You may read more about it here - https://www.npmjs.com/package/gh-pages

✅Step 5: Now we just need to push the project to your repository on GitHub. For that, you will have to create a repo manually on GitHub and then run the following commands one after another -

git init
git remote add origin "YOUR_REPOSITORY_URL"
git add .
git commit -m "YOUR_COMMIT_MESSAGE"
git push origin master

✅Step 6: Once all your code is pushed to the master branch, go to your repo on GitHub and create a new branch. Name it “gh-pages”. Now run this command in your terminal(make sure you are in the root of your project directory) —

npm run deploy

This step runs the “deploy” script that you added in Step 3 above.

✅Step 7: Go to your repo’s setting on GitHub. Scroll down to GitHub Pages section. 

You will see something like this👇 

P.S — Sometimes the site takes time to get published. So kindly wait for some time till you get that beautiful green message. Keep refreshing the page until you get that attractive tick mark.

Conclusion

And there you go! That’s how you deploy your Three.js project on GitHub Pages. 

Showcase your projects and your code to the world. 

Happy coding!

I am learning three.js from this awesome course by Bruno Simon. Join me and more than 4000+ developers from all around the world. Let’s grow the Three.JS community together💪

Last weekend, I made this with Three.js👇 -

Link to the GitHub Repository - https://github.com/knightcube/planet-and-stars-threejs & live demo.