A demonstration project to deploy a Solid.js application to GitHub Pages.
A note on package management:
These setup instructions use 'pnpm' as the package manager. However, it can substituted with the equivalent npm
or yarn
command.
ex) replace pnpm install ...
with npm install ...
or yarn install ...
Starting in the terminal of your local machine, initialize a Solid application using the solid template. There are templates for javascript and typescript. We will use the typescript template. However, either template will work.
Install degit globally, if it doesn't exist on your machine.
pnpm install -g degit
Initialize the Solid application
npx degit solidjs/templates/ts my-app
cd my-app
pnpm install
We will need a git
history to interface with GitHub
and create a branch specific to deployment. A git
history is not created automatically. We will need to start it manually.
git init
This should also generate a .gitignore
with dist
and node-modules
. We will want to exclude these folders from the git history.
If this .gitignore
does not exist, create it now. It should match the this repository's .gitignore.
Each GitHub Page is built from a GitHub repository. We will need to create one to host the website.
- Select "New" on the repositories page.
- Name the repository.
- Create repository. (Skip adding any template, readme, license, or .gitignore. These will come from local repository)
- Copy the link from the "Quick setup" on the next page. This is the link to the GitHub repository. It should be the url to the repository, followed by a
.git
extension.
Add the GitHub repository as remote resource for the local project. We will title it origin
. This is the traditional naming pattern.
It is also the name that our site will look for later, when we are deploying the application.
Back in the my-app
folder of your computer's terminal, run:
git remote add origin [link to GitHub repository]
When deploying the site, GitHub pages will look for a production build of the application on the gh-pages
branch of the repository.
This site is configured to store its production build in the dist
folder. If you recall from earlier, we tell git to ignore this folder.
This means we want to manage our gh-pages
branch differently than our development branches. The gh-pages
module helps us mange this special branch.
To configure the module:
- Install it as development requirement
pnpm install --save-dev gh-pages
- Create a script for deployment.
- open the package.json file
- under
scripts
, add"deploy": "gh-pages -d dist",
When building the application, Vite will assume that it is hosted on a root path. However, the GitHub pages route will include the name of repository.
We will need to tell Vite about this path. This is done with the base
option of the Vite config.
- add
base: '/[your-repo-name]/',
to the vite.config.ts
Note: If you need to specify resource paths throughout your application relative to this path,
it is available through import.meta.env.BASE_URL
.
We are finally ready to run our first deployment.
- Create a production build of the application
pnpm run build
- Deploy the application to GitHub pages
pnpm run deploy
GitHub Pages follows a format of [account-name].github.io/[repository-name]
.
You can visit your site there.
The gh-pages
module's deploy script will create a gh-pages
branch in your repository that contains only the production build. You can create other branches to track your source code.
git add .
git commit -m '[message]'
git push origin [branch-name]
Thank you, gitname. The react-gh-pages example served as a guideline for this Solid.js version.