Forem: Alex Lohr

💎 of solid-primitives, part 3: set, map, trigger

Alex Lohr — Tue, 10 Sep 2024 07:46:00 +0000

Author: @lexlohr, developer at @crabnebuladev and Solid.js ecosystem team member

Solid.js is already pretty powerful, but even so, there are things it cannot do out of the box. Here's where the community comes in and provides packages to enhance your development experience: solid-primitives.

As the author of a few of those packages, I want to delve into our collection to present you a few gems that might end up being helpful to you. Here's the third one:

`@solid-primitives/set` / `@solid-primitives/map`

The reactive system of Solid is undisputedly its strongest point. Its simplicity allows you to shape complex reactivity with ease. Which makes it even more surprising that Set and Map are not supported out of the box by Solid's stores.

Fret not, our community got you covered with the two packages mentioned above. Manipulating a ReactiveSet or ReactiveMap will trigger all subscribed effects.

// not reactive
const [data, setData] = createStore({ set: new Set(), map: new Map() });
data.set.add('test');
data.map.set('test', 'reactivity');

// reactive
const reactive = { set: new ReactiveSet(), map: new ReactiveMap() };
reactive.set.add('test');
reactive.map.set('test', 'reactivity');

`@solid-primitives/trigger`

There might be cases where neither a map nor a set will fit your use case. If you want to make your own class instances reactive, you can use the same underlying logic as the previous two primitives:

import { createTrigger } from "@solid-primitives/trigger";

class Node<T> {
  #trigger = createTrigger();
  #data: T | undefined = undefined;
  next?: Node<T>;
  push(data: T) {
    this.next ? this.next.push(data) : (this.next = new Node(data));
  }
  pop(prev?: Node<T>): T | undefined {
    if (this.next) return this.next.pop(this);
    if (prev) prev.next = undefined;
    return this.data;
  }
  constructor(data?: T) { this.#data = data; }
  get data(): T | undefined { 
    this.#trigger[0]();
    return this.#data;
  }
  set data(data: T | undefined) {
    this.#trigger[1]();
    this.#data = data;
  }
}
class ReactiveList<T> {
  public head = new Node<T>();
  #length = 0;
  constructor(init: Iterable<T>) { 
    for (const data of init || []) this.push(data);
  }
  push(data: T) {
    this.head.push(data);
    this.#length++
  }
  pop(): T | undefined {
    this.#length && this.#length--;
    return this.head.pop();
  }
  get length() { return this.#length; }
  [Symbol.iterator]() {
    let ref: Node<T> | undefined = this.head;
    return { 
      next() {
        ref = ref?.next;
        return ref 
          ? { value: ref.data, done: false }
          : { done: true };
      }
    };
  }
}

createTrigger() returns a tuple of two functions, track and dirty. The first one subscribes effects to updates, whereas the second one will propagate updates.

In this case, having the Node handle the updates is simple, but for set and map, we cannot access the Nodes, so we have to cache the triggers based on some key. That's where the second export of this primitive, TriggerCache comes in. It is basically a Map of triggers.

This can be used for example to make a reactive Date object:

import { TriggerCache } from '@solid-primitives/trigger';

export class ReactiveDate {
  #triggers = new TriggerCache<string>();
  #date: Date;
  constructor(...init: Parameters<typeof Date>) {
    this.#date = init ? new Date(...init) : new Date();
  }
  getTime() {
    triggers.forEach(this.#triggers.track);
    return this.#date.getTime();
  }
  setTime(time: number) {
    this.#date.setTime(time);
    // helper to set all keys to dirty
    this.#triggers.dirtyAll(); 
  }
  getSeconds() {
    this.#triggers.track('second');
    return this.#date.getSeconds();
  }
  setSeconds(secs: number) {
    // this is missing a logic to handle more than 59 seconds
    this.#date.setSeconds(secs);
    this.#triggers.dirty('second');
  }
  // ...
}

Final words

We always try to provide the most utility to you, our user. If you have ideas how we could do that even better, feel free to tell us on our #solid-primitives channel in the Solid.js Discord.

Be sure to also check the first and second installment of this series in case you missed it.

Does TypeScript fail at enums?

Alex Lohr — Thu, 04 Jul 2024 12:04:02 +0000

The concept of enumerables is quite simple: an item that can represent a finite number of different things. However, the implementation in languages are very different. Some languages like Rust and F# allow enum branches to be containers other types. Most of them compile away the enums to simple numbers without leaving a trace of their use in the compiled code. TypeScript... doesn't really do well in comparison.

Consider the following enum:

enum EnumImplementations {
  Rust,
  FSharp,
  TypeScript,
}

console.log(EnumImplementation.TypeScript);

Transpilation to JavaScript will yield the following result:

var EnumImplementations;
(function (EnumImplementations) {
    EnumImplementations[EnumImplementations["Rust"] = 0] = "Rust";
    EnumImplementations[EnumImplementations["FSharp"] = 1] = "FSharp";
    EnumImplementations[EnumImplementations["TypeScript"] = 2] = "TypeScript";
})(EnumImplementations || (EnumImplementations = {}));

console.log(EnumImplementation.TypeScript);

This is a lot of complex code just to give more meaning to three numbers. Even worse, many tree shaking strategies will leave it as is.

What we would actually need for TypeScript to emit (used JSDoc for the type definition):

/**
 * enum EnumImplementation
 * @typedef {(typeof _EnumImplementation_Rust | typeof _EnumImplementation_FSharp | typeof _EnumImplementation_TypeScript)} EnumImplementation
 */
const _EnumImplementation_Rust = 0;
const _EnumImplementation_FSharp = 1;
const _EnumImplementation_TypeScript = 2;
const _EnumImplementation_Keys = ["Rust", "FSharp", "TypeScript"];

console.log(_EnumImplementations_TypeScript);

Not only has that the advantage of being easily tree-shakable, it is also more readable and concise.

That was a long rant, sorry. What's your take on the issue?

Disclaimer: please don't misunderstand me, I really like TypeScript, but this is one of its shortcomings that rather irks me.

💎 of solid-primitives, part 2: storage

Alex Lohr — Tue, 26 Mar 2024 14:31:11 +0000

As the author of a few of those packages, I want to delve into our collection to present you a few gems that might end up being helpful to you. Here's the second one

`@solid-primitives/storage`

It is a very common requirement to persist your state in some sort of storage. You can do so manually, or you use our helpful storage primitive package that provides a few helpers to make this really simple.

`makePersisted`

This is the core of the whole package. It takes the output from createSignal or createStore and returns something similar, augmented in order to persist changes:

const [state, setState] = makePersisted(createSignal(0));

It supports an optional options object to set up your storage exactly the way you need it:

{
  /** the item name under which the state is persisted */
  name?: string;
  /** a serialization function, default is JSON.stringify */
  serialize?: (data: T) => string;
  /** a deserialization function, default is JSON.parse */
  deserialize?: (data: string) => T;
  /** storage to persist state in, default is localStorage */
  storage?: 
    | Storage
    | AsyncStorage
    | StorageWithOptions<O>
    | AsyncStorageWithOptions<O>;
  /* if the storage accepts options, set them up here: */
  storageOptions?: O;
  /** sync storage (see below) */
  sync?: PersistenceSyncAPI;
};

(De-)serialization

The Web Storage API only support strings. In order to be able to persist other types, we automatically serialize the data before writing and deserialize it after reading.

Using the serialize/deserialize options, you can influence this behavior; turn it off by using a function x => x for both or use a more sophisticated (de-)serialization engine like seroval, which is also used in solid-start.

Storage selection

In most cases, localStorage is exactly the right choice, since it persists data over sessions while not sending anything to the server. But maybe you want to restrict the persistence to your current session and instead choose sessionStorage.

You don't need to restrict yourself to storage APIs that already come with your browser. You can also use external packages like localForage or another export of this package, cookieStorage.

cookieStorage behaves exactly like a normal synchronous Web Storage API, but accepts an options object for the cookie settings and also has a .withOptions method, so you can bind options and use it like a normal Storage.

It works both in the client and in the server. For solid-start, no extra configuration is needed. For other SSR implementations, you need to provide a getRequestHeaders and getResponseHeaders in the options for it to work correctly, otherwise it will always read null and never set cookies.

Lastly, in case you want to use multiple storage APIs at the same time, you can use multiplexStorage, which takes an arbitrary number of storages as arguments and returns a single storage; .setItem(key, value) and .removeItem(key) will apply to all storages, but .readItem(key) will take the first valid return value; the returned storage will be asynchronous except if the storages are all synchronous, in which case it will be synchronous, too.

Storage Sync

The Web Storage API features a storage event that triggers if the storage for the same page is changed in another frame or tab so you can update your state from it.

In order to use this for localStorage or sessionStorage, you can use storageSync:

makePersisted(createSignal(0), { sync: storageSync });

If you use one of the other storages, but want to replicate the same behavior, you can use messageSync to transmit update events over the Post Message API or the Broadcast Channel API:

makePersisted(createSignal(0), {
  storage: localForage,
  sync: messageSync(broadcastChannel)
});

If even that is not enough and you want to sync over the client/server-boundary, you can use a WebSocket connection and wsSync:

makePersisted(createSignal(0), { sync: wsSync(ws) });

To create the web socket, we also provide a websocket primitive.

Maybe you want to synchronize over your own channel, e.g. Pusher? Writing your own sync API is simple:

export type PersistenceSyncData = {
  key: string;
  newValue: string | null | undefined;
  timeStamp: number;
  url?: string;
};

export type PersistenceSyncCallback = (data: PersistenceSyncData) => void;

export type PersistenceSyncAPI = [
  /** subscribes to sync */
  subscribe: (subscriber: PersistenceSyncCallback) => void,
  update: (key: string, value: string | null | undefined) => void,
];

Or you want to synchronize your state using multiple channels, then you can use multiplexSync:

makePersisted(createSignal(0), {
  sync: multiplexSync(storageSync, wsSync(ws))
});

🛈 We have primitives for the Web Socket API and the Broadcast Channel API, so you don't have to set them up yourself. They will be presented in a later installment of this series.

Bonus features (helpers)

Maybe you are just writing your own storage, but have a hard time providing a .clear() method? Just use addClear(customStorage).

Or you have a storage that accepts options and want a .withOptions(options) method like our cookieStorage, too? We have addWithOptionsMethod(customStorageWithOptions) for that use case.

Final Words

We always try to provide the most utility to you, our user. If you have ideas how we could do that even better, feel free to tell us on our #solid-primitives channel in the Solid.js Discord.

Be sure to also check the first installment of this series in case you missed it.

💎 of solid-primitives, part 1: context

Alex Lohr — Mon, 05 Feb 2024 10:23:27 +0000

As the author of a few of those packages, I want to delve into our collection to present you a few gems that might end up being helpful to you. Here's the first one

`@solid-primitives/context`

If you, like me, make extensive use of context, you probably already know the term "context hell" or can imagine what it looks like:

<FirstContext.Provider>
  <SecondContext.Provider>
    <ThirdContext.Provider>
      <AndSoOnContext.Provider>...

Wouldn't it be better if you could just compose contexts together like this:

[FirstContext, SecondContext, ThirdContext, AndSoOnContext, ...]

`MultiProvider` to the rescue!

Long story short, it allows you to compose contexts as an array:

import { MultiProvider } from '@solid-primitives/context';

<MultiProvider values={
  [FirstContext, SecondContext, ThirdContext]}>
  ...
</MultiProvider>

Even better, you can compose contexts depending on configuration and also add values by using a tuple [Provider, values]:

const providers = [
  featureOne && FirstContext,
  SecondContext,
  featureThree && ThirdContext,
  [AndSoOnContext.Provider, providerProps]
];
return <MultiProvider values={providers}>...</MultiProvider>;

It doesn't matter if you add the context or the context.Provider, MultiProvider will automatically detect what you gave it and handle it correctly. How's that for convenience? This functionality comes at only ~213bytes increase of bundle size¹ and is especially useful for feature toggles and A/B testing.

We're not done yet, though. This package has another export:

`createContextProvider`

Since we're using a lot of context, we want to reduce the boilerplate that goes into the creation of each of them. Imagine we have a Counter component that encapsulates its state in a context:

import { useCounter } from './CounterContext';

function ContextUsingCounter() {
  const { count, increment } = useCounter();
  return <button onClick={increment}>{count()}</button>;
}

The context for such a component would probably look like this:

import { createContext, createSignal, useContext } from 'solid-js';
import { type JSX } from 'solid-js/web';

const CounterContext = createContext({});

export function CounterProvider(props: { initial?: number, children?: JSX.Elements } = {}) {
  const [count, setCount] = createSignal(props.initial ?? 0);
  const increment = () => setCount(count() + 1);
  return <CounterContext.Provider values={{ count, increment }}>
    {props.children}
  </CounterContext.Provider>;
}

export function useCounter() {
  return useContext(CounterContext)
}

Instead, we can leverage createContextProvider to wrap things for us, resulting in more concise code:

import { createContextProvider } from '@solid-primitives/context';

export const [MyContextProvider, useCounter] =
  createContextProvider((props: { initial: number }) => {
    const [count, setCount] = createSignal(props.initial);
    const increment = () => setCount(count() + 1);
    return { count, increment };
  });

Since this primitive adds ~151bytes to your bundle size¹, using it 2-3 times should already decrease your bundle size.

Final words

I hope you'll find something useful in our collection. However, if you are missing something or have problems using our primitives, don't hesitate to ask for it, either here, or - if you want a fast response - in the #solid-primitives channel of the Solid.js discord.

¹: this is the minified/gzipped size of the bundled primitive alone. Depending on your own package, there might be a slight difference in the actual increase of your bundle size, as code that is repeated often gzips better.

The zen of state in Solid.js

Alex Lohr — Wed, 24 Jan 2024 12:45:15 +0000

Cover image from https://www.pxfuel.com/en/free-photo-jsrnn

Solid.js is a frontend framework that is known for its superficial similarities and otherwise vast differences to react. One of its best parts is its signals-based state management.

What are signals?

Signals are the simplest unit of state in Solid.js. They consist of two parts: a getter function that gets the current value, and a setter function that allows updating or mutating the value:

const [value, setValue] = createSignal(0);

Behind the scenes, the getter function subscribes effects (createEffect) and computations (createMemo, JSX fields) that use the value to future updates.

createSignal accepts an options object as its second argument. Its equals property can contain false if every call of the setter, even with the same value, should trigger the subscribers, or a function that returns true if the previous and the updated value are equal, which then avoids superfluous calls of the subscribers.

However, this wonderful simplicity comes with the inability to manage partial updates to more complex state in a fine-grained way:

const [user, setUser] = createSignal({ id: 123, name: 'User Name' });
createEffect(() => console.log(user().id));
// -> 123
setUser({ id: 123, name: 'Changed Name' });
// -> 123

// splitting up the state:
const [userId, setUserId] = createSignal(123);
const [userName, setUserName] = createSignal('User Name');

As you can see, even though id has not changed, the update will trigger the effect in the variant with the object. But Solid.js has something else for more complex state; more about that later.

1st Koan: Strive for simplicity; split your state where it is sensible; use signals for simple state.

What are stores?

For those cases the state is more complex than a string, for example an array or an object, and could be partially updated, Solid.js provides stores.

const [todos, setTodos] = createStore([]);

Unlike signals, values in this example is not a function, but a proxy object that can be accessed just like the initial value. Behind the scenes, the proxy creates signals for the properties you access and makes it, so the setter will call those signals that are changed.

The setter works different, too. Instead of merely taking a new value, it can take locations as property names, array indices, or functions that return the desired location inside the current part - and only at the end, either the new value or a function to manipulate the current value:

const add = (todo) => setTodos(todos.length, todo);
const toggle = (id) => setTodos(id, 'done', done => !done);

There are also tools like produce (receives a copy of the store that can be mutated freely) or reconcile (takes a new version of the store data and checks recursively for changes) to simplify certain use cases.

2nd Koan: Solve complexity that cannot be simplified; use stores for fine-grained updates.

How can I remove an item out of an array inside a store (in the most performant way)?

The most performant way is to avoid removing the item and instead set it to undefined and ignore it in the subsequent iteration using <Show>.

setValues(pos, undefined);

However, arrays in JS have a maximum number of 2³²-2 elements, so if you have a lot of frequent changes in that array and thus are in danger of hitting that limit, you should check the length and clean up periodically using produce and Array.prototype.filter:

if (values.length > 4e9)
  setValues(produce(v => v.filter(Boolean)));

Otherwise, use the following to remove the item:

// if you know the position
setValues(produce(v => v.splice(pos, 1)));
// if you only know the item reference
setValues(reconcile(values.filter(i => i === item)));

How can I handle Maps and Sets in Solid?

Use the community packages @solid-primitives/map and @solid-primitives/set to get a map or set that is reactive on its primary level - its items are not fine-grained reactive, but you could wrap them in createMutable (see "What are mutables?").

How can I subscribe to every update of a store?

There are two ways. The simple one is to wrap the setter so that every call triggers whatever is required on any update.

If you do not control the setter, you must recursively subscribe to every single property inside the store, e.g. using the trackDeep primitive from our community's solid-primitives project.

3rd Koan: Find another angle to deal with complexity; what may be obscured for you might be obvious to others (e.g. on the Solid.js Discord).

What are mutables?

While stores have a setter function that allows changing multiple properties in a single call, there are cases where you want a fine-grained reactive object that you need to be written to, like refs in Vue.

In those cases, use createMutable, otherwise it might be better to avoid it, since it hides its reactivity, which can lead to confusion that can cause issues.

One reasonable use for mutables is to make class instances reactive:

class MyClass {
  constructor() {
    return createMutable(this);
  }
}

If you want to update mutables in the same way that stores are updated, Solid.js provides modifyMutable to do exactly that.

4th Koan: Prefer visible reactivity over invisible one; use mutables only when it is necessary.

What are memos?

In Solid.js, you can derive state using simple functions: you can take state and create a different state out of it or combine multiple states into a new one. However, effects that are subscribed to the derived state will re-run on any changes to the original state that the derived state depends on, even if the return value of the derived state will be the same.

Solid.js can avoid having to needlessly run effects by keeping the results of the derived state in memory. By wrapping your derived state in createMemo, you get a reactivity filter which will only cause effects to re-run if the return value of the resulting "memo" changes.

const [num, setNum] = createSignal(1);
const halfNoMemo = () => Math.floor(num() / 2);
const halfMemo = createMemo(halfNoMemo); 

createEffect(() => console.log('no memo', halfNoMemo()));
createEffect(() => console.log('memo', halfMemo()));

// no memo: 0, memo: 0
setTimeout(() => setNum(2), 100);
// no memo: 1, memo: 1
setTimeout(() => setNum(3), 200);
// no memo: 1

5th Koan: Use memos as a reactivity filter when you face performance issues; avoid premature optimization.

What are effects?

Effects are changes caused by state updates. This may be an HTML attribute changed by setting the state of a signal used in a JSX property (JSX properties in Solid.js, unless static, are transpiled into effects). It can also be something a function inside createEffect causes, like the console.log in the previous examples.

Effects will re-run whenever the state it uses change, unless it is untracked and thus marked not to run on updates. If you need a state only once, you can untrack it.

Solid.js provides onMount and onCleanup that allow you to run effects only once, at the start or on the disposal of a component.

While you can change state within effects, you should be aware that this can cause infinite loops and thus performance issues. If you need to handle asynchronous state, better use a resource. The next section will show you how to do that.

6th Koan: Minimize and separate state usage in effects; avoid manipulating state in effects.

What are resources?

In Solid.js, resources are a way to handle asynchronous state. It can either be single-use or repeatedly updated.

// single-use
const [data] = createResource(fetcher);

// repeated updates
const [data] = createResource(sourceGetter, fetcher);

The fetcher will only be called if data is ever used and the value stored in sourceGetter is truthy. If data() is used and the fetcher throws an error, the error will be relayed to the next <ErrorBoundary>, so unless you want that, guard uses of data() with data.error.

<Suspense> will track resources inside it and show a fallback until those are resolved. That doesn't mean a component inside may not be evaluated, so you should make sure you do not rely on data() containing anything meaningful.

7th Koan: For asynchronous state, use resources; wrap components depending on such state in <Suspense>.

How can I run an asynchronous effect before cleanup?

For a task like this, you should probably use something like the transition group primitive.

A few words

Code on and enjoy the elegance and simplicity that comes naturally with building your state with Solid.js, dear reader. I hope you enjoyed your stay here.

Deploy a solid-start app on github pages

Alex Lohr — Thu, 11 Jan 2024 16:53:49 +0000

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!

Using Solid Start with GitHub pages

Alex Lohr — Mon, 13 Feb 2023 11:54:25 +0000

⚠ 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

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

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"
  }
}

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

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() })],
});

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

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!

Concepts behind modern frameworks

Alex Lohr — Mon, 19 Dec 2022 11:26:42 +0000

Many beginners ask "which framework should I learn?" and "How much JS or TS do I need to learn before a framework?" - countless opinionated articles go into promoting the advantages of the author's preferred framework or library, instead of demonstrating the readers the concepts behind them to allow for an informed decision. So let us get the second question out of the way first:

"How much JS/TS to learn before a framework?"

As much as allows you to understand the concepts they are based on. You will need knowledge of the basic data types, functions, basic operators and of the document object model (DOM), which is the representation of your HTML and CSS inside your JS. While everything beyond that will not hurt, it is not strictly required to become proficient with a framework or library.

If you are a complete beginner, JS for cats might be a good resource for your first steps. Keep going until you feel confident, then continue until you stop feeling confident again. That's when you know enough JS/TS and can move on to a framework. The rest you can learn on the go.

"Which concepts do you mean?"

State
Effects
Memoization
Templating and rendering

All modern frameworks derive their functionality from these concepts.

State

State is just the data powering your application. It may be on a global level, for a larger part of the application, or for a single component. Let us take a simple counter as an example. The count it keeps is the state. We can read the state and write to it to increase the count.

The simplest representation is usually a variable containing the data that our state consists of:

let count = 0;
const increment = () => { count++; };
const button = document.createElement('button');
button.textContent = count;
button.addEventListener('click', increment);
document.body.appendChild(button);

But this code has a problem: changes to count, like those made by increment, are not updating the text content of the button. We could manually update everything, but that doesn't scale well for more complex use cases.

The ability for count to update its users is called reactivity. This works by subscribing and re-running the subscribed parts of your application to updates.

Almost every modern front-end framework and library has a way to manage state reactively. There are three parts to the solution, and at least one of them or a mix is employed:

Observables / Signals
Reconciliation of immutable updates
Transpilation

Observables / Signals

Observables are basically structures that allow to read via a function that subscribes the readers. The subscribers are then re-run on update:

const state = (initialValue) => ({
  _value: initialValue,
  get: function() {
    /* subscribe */;
    return this._value; 
  },
  set: function(value) {
    this._value = value;
    /* re-run subscribers */;
  }
});

One of the first uses of this concept was in knockout, which used the same function with and without arguments for write/read access.

This pattern is currently seeing a revival as signals, for example in Solid.js and preact signals, but the same pattern is used under the hood of Vue and Svelte. RxJS, which powers the reactive layer of Angular, is an extension of this principle beyond simple state, but one could argue that its ability to model complexity is a whole arsenal of guns aimed at your feet. Solid.js also comes with further abstractions of these signals in the form of stores (objects that can be manipulated through a setter) and mutables (objects that can be used like normal JS objects or the state in Vue to handle nested state objects.

Reconciliation of immutable states

Immutability means that if the property of an object changes, the whole object reference must change, so a simple comparison of references can easily detect if there are changes, which is what the reconciler does.

const state1 = {
  todos: [{ text: 'understand immutability', complete: false }],
  currentText: ''
};
// updating the current text:
const state2 = {
  todos: state1.todos,
  currentText: 'understand reconciliation'
};
// adding a to-do:
const state3 = {
  todos: [
    state.todos[0],
    { text: 'understand reconciliation', complete: true }
  ],
  currentText: ''
};

// this breaks immutability:
state3.currentText = 'I am not immutable!';

As you can see, references of unchanged items are re-used. If the reconciler detects different object references, it runs all components using the state (props, memos, effects, context) again. Since the read access is passive, this requires the manual specification of dependencies to reactive values.

Obviously, you are not defining state that way. You either construct it from existing properties or use a so-called reducer. A reducer is a function that takes one state and returns another one.

This pattern is used by react and preact. It lends itself to being used with a vDOM, which we will explore later when templating is described.

Not every framework uses its vDOM to make the state fully reactive. Mithril.JS, for example, updates from state changes after the events set in the component; otherwise you have to trigger m.redraw() manually.

Transpilation

Transpilation is a build step that rewrites our code to make it run on older browsers or give it extra abilities; in this case, the technique is employed to change a simple variable into a part of a reactive system.

Svelte is based on a transpiler that also powers their reactive system from seemingly simple variable declaration and access.

As an aside, Solid.js uses transpilation, but not for its state, only for the templating.

Effects

In most cases, we need to do more with our reactive state than deriving from it and render it into the DOM. We have to manage side effects, which are all things that happen due to state changes beyond updates to the view (though some frameworks like Solid.js treat view changes as effects as well).

Remember the first example from state where the subscription handling was intentionally left out? Let us fill this in to handle effects as a reaction to updates:

const context = [];

const state = (initialValue) => ({
  _subscribers: new Set(),
  _value: initialValue,
  get: function() {
    const current = context.at(-1);
    if (current) { this._subscribers.add(current); }
    return this._value;
  },
  set: function(value) {
    if (this._value === value) { return; }
    this._value = value;
    this._subscribers.forEach(sub => sub());
  }
});

const effect = (fn) => {
  const execute = () => {
    context.push(execute);
    try { fn(); } finally { context.pop(); }
  };
  execute();
};

This is basically a simplification of the reactive state in preact signals or Solid.js without error handling and state mutation pattern (using a function that receives the previous value and returns the next), but that would be easy to add.

It allows us to make the previous example reactive:

const count = state(0);
const increment = () => count.set(count.get() + 1);
const button = document.createElement('button');
effect(() => {
  button.textContent = count.get();
});
button.addEventListener('click', increment);
document.body.appendChild(button);

☝ Try out the above two code blocks in an empty page using your developer tools.

In most cases, the frameworks allow for different timings to let the effects run before, during or after rendering the DOM.

Memoization

Memoization means caching of values computed from state, to be updated when the state it is derived from changes. It is basically an effect that returns a derived state.

In frameworks that re-run their component functions, like react and preact, this allows to opt out parts of the components again when the state it depends on does not change.

For other frameworks, it is the opposite: it allows you to opt in parts of the component to reactive updates, while caching the previous computation.

For our simple reactive system, memo looks like this:

const memo = (fn) => {
  let memoized;
  effect(() => {
    if (memoized) {
      memoized.set(fn());
    } else {
      memoized = state(fn());
    }
  });
  return memoized.get;
};

Templating and rendering

Now that we have state in pure, derived and cached form, we want to show it to the user. In our example, we used the DOM directly to add a button and update its text content.

To be more developer-friendly, almost all modern frameworks support some domain-specific language to write something similar to the desired output inside your code. Even though there are different flavors, like .jsx, .vue or .svelte files, it all comes down to a representation of the DOM in code that resembles HTML, so that basically

<div>Hello, World</div>

// in your JS
// becomes in your HTML:

<div>Hello, World</div>

"Where do I put my state?" you may ask. Excellent question. In most cases, {} are used to express dynamic content, both in attributes and around nodes.

The most used templating language extension to JS is undoubtedly JSX. For react, it is compiled to plain JavaScript in a way that allows it to create a virtual representation of the DOM, an internal view state called virtual document object model or vDOM for short.

This is based on the premise that creating objects is much, much faster than accessing the DOM, so if you can replace the latter with the current, you save time. However, if you either have numerous DOM changes in any case or create countless objects for no changes, the benefits of this solution are easily turned into a disadvantage that has to be circumvented through memoization.

// original code
<div>Hello, {name}</div>

// transpiled to js
createElement("div", null, "Hello, ", name);

// executed js
{
  "$$typeof": Symbol(react.element),
  "type": "div",
  "key": null,
  "ref": null,
  "props": {
    "children": "Hello, World"
  },
  "_owner": null
}

// rendered vdom
/* HTMLDivElement */<div>Hello, World</div>

JSX is not limited to react, though. Solid, for example, uses its transpiler to change the code more drastically:

// 1. original code
<div>Hello, {name()}</div>

// 2. transpiled to js
const _tmpl$ = /*#__PURE__*/_$template(`<div>Hello, </div>`, 2);
(() => {
  const _el$ = _tmpl$.cloneNode(true),
    _el$2 = _el$.firstChild;
  _$insert(_el$, name, null);
  return _el$;
})();

// 3. executed js code
/* HTMLDivElement */<div>Hello, World</div>

While the transpiled code may look daunting at first, it is rather simple to explain what happens here. First, the template with all the static parts is created, then it is cloned to create a new instance of its contents and the dynamic parts are added and wired to update on state changes.

Svelte goes even further and transpiles not only the templates, but also the state.

// 1. original code
<script>
let name = 'World';
setTimeout(() => { name = 'you'; }, 1000);
</script>

<div>Hello, {name}</div>

// 2. transpiled to js
/* generated by Svelte v3.55.0 */
import {
        SvelteComponent,
        append,
        detach,
        element,
        init,
        insert,
        noop,
        safe_not_equal,
        set_data,
        text
} from "svelte/internal";

function create_fragment(ctx) {
        let div;
        let t0;
        let t1;

        return {
                c() {
                        div = element("div");
                        t0 = text("Hello, ");
                        t1 = text(/*name*/ ctx[0]);
                },
                m(target, anchor) {
                        insert(target, div, anchor);
                        append(div, t0);
                        append(div, t1);
                },
                p(ctx, [dirty]) {
                        if (dirty & /*name*/ 1) set_data(t1, /*name*/ ctx[0]);
                },
                i: noop,
                o: noop,
                d(detaching) {
                        if (detaching) detach(div);
                }
        };
}

function instance($$self, $$props, $$invalidate) {
        let name = 'World';

        setTimeout(
                () => {
                        $$invalidate(0, name = 'you');
                },
                1000
        );

        return [name];
}

class Component extends SvelteComponent {
        constructor(options) {
                super();
                init(this, options, instance, create_fragment, safe_not_equal, {});
        }
}

export default Component;

// 3. executed JS code
/* HTMLDivElement */<div>Hello, World</div>

There are exceptions. In Mithril.js, for example, while it is possible to use JSX, you are encouraged to write JS:

// 1. original JS code
const Hello = {
  name: 'World',
  oninit: () => setTimeout(() => {
    Hello.name = 'you';
    m.redraw();
  }, 1000),
  view: () => m('div', 'Hello, ' + Hello.name + '!')
};

// 2. executed JS code
/* HTMLDivElement */<div>Hello, World</div>

While most people will find the developer experience lacking, others prefer full control over their code. Depending on which issue they aim to solve, the lack of a transpilation step might even be beneficial.

Many other frameworks allow for usage without transpilation, though it is rarely recommended like that.

"And what framework or library should I learn now?"

I have some good news and some bad news for you.

The bad news is: there is no silver bullet. No framework will be much better than all others in every single aspect. Each one of them has their advantages and compromises. React has its hook rules, Angular a lack of simple signals, Vue lacks backwards compatibility and Svelte don't scale too well, Solid.js forbids destructuring and Mithril.js is not really reactive, just to name a few.

The good news is: there is no wrong choice – at least, unless the requirements of a project are really limited, be it in terms of bundle size or performance. Every framework will do its job. Some may require working around their design decisions, which might slow you down a bit, but you should be able to get a working result in any case.

That being said, going without a framework might be a viable choice, too. Many projects are spoiled by overuse of JavaScript, when static pages with a sprinkle of interactivity would have done the job as well.

Now that you know the concepts that are applied by these frameworks and libraries, choose those which are the best fit for your current task. Do not be afraid to switch frameworks in your next project. It is not necessary to learn all of them.

If you try a new framework, one of the things I found most helpful is to connect to its community, be it on social media, discord, github or elsewhere. They can tell you which approaches are idiomatic for their framework, which will help you to get better solutions faster.

"Come on, you must have a personal preference!"

If your main goal is to become employed, I would suggest learning react. If you want a great experience of effortless performance and control, try Solid.js; you might meet me on Solid's Discord.

But please bear in mind that all other choices are equally valid. You should not choose a framework because I say so, instead use one that works best for you.

If you got through the whole text, thank you for your patience. I hope it was helpful for you. Leave a comment while you're here and have a nice day!

About criticism

Alex Lohr — Wed, 20 Jul 2022 11:58:39 +0000

Everybody is a critic. Every developer has both been on the receiving and the giving end of criticism. It is a vital part of our job, be it as code review, comments on social networks like this one or during a retrospective. So let us have a look at both sides of criticism:

Taking criticism

First, we should distinguish actual criticism from fallacious arguments (reasonings that are logically invalid) like ad hominems (personal attacks instead of making a point about the code/article/argument: "You don't have the experience to understand this") or false dichotomy (presenting a choice of two options when there are actually more: "You can either use Vue or React.") and point them out:

"Please no ad hominems, let us concentrate on the argument/code instead."
"That is a false dichotomy, one could also use a multitude of other frameworks and libraries!"

Next, acknowledge valid criticism, regardless if constructive or not. Even unconstructive criticism can be helpful to sharpen your arguments or provide a new point of view to think about your code. If you feel unjustly criticized, please keep it to yourself - complaining about it merely makes you look insecure; try to keep your ego out of the discussion.

"Thank you for your comment."

There's no shame in admitting being wrong, as long as you don't remain wrong. Telling your critics:

"Thank you for correcting my previously wrong position."

is one of the strongest moves you can make in any discussion.

Lastly, try to find an action to derive from the criticism: how can you use the criticism to improve your code, article or argument? If that doesn't work, directly ask the critic if they could offer actionable advice:

"Do you have any suggestion how I can improve this?".

That will usually either shut them up or may otherwise result in chances for actual improvement. Either way, you win.

That's it. You've handled the criticism in a measured and professional manner. Well done!

Giving criticism

What is there to gain from giving criticism? Is this just satiating your urge to be right? Or the wish to convince others to stand for your cause? Do you expect an insightful and civilized discussion to sharpen your arguments? Do you even want recognition as an expert in the field?

Whatever your goal is, avoid a discussion if it is obvious that you will fail to achieve it. Don't fall for the sunk cost fallacy (throwing away your time because you already started doing so) and continue a discussion after it becomes clear that you will not achieve it. If in doubt, getting out of a discussion is simpler than you think: just say your good-bye and refrain from commenting further. You might feel pressed to answer to comments or even slurs that follow - don't. It is not worth your time and slurs reflect more on those giving them than those targeted.

Otherwise, make it worth the use of your time and the one on the receiving end: constructive criticism is always preferable, but occassionally, destructive criticism may be warranted if starting from scratch is the only way forward. Good criticism fulfils three requirements: it is logically sound, is free from ego and is actionable for the recipient:

Logical soundness

As we already learned when looking at taking criticism, arguments should be logically sound, so refrain from fallacies.

👎 "Everyone is using React and so should you!"

👍 "React has a large ecosystem that will help you finish your project faster."

Free from ego

Arguments should be objective, not only in content, but also in form:

👎 "I would use recursion for that if I were you."

👍 "This task lends itself to a recursive approach."

Actionable

The best criticism is one the recipient can act on:

👎 "This is so bad, it can't even be improved!"

👍 "Instead, you can use the builder pattern if you happen to rewrite this."

External sources to support your point should be included both for strenghtening your point as well as a chance to learn more about the topic.

Have you already made your criticism? Great. Now it may become the subject of other people's criticism itself and you could be on the receiving side again. And that's a good thing.

Final words

🙏 "Thank you for the time you took reading this."

You probably knew all that already and are only here to criticise this post. Go for it, it can only become better from your criticism. Or maybe this helps as a small reminder for you to improve? Wonderful. Either way, have a nice day!

Discuss: package sabotage

Alex Lohr — Tue, 22 Mar 2022 12:16:12 +0000

(image copyright by Ministry of Defense of Ukraine, shared on flickr under CC-AT-SA)

Like any war, the current one in the Ukraine brings out the best and the worst in people. The best of us support the people of the Ukraine defending against the unlawful invasion by the Russian Regime. The worst of us commit package sabotage against users with a russian IP address.

On one hand, package sabotage is two-edged sword, as you cannot possibly know if the Russian IP currently installing your npm package is not actually against the war and just wanted to set up a site to spread knowledge on how to circumvent Russian net blockades – and now you've successfully stopped them from doing so and indirectly aided Russian Propaganda to prevail in the absence of that information. On the other hand, you undermine the global trust in the whole ecosystem that your package is a tiny part of.

For that reason, I'm rather convinced it's ultimately a really bad idea, but I wanted to hear your positions, too. What do you think about package sabotage? Also, shouldn't we be more mindful of the dependencies we pull from npm?

Testing your Solid.js code in vitest

Alex Lohr — Tue, 22 Feb 2022 08:43:11 +0000

Some time has passed since I showed you how to test your Solid.js code with jest and uvu or tape, but now there's another solution that I don't want you to waste time to research yourself: vitest.

You may have heard of vite, the slim fast dev server that scored an amazing as deserved 98% satisfaction on the state of js survey 2021. It's creators found unit testing too cumbersome and slow and decided to add their own perspective to the task. The result is vitest: it runs a vite server under the hood to transform the code to test as fast as possible, uses an enhanced flavor of chai to have jest-compatible assertions, integrates DOM mocking using jsdom or happy-dom and even the tiny-spy library that was just built as a separate library to allow for easy reuse is small and compatible with jest.

Setup

First, you need to add vitest and jsdom to your dev dependencies:

npm i --save-dev vitest jsdom

Then, your vite.config.js (or vitest.config.js if you want to have a different setup for testing) needs to look similar to this:

/// <reference types="vitest" />
/// <reference types="vite/client" />

import { defineConfig } from 'vite'
import solid from 'solid-start' // or 'vite-plugin-solid'

export default defineConfig({
  test: {
    environment: 'jsdom',
    transformMode: {
      web: [/\.[jt]sx?$/],
    },
    // solid needs to be inline to work around
    // a resolution issue in vitest:
    deps: {
      inline: [/solid-js/],
    },
    // if you have few tests, try commenting one
    // or both out to improve performance:
    // threads: false,
    // isolate: false,
  },
  plugins: [solid()],
  resolve: {
    conditions: ['development', 'browser'],
  },
})

If you already have a vite.config.js, all you need to add is the test section and make sure that the correct conditions are set in resolve.

Lastly, you should add a script to your package.json to allow for testing:

{
  "scripts": {
    "test": "vitest"
  }
}

How to test?

Actually, vitest is 95% compatible with jest, so I'll just send you to the corresponding part of the jest guide. Obviously, it won't let you run the jest transpilation pipeline, but everything else should be there.

Code coverage is provided by c8; unfortunately, even vitest cannot fix the issue in babel's handling of source maps that doesn't allow us to collect coverage from Solid.js components.

How fast is it?

For all the promises of being blazing fast, vitest is slower than uvu and it can actually be as slow as jest for the first run of a suite containing very few test cases. Once you have more than 5-10 tests and can really use the watch mode, it easily outperforms jest, even though it will only be faster than uvu if it can omit enough test cases in a run (though to be fair, this is mostly because uvu lacks a lot of features that vitest provides).

Also, you should consider that vitest is still in development, so performance improvements shouldn't be unexpeced.

If you are currently using jest and don't like waiting for test results, you should definitely consider vitest; if you only have a really small test suite of less than 5 tests and don't need advanced features like a sophisticated watch mode and extendable assertions, uvu/solid-register will be faster, though it won't be nearly as comfortable as vitest.

A new paradigm

Alex Lohr — Sun, 20 Feb 2022 18:07:54 +0000

I witnessed the rise of a new paradigm in the world of JS development that surprised me: frugality.

We've all seen enough of the opposite. Pulling a new dependency in our project more often than not takes some time, because it's megabytes of code and uses some more dependencies itself and before you realize it, node_modules fills your disk space faster than unrotated log files.

It's ok, you'll say, it's just tooling, not the code that appears in the user's browser. But wouldn't it be great if everything was just a bit leaner, faster and more self-reliant?

This question is apparently asked by an increasing number of people. A few of them are the authors of the upcoming testing framework vitest. While during development they used parts of jest and more heavyweight dependencies, most of them were either replaced by internal code or more lightweight, reusable modules.

Then, there's goober, a minimalistic framework-agnostic css-in-js component library. You'll probably find more examples of modern yet frugal tools and libraries.

Less code will statistically also contain less bugs and it is good for performance, too. The less code there's to parse, the faster the startup. I invite you to consider this new paradigm for your own packages, too.

Forem: Alex Lohr

💎 of solid-primitives, part 3: set, map, trigger

@solid-primitives/set / @solid-primitives/map

@solid-primitives/trigger

Final words

Does TypeScript fail at enums?

💎 of solid-primitives, part 2: storage

@solid-primitives/storage

makePersisted

(De-)serialization

Storage selection

Storage Sync

Bonus features (helpers)

Final Words

💎 of solid-primitives, part 1: context

@solid-primitives/context

MultiProvider to the rescue!

createContextProvider

Final words

The zen of state in Solid.js

What are signals?

What are stores?

How can I remove an item out of an array inside a store (in the most performant way)?

How can I handle Maps and Sets in Solid?

How can I subscribe to every update of a store?

What are mutables?

What are memos?

What are effects?

What are resources?

How can I run an asynchronous effect before cleanup?

A few words

Deploy a solid-start app on github pages

Creating your project

Install the dependencies

Configure vite

Configure the Router

Create a github action to deploy the page

Enable GitHub pages for your project

Using Solid Start with GitHub pages

Creating your project

Install the dependencies

Configure vite

Create a GitHub action to deploy the page

Enable GitHub pages for your project

Concepts behind modern frameworks

"How much JS/TS to learn before a framework?"

"Which concepts do you mean?"

State

Observables / Signals

Reconciliation of immutable states

Transpilation

Effects

Memoization

Templating and rendering

"And what framework or library should I learn now?"

"Come on, you must have a personal preference!"

About criticism

Taking criticism

Giving criticism

Logical soundness

Free from ego

Actionable

Final words

Discuss: package sabotage

Testing your Solid.js code in vitest

Setup

How to test?

How fast is it?

A new paradigm

`@solid-primitives/set` / `@solid-primitives/map`

`@solid-primitives/trigger`

`@solid-primitives/storage`

`makePersisted`

`@solid-primitives/context`

`MultiProvider` to the rescue!

`createContextProvider`