Deploy a solid-start app on github pages

Solid-start is the long awaited meta-framework for Solid.js. Since it entered its second beta after a rewrite, there were a few breaking changes, so the previous article on this one's topic was no longer valid.

With solid-start, you can deploy your application with client-side rendering, server-side rendering, or islands architecture basically anywhere thanks to nitro.

One of these presets to deploy pages is "static", which creates a basic server for the server-rendered pages and then uses it to render static versions of them, to be deployed on github pages or wherever else you want. There is also "github_pages", but I cannot see that it does anything different than "static", so let us stick with that.

Creating your project

npm init solid@latest my-app
# or
pnpm create solid@latest my-app

Instead of my-app, use whatever name you want. Select a version with SSR and whatever other configuration you want.

Make sure you are using at least @solid-js/start@0.4.8 or newer, since that fixes an issue with the hydration of pages with a different base url.

Install the dependencies

Once your package is set up, install the dependencies:

npm i
# or
pnpm i

Configure vite

You can add whatever configuration you want; the important parts are ssr: true and the server config.

import { defineConfig } from "@solidjs/start/config";

export default defineConfig({
  start: {
    ssr: true,
    server: {
      baseURL: process.env.BASE_PATH,
      preset: "static"
    }
  }
});

Configure the Router

You need to make the Router in src/app.tsx aware of the base path set in the vite configuration, so add the following base property:

      <Router
        base={import.meta.env.SERVER_BASE_URL}
        root={...}
      >

Create a github action to deploy the page

We can use JamesIves/github-pages-deploy-action to deploy the output from our build on github pages; however, we need to create an extra file .nojekyll so directories starting with an underscore (like _build) will be served and our page will receive its assets.

Add .github/workflows/main.yml:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: install
        run: npm i --legacy-peer-deps

      - name: build
        run: npm run build
        env:
          BASE_PATH: /my-app/

      - name: create .nojekyll
        run: touch .output/public/.nojekyll

      - name: deploy pages
        uses: JamesIves/github-pages-deploy-action@v4.5.0
        with:
          branch: gh-pages
          folder: .output/public

Instead of /my-app/, insert your github repository name again.

Enable GitHub pages for your project

Once the action finished,

Go to your project's GitHub page and on there to the settings tab
In the left menu, select pages
For branch, select gh-pages and / (Root)

It may take a few seconds up to two minutes until the pages are set up for the first time – subsequent deployments are usually a lot faster. After that, you can take a look at your freshly deployed GitHub page with your solid-start project.

Happy hacking!

Blog