Using Solid Start with GitHub pages
Tags: solidjs, javascript, typescript, githubactions
Published: 2023-02-13 11:54:25

> ⚠ **Warning**: the information in this article is outdated. There is a new version of solid-start that contains multiple breaking changes. I have prepared an [updated article](https://dev.to/lexlohr/deploy-a-solid-start-app-on-github-pages-2l2l) for you.

You may or may not yet have heard about [Solid Start](https://start.solidjs.com/), which is the much anticipated upcoming meta framework for [Solid.js](https://www.solidjs.com/) currently being in beta.

One of the valuable features of Solid Start is that you can use so-called "adapters" to completely change the output into something deployable basically everywhere that serves pages and with quite a lot of options: there are adapters for [amazon web services](https://aws.amazon.com/), [cloudflare pages](https://pages.cloudflare.com/) and [workers](https://workers.cloudflare.com/), [deno deploy](https://deno.com/deploy), [netlify](https://www.netlify.com/), standard [node server](https://nodejs.dev/en/) (the default), [vercel](https://vercel.com/), and static deployment - the latter allows us to build something that we can put on [github pages](https://pages.github.com/).

### Creating your project

In order to create such a project, you can create your directory and from inside, use

```bash
npm init solid@latest
npm add --save-dev solid-start-static
npm remove solid-start-node
```

(or use `pnpm create/add/remove` instead of `npm` if you like that better), then choose whatever template you want to use for your project.

---

**If you are using a version of solid-start prior to 0.2.21,** you'll find an issue that prevents the initial hydration of pages with a base path different than the root. If you are using a newer version, you can skip that part and [continue below](#install-the-dependencies).

To patch solid-start, create a file called `solid-start-use-base-path-in-client-router.patch` with the following content:

```diff
diff --git a/node_modules/solid-start/entry-client/StartClient.tsx b/node_modules/solid-start/entry-client/StartClient.tsx
index c17a8e5f..6569d504 100644
--- a/node_modules/solid-start/entry-client/StartClient.tsx
+++ b/node_modules/solid-start/entry-client/StartClient.tsx
@@ -83,7 +83,7 @@ export default () => {
   return (
     <ServerContext.Provider value={mockFetchEvent}>
       <MetaProvider>
-        <StartRouter data={dataFn}>
+        <StartRouter base={import.meta.env.BASE_URL} data={dataFn}>
           <Root />
         </StartRouter>
       </MetaProvider>
```

Then add a `postinstall` script that applies the patch (this expects that you have [patch](http://savannah.gnu.org/projects/patch/) available in your path) to `package.json`:

```js
{
  "scripts": {
    "postinstall": "patch -Np1 -i solid-start-use-base-path-in-client-router.patch"
  }
}
```

Once you update to a package that includes the fix, you can safely remove the script and the patch file. If the postinstall step fails, this might be the case.

---

### Install the dependencies

Once you set up the package, install the dependencies:

```bash
npm install  # or pnpm install
```

### Configure vite

Next, you need to configure vite in `vite.config.js/ts` so that it will shape the output into something working on GitHub pages:

```js
import solid from "solid-start/vite";
import staticAdapter from "solid-start-static";
import { defineConfig } from "vite";

export default defineConfig({
  base: "/my-project/",
  // insert your github project name between slashes above
  plugins: [solid({ adapter: staticAdapter() })],
});
```

### Create a GitHub action to deploy the page

Finally, create a file `.github/workflows/main.yml` and add the following actions:

```yaml
name: CI

on:
  push:
    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

      - name: deploy pages
        uses: JamesIves/github-pages-deploy-action@v4.4.1
        with:
          branch: gh-pages
          folder: dist/public
```

Push to your repository and wait for the action to finish (have a look in the `Actions` tab of your project).

### 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. After that, you can take a look at your freshly deployed GitHub page with your solid-start project.

Happy hacking!