Deploy a solid-start app on github pages
Published: 2024-01-11 16:53:49

[Solid-start](https://start.solidjs.com) is the long awaited meta-framework for [Solid.js](https://solidjs.com). Since it entered its second beta after a rewrite, there were a few breaking changes, so the [previous article on this one's topic](https://dev.to/lexlohr/using-solid-start-with-github-pages-3iok) 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](https://nitro.unjs.io/deploy).

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

```sh
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:

```sh
npm i
# or
pnpm i
```

## Configure vite

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

```ts
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:

```ts
      <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`:

```yaml
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!