DEV Community

Cover image for Using Solid Start with GitHub pages
Alex Lohr
Alex Lohr

Posted on • Updated on

Using Solid Start with GitHub pages

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 for you.

You may or may not yet have heard about Solid Start, which is the much anticipated upcoming meta framework for Solid.js 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, cloudflare pages and workers, deno deploy, netlify, standard node server (the default), vercel, and static deployment - the latter allows us to build something that we can put on github pages.

Creating your project

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

npm init solid@latest
npm add --save-dev solid-start-static
npm remove solid-start-node
Enter fullscreen mode Exit fullscreen mode

(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.

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

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>
Enter fullscreen mode Exit fullscreen mode

Then add a postinstall script that applies the patch (this expects that you have patch available in your path) to package.json:

{
  "scripts": {
    "postinstall": "patch -Np1 -i solid-start-use-base-path-in-client-router.patch"
  }
}
Enter fullscreen mode Exit fullscreen mode

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:

npm install  # or pnpm install
Enter fullscreen mode Exit fullscreen mode

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:

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() })],
});
Enter fullscreen mode Exit fullscreen mode

Create a GitHub action to deploy the page

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

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
Enter fullscreen mode Exit fullscreen mode

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!

Top comments (21)

Collapse
 
welschmoor profile image
welschmoor

After npm init solid@latest I see some astro stuff, they must've changed things.

Collapse
 
lexlohr profile image
Alex Lohr

Yes, the new solid start version is now based on astro. The rest should work the same, though.

Collapse
 
welschmoor profile image
welschmoor • Edited

I tried with the older vite version and after deploying to github all I see is the Readme.MD :D

I am so bad at this, no idea what I am doing wrong.

BTW do you know where I can get the latest news (such as an explanation of why they now use astro). I've never used astro so I don't know what good or bad it does. All I see is close to 40KB of JavaScript on a new project, which I don't like :D

Thread Thread
 
lexlohr profile image
Alex Lohr

I daresay this article needs to be updated soon... I'm a bit short on time at the moment, though.

Thread Thread
 
welschmoor profile image
welschmoor

I'd like to mention that your article is very important to us. Thank you for sharing your knowledge!

Thread Thread
 
welschmoor profile image
welschmoor

Hey,

today I started a new project and no astro any longer... 17kB JS being sent to the browser.

Thread Thread
 
lexlohr profile image
Alex Lohr

I can share a bit of insider knowledge here: the porting of solid-start to Astro has hit a few snags and is therefore abandoned, the core team is currently testing a few other approaches while pushing the work done before forward that couldn't be merged because it was mostly experimental. In the meantime, Ryan explores ways to resume SSR-rendered components: hackmd.io/@0u1u3zEAQAO0iYWVAStEvw/...

While it might seems things are slow, they are actually moving in a surprisingly fast pace, just in many different directions at once and not as open as one would wish for.

Collapse
 
lexlohr profile image
Alex Lohr

Small update: solid-start 0.2.21 is released, so you can now use that and skip the patching step.

Collapse
 
chrisspotless profile image
Chrisspotless

@lexlohr
This is awesome,and it;s indeed so detailed.

Collapse
 
amustafa16421 profile image
Mustafa_A

Indeed.
He is very passionate about Solid.js ^^

Collapse
 
thetarnav profile image
Damian Tarnawski

You've left in the gh action, is that intentional?

  pull_request:
    branches: [ main ]
Enter fullscreen mode Exit fullscreen mode
Collapse
 
lexlohr profile image
Alex Lohr

I knew I had forgotten something. Thanks.

Collapse
 
gregv21v profile image
Gregory Venezia

When I try to view the website I get a 404 error.

Collapse
 
gregv21v profile image
Gregory Venezia

I resolved this issue. I just had to wait until GitHub pages loaded the files.

Collapse
 
lexlohr profile image
Alex Lohr

Thanks for the feedback. There is currently an issue with SolidStart, Ryan is just preparing a new release.

Collapse
 
theslantedroom profile image
Steve Yee • Edited

Configure vite Step has changed.

import solid from "solid-start/vite";
import static 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: static() })],
});
Enter fullscreen mode Exit fullscreen mode

needs to be

import solid from "solid-start/vite";
import solidStatic 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: solidStatic() })],
});
Enter fullscreen mode Exit fullscreen mode

further more, github actions might fail if you do not give permission to the github-pages-deploy-action
as such update the yml to:

name: CI
permissions:
  contents: write

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
Enter fullscreen mode Exit fullscreen mode

see Read and Write Permissions in:
github.com/JamesIves/github-pages-...

Collapse
 
lexlohr profile image
Alex Lohr

From what I can see, you only changed the default import name of the static adapter. There is no functional change whatsoever.

Collapse
 
theslantedroom profile image
Steve Yee • Edited

Maybe so but strict mode reserves the name 'static', and as such for me the app failed to launch. True we could call the import bananas, so long as it's not 'static'

Thread Thread
 
lexlohr profile image
Alex Lohr

Thanks for the feedback, I've changed the name.

Collapse
 
birkskyum profile image
Birk Skyum • Edited

Can you use npm run start to preview the build locally before pushing to github pages, or does the assets in your case also load from the wrong url?

When I do npm run start, the client try to fetch localhost:55775/github-repo-name/a..., but it actually exist at localhost:55775/assets/entry-clien...

Collapse
 
joshuarossi profile image
Josh Rossi

I am just trying to build the actual static site and that keeps failing. It says the following:

file:///Users/joshrossi/Code/LendingUI/node_modules/rollup/dist/es/shared/node-entry.js:2287
        base = Object.assign(new Error(base.message), base);
                             ^

Error [RollupError]: "template" is not exported by "node_modules/solid-simple-table/node_modules/solid-js/web/dist/server.js", imported by "node_modules/solid-simple-table/dist/SimpleTable.mjs".
Enter fullscreen mode Exit fullscreen mode

My vite config is like this

import solid from "solid-start/vite";
import solidStatic from "solid-start-static";
import { defineConfig } from "vite";

export default defineConfig({
  base: "/src/",
  // insert your github project name between slashes above
  plugins: [solid({ adapter: solidStatic() })],
});
Enter fullscreen mode Exit fullscreen mode

This is really really making me hate SSR. I just want to build the pages, I can deal with hosting etc