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!