Github pages provides an alternative option to host pages directly from repositories.
Despite being a static file hosting service, we can create dynamic web applications. In this article we will use Vue.js to create an application and deploy it on github.
Github pages allows three types of GitHub Pages sites: project, user, and organization. The chosen type defines the name of the repository to be created.
For a personal site, the repository name should follow the pattern
For an organization’s website, a repository must be created following the
<organization>.github.io pattern. It must belong to the organization.
Each GitHub account can have a personal website, and each organization can have a website of type organization. As for the project type, there is no such limitation.
Let’s create a project type website. Go to github and create a new repository. As the type will be project, we don’t have to follow the patterns described above.
For this tutorial, we will choose
bravecl-public as the repository name. This repository must be public.
Let’s configure the repository locally. Github offers a quick setup, shown right after the repository is created. You can directly clone the repository or use one of the quick setup options.
Create an index.html file with the content below:
In the project type, GitHub suggests that the files should be at the root of the
Let’s initially commit our
index.html file. Run the commands below in the terminal:
git add index.html
git commit -m "Hello world index.html"
git push -u origin main
Now, let’s create the
gh-pages branch and push it to the repository. Run the commands below:
git checkout -b gh-pages
git push -u origin gh-pages
Access your project on Github and go to Settings. Go to pages on the left menu.
You now have your site hosted and published on github pages. You can use the link provided to access it.
This step is optional.
If you have a domain, you can use it. In our case, we will use the domain
test.bravecl.com instead of
On the Settings > Pages, under Custom domain add your domain and click Save.
Github will complain that you need to configure DNS. We will need to set up a CNAME record. The registry name must be the chosen domain and the value must be
<user>.github.io. In our case, the cname should contain name: test.bravecl.com. value:
DNS configuration is outside the scope of this article. If you have configured it correctly, you can test using the dig command. In the case of test.bravecl.com we can run:
dig test.bravecl.com cname
You can enable the Enforce HTTPS function to increase security.
With our hello world running on Github pages, let’s create our Vue.js project.
You will need to have nodejs installed, available from https://nodejs.org/.
We will use Visual Studio Code as an IDE. Open your repository folder. Run the command below in the terminal to create the Vue.js project:
git checkout master
npm init vue@latest dev
Choose the following options:
- Add TypeScript? No
- Add JSX Support? No
- Add Vue Router for Single Page Application development? Yes
- Add Pinia for state management? Yes
- Add Vitest for Unit Testing? No
- Add Cypress for both Unit and End-to-End testing? No
- Add ESLint for code quality? Yes
- Add Prettier for code formatting? Yes
A new project will be created in the dev folder. Run in terminal:
Your project should look as shown above. Run npm run dev and access localhost:3000 in your browser.
Build and Deploy
vite.config.js file and edit it as shown below. Let’s set the destination folder to be /docs, at the root of your repository.
If you have not configured a custom domain, in a project hosting, you must also configure the base path , as shown below, replacing
Run npm run build. The docs folder will be created at the root of your repository.
In the terminal, enter the commands below:
git add -A
git commit -m "Vue project creation"
git checkout gh-pages
git merge main
The above commands merge the Vue project created in the
gh-pages branch. Go to your repository’s configuration page on GitHub and in Source change it to
/docs. Click Save.
Now, let’s update our repository with GitHub and push. If you are using a custom domain, git pull will bring up the CNAME file created by git, requiring you to type a message for the merge.
Below, the updated website.