DEV Community: José Pablo Ramírez Vargas

Now that TypeScript is about to be blazing fast, what do JsDoc lovers think about this? This pretty much takes away the one complaint they had. Will you still go JsDoc? Or will you migrate to TS?

José Pablo Ramírez Vargas — Sun, 16 Mar 2025 19:26:16 +0000

The Ugly Truth: All Popular fetch() Wrappers Do It Wrong

José Pablo Ramírez Vargas — Tue, 11 Mar 2025 03:19:30 +0000

Please have a look at the following two pieces of code. The purpose is to do something (writing to the console) if the value of x is false.

const x = false;
try {
    if (!x) {
        throw new Error("x is false");
    }
}
catch {
    console.log('x is false');
}


const x = false;
if (!x) {
    console.log('x is false')
}

What can we say about these two when we compare them? In a nutshell, we can declare the first one madness. Why would I want to throw just because some variable’s value is false? Clearly, I should do as the second script does: Simple branching.

Well, if you use axios, ky or literally any other fetch() wrapper that throws on non-OK responses, then you’re walking the path of madness.

The Problem

This is evident when simplifying the issue as we did above: The problem is using try..catch as a branching mechanism. But does this matter? Turns out that it does.

This benchmark compares the madness route with regular branching, and the performance loss is huge: About 40% slower if you do madness:

This is true for most (or all, perhaps) runtimes: Throwing is an expensive operation because callstack unwinding is expensive.

I know, nay-sayers will comment on this post and say, “that’s the minority of the cases, almost always response.ok is true so this doesn’t matter”, and it’s a statement with substance. But do you know what’s even better? NOT THROWING. Stop using try..catch as a branching mechanism. It is not its function.

It is mind-blowing how long this awful detail has gone unnoticed.

Is that It?

Well, how do you feel about being forced to write more code because you were sold the idea that interceptors are a cool thing? Don’t believe it? Let’s find out.

TASK: Create code that fetches data. Make sure the fetcher object/function always include the JWT in the Authorization header.

Pretty standard stuff. Fetching 101, if this were a college course.

Using ky

Taken from their README and modifying a bit:

import ky from 'ky';

export const api = ky.extend({
    hooks: {
        beforeRequest: [
            request => {
                request.headers.set('Authorization', `Bearer ${getToken()}`);
            }
        ]
    }
});

Writing a myFetch Function

The same thing with none of these packages:

export function myFetch(url, options) {
    options.headers = { ...options.headers, Authorization: `Bearer ${getToken()}` };
    return fetch(url, options);
}

Was I lying? Is it not more code with ky?

“More code” is not the only consequence: By using ky, you are forcing the developers that maintain your project to learn ky’s API. You’re asking people to learn an API that works against the project’s best interests of performance and maintainability, in exchange for … ? Why, again, are you using ky or axios or any other that behaves like this?

The Solution

The solution is obvious: The standardized fetch() API does a great job on its own. Most of your small to medium-sized projects won’t need anything else. Just write a customized data-fetching function based on fetch() and you’re good to go.

“But I need progress, and plug-ins, and other fancy stuff”. You might, I agree. Search the NPM registry thoroughly. For example, you can find at least one NPM package that allows for progress using fetch(). Other “fancy” requirements could probably be fulfilled just as well.

Is your need still not fulfilled? Search for a good wrapper. I’ll save you the trouble: Because I’m pretty sure I’m the only one in the world that complains about all this, my wrapper dr-fetch is most likely the only wrapper I can recommend.

dr-fetch builds upon the idea of a customized data-fetching function, and it has a unique feature not found in any other wrapper in the world: It lets you type the HTTP response’s body depending on the HTTP status code:

// fetcher.ts
import { DrFetch, setHeaders } from 'dr-fetch';

function myFetch(url: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) {
    init ??= {};
    setHeaders(init, {
        Accept: 'application/json',
        Authorization: `Bearer ${getToken()}`,
    });
    return fetch(url, init);
}

export default new DrFetch(myFetch);

//Consume the exported object and fetch:
import fetcher from './fetcher.js';

const response = await fetcher
    .for<200, MyData[]>()
    .for<401, undefined>()
    .for<400, ValidationError[]>()
    .fetch('/api/data/?sort=desc');

// The response object is now strongly-typed for status codes 200, 400 and 401:
// TypeScript narrowing will work properly:
if (response.status === 200) {
    console.log('Data: %o', response.body.map(x => x.id));
}
else if (response.status === 400) {
    console.log('Errors: %s', response.body.map(error => error.message).join('\n'));
}
else if (response.status === 401) {
    deleteSavedToken();
}

Do you see how nice the above code is? Simple branching, and not a single try..catch in sight (or callbacks or whatever abstraction other wrappers use for interceptors).

NOTE: You would need a try..catch for network errors, like DNS failure, disconnection and the like, but not for business logic.

I don’t claim to be an expert at “fancy” fetching things, but if you open an issue in the repository, I will answer you. Feel free to ask for features that you think might be good. You are welcome to contribute directly, if that’s your preference.

UPDATE: Just to give you an idea of how easy and powerful dr-fetch’s approach is, I made a Svelte REPL that adds download progress very easily.

Svelte Reactivity: Let's Talk About $Effects

José Pablo Ramírez Vargas — Wed, 19 Feb 2025 21:31:40 +0000

In the previous article of the series, we learned the basics of Svelte v5’s reactivity system: The basic runes. We learned that this version of Svelte now reacts to things in runtime rather than depending on the static code analysis provided in previous versions. But what does this mean? Let’s find out.

The $effect Rune in Detail

Before we can talk about effects, let’s remind us about proxies in JavaScript: Proxies are objects that take the place of other objects in order to intercept calls to its methods and properties. This is what goes on in Svelte v5 when you use reactivity: Things like $state create proxies for you. These proxies are then programmed in such a way that they can “report” to a central location in the Svelte runtime whenever they are being read (their value is being accessed). This is the basis of effects, and reactivity overall.

Whenever we create an effect with the $effect rune, we are setting up a “recorder” of reactive value reads. Let’s see an example:

<script lang="ts">
    let count = $state(0);

    $effect(() => {
        if (count >= 5) {
            window.open('/some/url');
        }
    });
</script>

<button type="button" onclick={() => ++count}>
    Click me
</button>

The component above sets an effect up in such a way that a pop-up comes up whenever the button is clicked 5 or more times. The first line of the effect’s code (the IF statement) reads the reactive variable count and the recorder picks up this fact. Now the Svelte runtime knows that whenever the count variable’s value changes, the effect must be re-run because it depends on this reactive variable’s value.

This recording takes place every time the effect is run: The previous set of recorded reactive values (if any) is discarded, and a new recording takes place, every time the effect is re-run.

IMPORTANT: The above is critical. Debugging effects is tricky and knowing the above will help you heaps if you ever need to figure out why an effect is not running when (you believe) it should.

So, there you go, one of the most vital pieces of information about effects just fell on your lap.

The $inspect.trace() Rune

This is a new rune available in Svelte v5.14.0 and above and is meant to help troubleshoot effects and derived values. When used inside the function body of an $effect or a $derived.by rune, it outputs the reactive signals that were read during the run. Furthermore, the signals that changed and made the effect to re-run will be highlighted in light blue (colorblind people, kindly file an issue with Svelte because this color indicator is the only indicator available). On first run, all signals will be light blue.

IMPORTANT: The documentation about this rune is plain wrong, in my opinion. It reads “information will be printed to the console about which pieces of reactive state caused the effect to fire.”, which is not true. It should read “information about the read signals will be printed to the console, with the pieces of reactive state that caused the effect to fire highlighted in light blue color.”.

To give you an idea of how the output looks like, I added the line $inspect.trace(‘seggregatedColumns’); to the calculation of the seggregatedColumns value in @wjfe/dataview and this is the initial console output:

As numbered in the screenshot:

#1: It shows the amount of time taken to complete the operation.
#2, #3: It shows the type of reactive signal.
#4, #5: It shows the reactive signal’s value.

Watch-Outs!

There are a few cases worth noting where you might have trouble “seeing” because they are not immediately obvious.

Branching

One of the more common gotcha’s is to think that an effect will run based on a reactive value, but this is not happening because the value wasn’t really read the last (first) time the effect executed.

This next example uses a “control” Boolean variable that disallows the running of the effect the very first time the effect is run, maybe because you want to save an HTTP request, or perhaps double rendering something, etc. For whatever reason.

<script lang="ts">
    let firstRun = true;
    let someReactiveState = $state(0);

    $effect(() => {
        if (firstRun) {
            firstRun = false;
            return;
        }
        // Rest of effect here where "someReactiveState" is used (read).
    });
</script>

What will happen here is that the effect is run (for the first time once the component mounts) and will record any reads on reactive values. But guess what? The guard that was set in place using the firstRun variable had prevented any reads of reactive variables. The result: The effect will never run again.

You might think that this is fixed by making firstRun a reactive variable. This way, when it changes to false the effect runs again. But if you do that, the guard has no meaning: You ended up running the effect at the moment the component was mounted. You gained nothing. Let me know in the Comments section if this is not making sense to you and I’ll try to explain better.

The best fix for this is to avoid this construct. If you must, however, the way to fix it is to make dummy reads of the desired reactive values before the first-run guard:

<script lang="ts">
    let firstRun = true;
    let someReactiveState = $state(0);

    $effect(() => {
        if (firstRun) {
            // Dummy read:
            someReactiveState;
            firstRun = false;
            return;
        }
        // Rest of effect here where "someReactiveState" is used (read).
    });
</script>

Short Circuits

JavaScript will short-circuit when calculating Boolean expressions. If the expression requires evaluation of N sub-expressions, but evaluating the first K expressions is enough to infer the result, the rest of expressions R (N - K) will not be evaluated. They have been excluded because the entire original expression’s value has been inferred already.

Let’s see an example:

<script lang="ts">
    let a = $state(false);
    let b = $state(true);
    let c = $state(0);

    $effect(() => {
        if (a && b) {
            // Some logic that reads reactive value "c".
        }
    });
</script>

The example above contains the Boolean expression a && b. As you can verify by looking at a and b’s initial values, the expression doesn’t require reading the value of b: The result of a && b can be inferred by just reading a and realizing that it is false. Since false && <anything> will be false, there is no need to read b’s value. This means that the effect’s recorder will not record b as a potential trigger for the effect.

The net result of the above: Unless the value of a changes, changes to b won’t trigger the effect. This is particularly problematic if one of the K expressions (the expressions that are read/evaluated) are based on non-reactive variables.

Also note that, whenever a and b are true, the effect’s recorder will also record that c is a dependency of the effect. This should be clear by now, but one last reminder just in case. The recording takes place every time the effect runs, so this effect sometimes will only be triggered by changes in a, a or b, and sometimes it will be a, b or c.

The main lesson here is: The order of the expressions that compose Boolean expression matter.

Reading State Without Being Recorded

In less common cases, you might want to read a reactive variable inside an effect, but you don’t want the effect re-run if that reactive variable’s value changes. This can be accomplished with the untrack function. Any reactive variables read within the function delegate given to untrack will not be recorded and therefore will not contribute to the effect’s re-run.

The untrack function is usually the one function that saves you from infinite loops in effects that read and write the same reactive variable, or when 2-way synchronization is needed.

As stated, 2-way synchronization is usually a case where untrack is needed. The following example synchronizes a filter user interface with a quick-search textbox (that assumes to work on the “name” field):

<script lang="ts">
    import { untrack } from "svelte";

    const fields = ['name', 'email'];

    const stringOperators = ['contains', 'equals', 'starts with', 'ends with'];
    type Condition = {
        field?: string;
        value?: string;
        operator?: (typeof stringOperators)[number];
    };

    let filter = $state<Condition[]>([]); // Internal filter structure
    let quickSearch = $state(''); // Quick search value

    // Effect that transfers the quick search to the filter.
    // We need to untrack any reads on the filter to avoid infinite loops,
    // or at least unnecessary effect runs.
    $effect(() => {
        const cndIndex = untrack(() => filter.findIndex(condition => condition.field === 'name'));
        if (quickSearch) {
            if (cndIndex >= 0) {
                filter[cndIndex].value = quickSearch;
            } else {
                untrack(() => filter).push({ field: 'name', operator: 'contains', value: quickSearch });
            }
        }
        else if (cndIndex >= 0) {
            filter.splice(cndIndex, 1);
        }
    });
    // Effect that updates the quick search when the filter changes.
    $effect(() => {
        const nameCondition = filter.find(condition => condition.field === 'name');
        quickSearch = nameCondition?.value ?? '';
    });
</script>

<label>
    Quick Search:
    <input type="text" />
</label>

<form>
    {#each filter as _, index}
        <div>
            <select bind:value={filter[index].field}>
                {#each fields as field}
                    <option value={field}>{field}</option>
                {/each}
            </select>
            <select bind:value={filter[index].operator}>
                {#each stringOperators as operator}
                    <option value={operator}>{operator}</option>
                {/each}
            </select>
            <input type="text" bind:value={filter[index].value} placeholder="Value" />
            <button type="button" onclick={() => (filter = filter.filter((_, i) => i !== index))}>Remove</button>
        </div>
    {/each}
    <button
        type="button"
        onclick={() => filter.push({ field: fields[0], operator: stringOperators[0], value: '' })}
    >
        Add Condition
    </button>
</form>

The example is a bit long, but I felt it necessary to provide a good real-life example.

Warning: GitHub Copilot generated the markup and a few things in the script. I did not review it all. I did, however, review the 2 effects in the script tag.

The main thing to note here is that the first effect untracks any reads on the filter signals to avoid being re-run whenever the filter changes. This brings this tip up: It is very useful to add a comment line that describes what the effect’s intention is. This helps you study the code and be mindful about untracking any potential problematic signals.

The above also brings another tip up: The more focused an effect is, the better. Try to ensure that an effect has one and only one purpose. It is better to write more effects that does minimal things than one big effect that does all.

What About $effect.pre?

This is identical to the $effect rune in every way except one: Effects registered using $effect.pre will run before the component is mounted and before changes to the HTML document are made (the $effect ones run after mounting and after updates). That’s all there is to say about this rune.

Using Runes Outside Components

This is not an $effect-exclusive feature, but it is convenient to learn it in the context of effects because effects are the magic behind everything.

One of the major drivers for creating Svelte v5 with proxies (reactive signals) was that they allow for code refactoring. Rich Harris has explained this extensively, so I won’t say much about this here.

What’s important right now is to know that runes can be used outside component files as long as their file name contains “.svelte” in it, so the Svelte preprocessor picks these files up.

The simplest example is to replace Svelte v4 stores:

// v5Writable.svelte.ts
// Function form.  Not the preferred variant.
export function v5Writable<T>(initialValue: T) {
    const store = $state({ value: initialValue });
    return store;
}
// Class form.  This is the preferred variant.
export class V5State<T> {
    value = $state<T>() as T; // The type assertion is a trick to get rid of undesired "undefined".
    constructor(initialValue: T) {
        this.value = initialValue;
    }
}

Remember the previous article of this series: Even if $state looks like a function (that produces an R-value), it is not. It produces an L-Value with deep reactivity. We need the value property and so deep reactivity is welcome here.

Now you can use the v5Writable function or the V5State class in place of the old writable function to create stores based on proxies (signals):

<script lang="ts">
    import { V5State } from './v5Writable.svelte.js'
    let nameState = new V5State('world');
    let countState = new V5State(1);
</script>

<input type="text" bind:value={nameState.value} />
<input type="number" min="1" max="10" bind:value={countState.value} /> times
{#each { length: countState.value } as _, index}
    <h1>{index + 1}: Hello, {nameState.value}!</h1>
{/each}

NOTE: To be actual stores that can be accessed by multiple components, you would export an instance created by the function or an instance of the class, so the instance is available to many components. You know, the same you do with Svelte v4 stores: Singletons.

Ok, this is great, but how do we do the same with $effect? Because, for example, you might now want to write an effect that saves the value of the store every time it changes.

Creating Effects Outside Component Files

This is tricky. Effects can only be registered in the context of the lifecycle of components. You can write $effect’s anywhere you want: Constructors of classes, property getters or setters, exported module functions, etc. It will compile. The problem comes in runtime. If the $effect statement is executed outside the lifecycle of a component, you’ll get a runtime error.

Let’s modify V5State:

// v5Writable.svelte.ts
export class V5State<T> {
    value = $state<T>() as T;
    constructor(initialValue: T) {
        this.value = initialValue;
        $effect(() => {
            console.log('V5State value: %o', $state.snapshot(this.value));
        });
    }
}

After what I stated about how tricky effects are outside component files, this simple modification works! Did I blow things out of proportions? Well, let’s try to create singletons as one would for stores that need to be available to multiple components:

// NameStore.ts
import { V5State } from './v5Writable.svelte.js';

export default new V5State('World');

Now consume this global instance as one would normally do: By importing it. This is the previous example consuming this global instance:

<script lang="ts">
    import { V5State } from './v5Writable.svelte.js'
    import nameState from './NameStore.js';
    let countState = new V5State(1);
</script>

<input type="text" bind:value={nameState.value} />
<input type="number" min="1" max="10" bind:value={countState.value} /> times
{#each { length: countState.value } as _, index}
    <h1>{index + 1}: Hello {nameState.value}!</h1>
{/each}

The following error shows up:

effect_orphan `$effect` can only be used inside an effect (e.g. during component initialisation)

This happens because the code that sets the effect up is now running before the component that uses it starts initializing. So No, I did not blow things out of proportion. This is a real tricky issue one must have in mind.

Let’s learn about how to properly code effects outside components.

Using $effect.tracking

The $effect.tracking rune is a function that returns true if, when executed, the code was running within an effect (actual effects set up with $effect, or the effect that takes care of the updates of the component template). It so happens that this is one of those times that we are within the context of a component’s lifecycle.

This is a useful piece of information that we can use to fix our current example:

export class V5State<T> {
    value = $state<T>() as T;
    constructor(initialValue: T) {
        this.value = initialValue;
        if ($effect.tracking()) {
            $effect(() => {
                console.log('V5State value: %o', $state.snapshot(this.value));
            });
        }
        else {
            console.log('Not tracking.');
        }
    }
}

With this new version, the error seen before disappears! Yay! Oh, but wait, examine the console: There are two “Not tracking.” messages, one for the global nameState singleton, and one for the countState store. The error went away, but the effect wasn’t really set up.

This is because $effect.tracking only tracks effects, but effects aren’t the only place where effects can be registered. Component initialization, as we saw before, is an acceptable time for registering effects. How can we get the effects registered, then?

I have raised this issue here, and the summary of the discussion is: There is no one API that can be used to accurately know when it is OK to register effects. Core team member trueadm expressed the fact that the core team has had this discussion before, and that they may (but not guaranteed to) come up with a new rune for this exact purpose. At the time of writing, this pull request defines the $effect.active rune for this purpose and is still a draft pull request.

In the meantime, us mortals must juggle things in userland for the time being.

To make things work, let’s allow developers to signal when the class is being instantiated during component initialization with an extra parameter:

export class V5State<T> {
    value = $state<T>() as T;
    constructor(initialValue: T, effectAllowed = false) {
        this.value = initialValue;
        if (effectAllowed || $effect.tracking()) {
            $effect(() => {
                console.log('V5State value: %o', $state.snapshot(this.value));
            });
        }
        else {
            console.log('Not tracking.');
        }
    }
}

We, as consumers of the V5State class, can now use this second parameter to get the effect going:

<script lang="ts">
    import { V5State } from './v5Writable.svelte.js'
    import nameState from './NameStore.js';
    let countState = new V5State(1, true);  <-----  HERE!
</script>

<input type="text" bind:value={nameState.value} />
<input type="number" min="1" max="10" bind:value={countState.value} /> times
{#each { length: countState.value } as _, index}
    <h1>{index + 1}: Hello {nameState.value}!</h1>
{/each}

With this modification, we now only see one “Not tracking.” console log entry, and we can see that the effect for the count store works as expected.

To fix the global store, however, we must be more cunning than what we have been so far.

The $effect.root Rune

As stated in the documentation for this rune, it creates a non-tracked scope that doesn’t auto-cleanup. What does this mean? It means that you can run your own “private” effects whenever you want, at the cost of some extra RAM and CPU cycles.

We could re-write V5State like the following:

export class V5State<T> {
    value = $state<T>() as T;
    #cleanup;
    constructor(initialValue: T) {
        this.value = initialValue;
        this.#cleanup = $effect.root(() => {
            $effect(() => {
                console.log('V5State value: %o', $state.snapshot(this.value));
            });
        });
    }
    dispose() {
        this.#cleanup?.();
        this.#cleanup = undefined;
    }
}

What’s the catch with this rune? Its clean-up. We have collected the clean-up function and have exposed the public method dispose() to be able to execute this clean-up. But when do we call it? When should we clean up? There is no good and single answer to this question, and if you take this route, this is something you’ll have to figure out for yourself depending on your particular use case.

The above variant, however, will properly run the effect whenever the value property changes, and is therefore one way to overcome the problem we have been talking about.

The createSubscriber Function

This is a function available since v5.7.0, and its documentation isn’t the easiest of the bunch. I’ll provide an alternative explanation.

The createSubscriber function is used to create a subscribing function that keeps track of the number of times a subscriber (a component) reads the reactive value of interest (in V5State’s case, its value property). Every time the value is read, it sets up an effect if the read is performed within a tracking context. In other words, if $effect.tracking() returns true. After this, it merely counts reads and reduces this count on subscriber unmounts. When the counter reaches zero again, everything is cleaned up.

At the time of writing, this is the recommended option from the Svelte core team.

Let’s re-write V5State one more time:

import { createSubscriber } from "svelte/reactivity";

export class V5State<T> {
    #value = $state<T>() as T;
    #subscribe;
    constructor(initialValue: T) {
        this.value = initialValue;
        this.#subscribe = createSubscriber(() => {
            $effect(() => {
                console.log('V5State value: %o', $state.snapshot(this.value));
            });
        });
    }
    get value() {
        this.#subscribe();
        return this.#value;
    }
    set value(newValue: T) {
        this.#value = newValue;
    }
}

We have created the subscribing function, and we have set the effect up within the context of the subscription. We have also made the value property private and have explicitly provided a get accessor to ensure any reads on the value trigger a subscription.

Again: This is what the Svelte core team currently recommends.

This method has a scalability problem: This works by setting up a new effect every time the subscription runs (every time value is read), and these effects return a cleanup function that decrease the subscription count. Now, what if the value is read thousands of times in, say, an {#each} block? Then you will have created thousands of effects and thousands of cleanup functions.

There is also another problem: What if this is used in a global store (those where you export a singleton), and the subscription keeps starting and stopping, starting and stopping? If your subscription set-up is expensive, then you’ll pay the high price over and over.

Even if this is what the Svelte core team recommends being done, be aware that it might cause performance degradation in the above cases. In my opinion, avoid this method if your case is one of the above, and instead consider the $effect.root solution.

What About SSR?

This is a very easy question. Its answer: Effects don’t run in the server. In other words, server-side rendering doesn’t execute effects. Therefore, avoid effects as much as possible when writing applications or components that are meant to be rendered on the server. The effects only run after component hydration.

The lesson here is to always prefer $derived whenever possible because they work on the server.

Conclusion

Effects are very powerful but very tricky. Only by using them can one fully grasp their reach and limitations, and this article provides unique information that isn’t documented anywhere else.

Effects are great and necessary tools that enable the creation of great user interfaces, but there are rules to follow and behaviors to know in order to successfully realize their full potential. Developers need to understand how effects work internally in order to effectively code and debug them.

Svelte provide few, very useful tools to work with effects:

$inspect.trace(): To debug reactivity issues.
$effect.root(): To set effects up outside the context of components.
createSubscriber: To assist in the creation of reusable reactive code, usually in the form of classes, that can set effects up.

There is still room for improvement. We are expecting the $effect.active rune to come out that should provide an alternative method that doesn’t exhibit the potential scalability issues of createSubscriber.

Throwing if fetch() returns response.ok === false?? Terrible!

José Pablo Ramírez Vargas — Wed, 04 Dec 2024 07:14:28 +0000

Can anyone think of a good reason why the masses of Javascripters decided that the norm is to throw an error on non-OK HTTP responses?? Because I can't.

To me, this is a terrible practice, and everyone just seems hypnotized by it, like moths to the flame.

I hear you all, potential moths. 😄

How to Use TypeScript to Accumulate Types: Typing ALL possible fetch() Results

José Pablo Ramírez Vargas — Sun, 01 Dec 2024 02:25:53 +0000

When I started re-writing (with my team) our application in TypeScript and Svelte (it was in JavaScript and React which we all hate), I was faced with a problem:

How can I safely type all possible bodies of an HTTP response?

Does this ring a bell to you? If not, you’re most likely “one of those”, hehe. Let’s digress for a moment to understand the picture better.

Why This Area Seems Unexplored

Nobody seems to care about “all possible bodies” of an HTTP response, as I could not find anything out there already made for this (well, maybe ts-fetch). Let me quickly go through my logic here about why this is.

Nobody cares because people either:

Only care about the happy path: The response body when the HTTP status code is 2xx.
People manually type it elsewhere.

For #1, I’d say that yes, developers (especially the inexperienced ones) forget that an HTTP request may fail, and that the information carried in the failed response is most likely completely different to the regular response.

For #2, let’s dig into a big issue found in popular NPM packages like ky and axios.

The Problem With Data-Fetching Packages

As far as I can tell, people like packages like ky or axios because one of their “features” is that they throw an error on non-OK HTTP status codes. Since when is this OK? Since never. But apparently people are not picking this up. People are happy and content getting errors on non-OK responses.

I imagine that people type non-OK bodies when it is time to catch. What a mess, what a code smell!

This is a code smell because you are effectively using try..catch blocks as branching statements, and try..catch is not meant to be a branching statement.

But even if you were to argue with me that branching happens naturally in try..catch, there is another big reason why this remains bad: When an error is thrown, the runtime needs to unwind the call stack. This is far more costly in terms of CPU cycles than regular branching with an if or switch statement.

Knowing this, can you justify the performance hit just to misuse the try..catch block? I say no. I cannot think of a single reason why the front-end world seems to be perfectly happy with this.

Now that I have explained my line of reasoning, let’s get back to the main topic.

The Problem, Detailed

An HTTP response may carry different information depending on its status code. For example, a todo endpoint such as api/todos/:id that receives a PATCH HTTP request may return a response with a different body when the response’s status code is 200 than when the response’s status code is 400.

Let’s exemplify:

// For the 200 response, a copy of the updated object:
{
    "id": 123,
    "text": "The updated text"
}

// For the 400 response, a list of validation errors:
{
    "errors": [
        "The updated text exceeds the maximum allowed number of characters."
    ]
}

So, with this in mind we go back to the problem statement: How can I type a function that does this PATCH request where TypeScript can tell me which body I’m dealing with, depending on the HTTP status code as I write code? The answer: Use fluent syntax (builder syntax, chained syntax) to accumulate types.

Building the Solution

Let’s start by defining a type that builds upon a previous type:

export type AccumType<T, NewT> = T | NewT;

Super simple: Given types T and NewT, join them to form a new type. Use this new type as T again in AccumType<>, and then you can accumulate another new type. This done by hand, however, is not nice. Let’s introduce another key piece for the solution: Fluent syntax.

Fluent Syntax

Given an object of class X whose methods always return itself (or a copy of itself), one can chain method calls one after the other. This is fluent syntax, or chained syntax.

Let’s write a simple class that does this:

export class NamePending<T> {
    accumulate<NewT>() {
        return this as NamePending<AccumType<T, NewT>>;
    }
}

// Now you can use it like this:
const x = new NamePending<{ a: number; }>();  // x is of type NamePending<{ a: number; }>.
const y = x.accumulate<{ b: string; }>  // y is of type NamePending<{ a: number; } | { b: string; }>.

Eureka! We have successfully combined fluent syntax and the type we wrote to start accumulating data types into a single type!

In case it is not evident, you can continue the exercise until you’ve accumulated the desired types (x.accumulate().accumulate()… until you’re done).

This is all good and nice, but this super simple type is not tying up the HTTP status code to the corresponding body type.

Refining What We Have

What we want is to provide TypeScript with enough information so that its type-narrowing feature kicks in. To do this, let’s do the needful to obtain code that is relevant to the original problem (typing bodies of HTTP responses in a per-status code basis).

First, rename and evolve AccumType. The code below shows the progression in iterations:

// Iteration 1.
export type FetchResult<T, NewT> = T | NewT;
// Iteration 2.
export type FetchResponse<TStatus extends number, TBody> = {
    ok: boolean;
    status: TStatus;
    statusText: string;
    body: TBody
};

export type FetchResult<T, TStatus extends number, NewT> = 
    T | FetchResponse<TStatus, NewT>; //Makes sense to rename NewT to TBody.

At this point, I realized something: Status codes are finite: I can (and did) look them up and define types for them, and use those types to restrict type parameter TStatus:

// Iteration 3.
export type OkStatusCode = 200 | 201 | 202 | ...;
export type ClientErrorStatusCode = 400 | 401 | 403 | ...;
export type ServerErrorStatusCode = 500 | 501 | 502 | ...;
export type StatusCode = OkStatusCode | ClientErrorStatusCode | ServerErrorStatusCode;
export type NonOkStatusCode = Exclude<StatusCode, OkStatusCode>;

export type FetchResponse<TStatus extends StatusCode, TBody> = {
    ok: TStatus extends OkStatusCode ? true : false;
    status: TStatus;
    statusText: string;
    body: TBody
};

export type FetchResult<T, TStatus extends StatusCode, TBody> = 
    T | FetchResponse<TStatus, TBody>;

We have arrived to a series of types that are just beautiful: By branching (writing if statements) based on conditions on the ok or the status property, TypeScript’s type-narrowing function will kick in! If you don’t believe it, let’s write the class part and try it out:

export class DrFetch<T> {
    for<TStatus extends StatusCode, TBody>() {
        return this as DrFetch<FetchResult<T, TStatus, TBody>>;
    }
}

Test-drive this:

const x = new DrFetch<{}>(); // Ok, having to write an empty type is inconvenient.
const y = x
    .for<200, { a: string; }>()
    .for<400, { errors: string[]; }>()
    ;
/*
y's type:  DrFetch<{
    ok: true;
    status: 200;
    statusText: string;
    body: { a: string; };
}
| {
    ok: false;
    status: 400;
    statusText: string;
    body: { errors: string[]; };
}
| {} // <-------- WHAT IS THIS!!!???
>
*/

It should now be clear why type-narrowing will be able to correctly predict the shape of the body when branching, based on the ok property of the status property.

There’s an issue, however: The initial typing of the class when it is instantiated, marked in the comment block above. I solved it like this:

// Iteration 4.
export type FetchResult<T, TStatus extends StatusCode, TBody> = 
    unknown extends T ?
    FetchResponse<TStatus, TBody> : 
    T | FetchResponse<TStatus, TBody>;

export class DrFetch<T = unknown> { ... }

This small change effectively excludes the initial typing, and we are now in business!

Now we can write code like the following, and Intellisense will be 100% accurate:

const fetcher = new DrFetch();
...
const response = await fetcher
    .for<200, ToDo>()
    .for<400, { errors: string[]; }>()
    .fetch('api/todos/123', { method: 'PATCH' })
    ;

if (response.status === 200) {
    // You'll have full TypeScript support on the properties of the ToDo object
    // in the body property.
    response.body.id;
}
else {
    // You'll have full TypeScript support here, too:
    response.body.errors;
}

Type-narrowing will also work when querying for the ok property.

If you did not notice, we were able to write much better code by not throwing errors. In my professional experience, axios is wrong, ky is wrong, and any other fetch helper out there doing the same is wrong.

Conclusion

TypeScript is fun, indeed. By combining TypeScript and fluent syntax, we are able to accumulate as many types as needed so we can write more accurate and clearer code from day 1, not after debugging over and over. This technique has proven successful and is live for anyone to try. Install dr-fetch and test-drive it:

npm i dr-fetch

A More Complex Package

I also created wj-config, a package that aims towards the complete elimination of the obsolete .env files and dotenv. This package also uses the TypeScript trick taught here, but it joins types with &, not |. If you want to try it out, install v3.0.0-beta.1. The typings are much more complex, though. Making dr-fetch after wj-config was a walk in the park.

Fun Stuff: What’s Out There

Let’s see a few of the errors out there in fetch-related packages.

isomorphic-fetch

You can see in the README this:

fetch('//offline-news-api.herokuapp.com/stories')
    .then(function(response) {
        if (response.status >= 400) {
            throw new Error("Bad response from server");
        }
        return response.json();
    })
    .then(function(stories) {
        console.log(stories);
    });

“Bad response from server”?? Nope. “Server says your request is bad”. Yes, the throwing part itself is terrible.

ts-fetch

This one has the right idea, but unfortunately can only type OK vs non-OK responses (2 types maximum).

ky

One of the packages that I criticized the most, shows this example:

import ky from 'ky';

const json = await ky.post('https://example.com', {json: {foo: true}}).json();

console.log(json);
//=> `{data: '🦄'}`

This is what a very junior developer would write: Just the happy path. The equivalence, according to its README:

class HTTPError extends Error {}

const response = await fetch('https://example.com', {
    method: 'POST',
    body: JSON.stringify({foo: true}),
    headers: {
        'content-type': 'application/json'
    }
});

if (!response.ok) {
    throw new HTTPError(`Fetch error: ${response.statusText}`);
}

const json = await response.json();

console.log(json);
//=> `{data: '🦄'}`

The throwing part is so bad: Why would you branch to throw, to force you to catch later? It makes zero sense to me. The text in the error is misleading, too: It is not a “fetch error”. The fetching worked. You got a response, didn’t you? You just didn’t like it… because it is not the happy path. Better wording would be “HTTP request failed:”. What failed was the request itself, not the fetching operation.

How badly do you need to type HTTP responses?

José Pablo Ramírez Vargas — Tue, 12 Nov 2024 04:29:57 +0000

On one hand, fetching data is a must in 99.99% of web projects. On the other hand, fetch responses are not typed, or better stated, they return an object of type any, and on the other (prosthetic) hand, it is a major pain to work on projects where you have to constantly log to the console the response objects because your project is either not a TypeScript project or other developers just plain didn't care about their fellow developers and never typed a thing.

If you agree with me so far, stay. If you don't agree, this is not for you.

The Problem In Detail

Typing a response is not straightforward. Even if Response.json() were generic (it would accept the response type as a type argument), it still would be a pain. Why? Because the response type depends on the status code returned. A response with status code 200 OK carries different data than the response of the same URL with a 400 BAD REQUEST status code. Yes, we can go on: We could have different types for 401, 403, 201, 202, 503, etc.

So one URL, one fetch() operation, but multiple possible return types that depend on the status code of the response. How to type this?

My Objective

If you have an idea on how to tackle this N-types-for-N-stauts-codes problem, please share, no worries, but I write this to sense the audience. My objective here is to know if it would be worth creating an NPM package that solves this problem.

Would you be interested in such a package? I have this working at work, but if there's interest, I can make a public NPM package out of it.

Let me know!! Thanks for reading.

Dev.to is Gone: SPAM is What Powers It Now

José Pablo Ramírez Vargas — Sun, 10 Nov 2024 17:27:36 +0000

I used to be able to read the latest posts because, let's be honest: The Top feed is filled with useless, brainless listicles, and the featured feed becomes rather repetitive during they course of the day. So I used to browse the Latest feed the most.

Nowadays, what one can see is endless articles about asbestos, asbestos lawyers and a few how-to's on how to upgrade airplane tickets. It seems that Dev.to developers are incapable of finding a solution to this nonsense and for me, Dev.to is no longer an enjoyable place to find development-related content.

At the pace SPAM is overtaking the website, I believe it is no longer worth coming here every day. Maybe once or twice a week and read the Featured feed so it doesn't get repetitive.

What do you guys think? Is this boat sinking like the Titanic, or can it still be saved?

Learning the new Svelte v5 Reactivity System

José Pablo Ramírez Vargas — Thu, 24 Oct 2024 16:59:15 +0000

So Svelte v5, the newest rendition of what probably is the best front-end framework in existence, has been released and it is vastly different from its previous version. The main difference lies at its core: How reactivity of variables is implemented. Because of these changes, Svelte became easier, and at the same time a bit more difficult.

Since I have been working intensely with Svelte v5 since v5@next.155 in real-world micro-frontend projects, I decided to write this series of articles to pass on my gained knowledge to help you understand, embrace and potentially migrate your code to Svelte v5.

A Brief Introduction: Svelte v4 Reactivity

Svelte v4’s reactivity system is nothing short of a work of art: Svelte statically analyzes code in components and then generates code that imperatively changes the DOM whenever regular JavaScript variables change. Simple, elegant, and very performant. A quick example:

<script lang="ts">
    let clickCount = 0;

    function countClicks() {
        ++clickCount;
    }
</script>

<svelte:document on:click={() => countClicks()} />
<pre>Clicks inside document: {clickCount}</pre>

This simple component adds a “click” event listener to the document object and counts clicks. The click count is displayed in real time with just the above code. Amazing, right?

Like everything in life, though, this is not perfect. Rich Harris (the creator of Svelte) has explained the caveats, and I won’t go through those in this article. I’ll just mention one: Code refactor.

Code Refactoring is not Possible

One of the more important caveats is the inability to carry this reactivity system outside the component. One cannot, for instance, create a reusable module that encapsulates the implementation of the countClicks function in the example.

Because reactivity depends on static analysis, taking the function away and into a module will hide the variable mutation to the static code analyzer and then reactivity is lost.

Reactivity in Svelte v5: Runes

The term rune refers to a “magic symbol”, and is the term that Svelte adopted to name the following function-looking “magic” terms:

$state
$props
$bindable
$derived
$effect

Reactivity in Svelte v5 is governed by the use of these runes.

It is important to note that while they look like R-values, their produced code is really L-values. In other words, don’t think that you can pass around state from variable to variable. This is detailed a bit more below in the $state rune section.

The main advantages of this new reactivity system are:

Ability to refactor reactive code outside of components
Fine-grained reactivity

The former means that we can have reactive variables outside components; the latter means that component re-renders are more targeted when it comes to reacting on changing state.

The ability to have state outside components is not covered in this article but follow the series because an article about this will come.

Fine-grained reactivity, on the other hand, means that Svelte can now know which property changed in a state object, and only re-renders (and re-runs effects and recalculates derived values) what is affected by that specific property only. This is in some cases a major performance improvement. As a quick example: If a large table component sees a new row added to its data, Svelte will only render the new row. If a single cell value in the 3rd row changes, only the cell that shows the value will be re-rendered. Is it clear now? Hopefully it is, but if not, hit me in the Comments section.

The $state Rune

This rune is used to create reactive state. Let’s re-write the Svelte v4 code sample from above:

<script lang="ts">
    let clickCount = $state(0);

    function countClicks() {
        ++clickCount;
    }
</script>

<svelte:document onclick={() => countClicks()} />
<pre>Clicks inside document: {clickCount}</pre>

To achieve the same result that we did in Svelte v4, we simply used $state(0) instead of 0.

The main rule that governs this rune is that it can only be used to initialize variables or class fields, and it has to do with the important note you read a minute ago: Runes look like functions syntactically, but they are not. The compiler replaces runes with code that is not compatible with the idea of what a function does, which is calculate and return a value. This means that the following doesn’t create a second reactive variable:

<script lang="ts">
    let clickCount = $state(0);
    let secondClickCount = clickCount;

    function countClicks() {
        ++clickCount;
    }
</script>

The reactive nature of clickCount is not transferred or copied over to secondClickCount by virtue of using the assignment operator. If runes were functions, the above would have worked, but they are not.

There is one more important thing to mention about $state: It makes its value deeply reactive. This means that if the value is an object whose properties contain objects, then the properties of the contained objects are also reactive. This pattern applies recursively, so the entire object graph is ultimately reactive.

The $props Rune

Component properties are expected to be reactive, and Svelte v5 achieves this using the $props rune.

<script lang="ts">
    type Props = {
        data: number[];
        operation?: 'sum', 'avg';
    };

    let {
        data,
        operation = 'sum',
        ...restProps,
    }: Props = $props();

    function sum() {
        return data.reduce((p, c) => p + c);
    }

    function avg() {
        return sum() / data.length
    }
</script>

<span class="amount" {...restProps}>{operation === 'sum' ? sum() : avg()}</span>

<style>
    .amount {
        font-family: monospace;
    }
</style>

Because using TypeScript is everything to a project, we start by declaring the component properties using a type. Optional properties are marked by appending ? to its name.

Then comes the use of the rune, which is a de-structuring statement. The example shows how to assign default values and how to allow “rest” properties, which is any other property. The component spreads (applies) this “rest” of properties as properties (attributes) on the span HTML element.

You could do let props: Props = $props(); to define the properties and it works, but then you cannot specify defaults for the various properties, so I suggest you always declare properties as shown. I also wouldn’t know how to declare restProperties either if not de-structuring, by the way.

If you have been paying attention, the above produces a TypeScript error. After all, the Props type has no mention about any “rest” property. How can we type restProps?

Generally speaking, you could do stuff like the following to allow all kinds of stuff. It is up to your TypeScript skills, I suppose.

The following opens the Props type up to allow any data-* attribute:

<script lang="ts">
    type Props = {
        data: number[];
        operation?: 'sum', 'avg';
        [x: `data-${string}`]: any;
    };
</script>

This one allows anything:

<script lang="ts">
    type Props = {
        data: number[];
        operation?: 'sum', 'avg';
        [x: string]: any;
    };
</script>

But more often than not, one would need to allow the attributes of the HTML element that receives restProps, and in our example, that was the span HTML element.

For this common scenario, Svelte v5 provides types that should cover most of the HTML elements:

<script lang="ts">
    import type { HTMLAttributes } from 'svelte/elements';

    type Props = {
        data: number[];
        operation?: 'sum', 'avg';
    } & HTMLAttributes<HTMLSpanElement>;
</script>

Using the latter will make GUI’s like VS Code provide accurate Intellisense on the possible props (attributes) for the span HTML element. Nice, right?

The HTMLAttributes<T> interface is used for HTML elements that have no particularities in their list of properties. Many elements, however, do have. For example, rather than doing HTMLAttributes<HTMLButtonElement>, import the HTMLButtonAttributes interface from 'svelte/elements'.

The last detail is default values. There’s really not much to say and the example says it all: The default value of the operation prop is 'sum'. If the property is not specified when the component is used, that’s the value the prop will assume.

If the wanted default is undefined, then don’t specify anything at all.

The $bindable Rune

This one is a very specific rune that can only be used in component properties. It marks a property as bindable.

If you don’t know or don’t recall, Svelte allows for 2-way binding of properties. Vue also has this feature, and in contrast, React does not.

Usage is super simple:

// This is Rating.svelte
<script lang="ts">
    type Props = {
        value?: number;
    };

    let {
        value = $bindable(5),
    }: Props = $props();
</script>

<span>Rate Us:</span>
<input type="range" min="1" max="5" bind:value />

// This is a component consuming Rating.svelte
<script lang="ts">
    import Rating from './Rating.svelte';
    let rating = $state(3);
</script>

<Rating bind:value={rating} />

Always make properties that get their values modified as bindable, or Svelte will complain with a console warning. The warning states that components should not modify state that doesn’t belong to them, and that if this is intended, then a binding should be used.

As shown in the example, one can specify a property default through the $bindable rune. The example sets the property’s default to 5.

But does a default even make sense here? Well, yes. Declaring a property as bindable doesn’t make it required.

The $derived Rune

Whenever we need to calculate a value using values from props or other reactive state (that can change over time), we use the $derived rune.

Bringing the example component that calculates sums and averages back, we can re-write it using this rune:

<script lang="ts">
    import type { HTMLAttributes } from 'svelte/elements';

    type Props = {
        data: number[];
        operation?: 'sum', 'avg';
    } & HTMLAttributes<HTMLSpanElement>;

    let {
        data,
        operation = 'sum',
        ...restProps,
    }: Props = $props();

    let result = $derived(operation === 'sum' ? sum() : avg());

    function sum() {
        return data.reduce((p, c) => p + c);
    }

    function avg() {
        return sum() / data.length
    }
</script>

<span class="amount" {...restProps}>{result}</span>

<style>
    .amount {
        font-family: monospace;
    }
</style>

Now we have a new variable named result that is as reactive as its input and will automatically recalculate every time data in the data array changes. It itself is a reactive variable, so the template (the HTML part of the component) that uses it will also update.

The $effect Rune

This rune allows us to specify arbitrary code that runs whenever reactive data changes. For this rune to work its magic, it keeps track of the reactive data that is read during its execution. This inventory of reactive data is then used to re-trigger the effect whenever anything in the inventory changes its value.

Probably the most common scenario is to re-trigger a data fetch operation based on changing values:

<script lang="ts">
    import type { MyData } from './my-types.js';

    type Props = {
        pageSize?: number;
    };

    let {
        pageSize = 20,
    }: Props = $props();

    let data = $state<MyData[] | null>(null);

    $effect(() => {
        fetchMyData();
    });

    async function fetchMyData() {
        const response = await fetch(`/api/my-data?pageSize=${pageSize}`, { ... });
        if (response.ok) {
            data = JSON.parse(await response.json());
        }
        data = null;
    }
</script>

<ul>
    {#each data as item (item.id)}
        <li>
            <!-- Render data here -->
        </li>
    {/each}
<ul>

Asynchronous operations are usually the norm inside effects whenever we don’t want our $derived variables to hold promises. Personally, though and because it is so easy to work with promises in Svelte, I would simply use a $derived value. The variant shown next makes data a reactive calculated value that holds a promise:

<script lang="ts">
    import type { MyData } from './my-types.js';

    type Props = {
        pageSize?: number;
    };

    let {
        pageSize = 20,
    }: Props = $props();

    let data = $derived(fetchMyData());

    async function fetchMyData() {
        const response = await fetch(`/api/my-data?pageSize=${pageSize}`, { ... });
        if (response.ok) {
            return JSON.parse(await response.json()) as MyData[];
        }
        return null;
    }
</script>

{#await data}
    <Spinner>Loading data...</Spinner>
{:then items}
    <ul>
        {#each items as item (item.id)}
            <li>
                <!-- Render data here -->
            </li>
        {/each}
    <ul>
{:catch reason}
    <span>Oops! - {reason}</span>
{/await}

Generally speaking, if you are doing a combination of $state and $effect, you’re most likely better off with a $derived. There are exceptions to this rule, though, so take it as a rule of thumb and not the Holy Word.

If data fetching is not a good example for $effect, then what is? Let’s see this one:

<script lang="ts">
    type Props = {
        elapsed?: number;
        status?: 'not-started' | 'running' | 'paused ' | 'stopped';
    };

    let {
        elapsed = $bindable(0),
        status = 'not-started',
    }: Props = $props();

    let accumElapsed = $state(0);
    let startTime: Date;
    let intervalId: NodeJS.Timeout;
    let stopped = false;

    $effect(() => {
        switch (status) {
            case 'not-started':
                clearInterval(intervalId);
                elapsed = 0;
                accumElapsed = 0;
                stopped = false;
                break;
            case 'running':
                startTime = new Date();
                if (stopped) {
                    stopped = false;
                    elapsed = 0;
                    accumElapsed = 0;
                }
                runInterval();
                break;
            case 'paused':
                stopped = false;
                clearInterval(intervalId);
                accumElapsed += elapsed;
                break;
            case 'stopped':
                stopped = true;
                clearInterval(intervalId);
                break;
        }
    });

    function runInterval() {
        intervalId = setInterval(() => {
            elapsed = Math.floor((new Date().getTime() - startTime.getTime()) / 1_000) + accumElapsed;
        }, 1_000);
    }
</script>

<div>
    <span>Elapsed time: <span>{elapsed}</span> seconds</span>
</div>

This is a simple timer component that is controlled via its status property. The $effect rune is used here to enforce the timer’s operation. Can you imagine refactoring this to $derived? By the way, don’t try because elapsed is a prop, so it cannot be $derived and prop at the same time.

Conclusion

Svelte v5 comes with a brand-new reactivity engine that is geared towards better performance in re-renders and better code refactoring. Using the new reactivity system is both simple and complex: Simple because the common scenarios are well covered by the system’s design, and a bit more difficult because, when compared to v4, the code has become a bit more complex.

Regardless, the new system is powerful and caters for most scenarios gracefully and effectively, providing runes for all possibilities that are straightforward to use, albeit a bit odd at first.

What’s Next

This article has only covered the introductory part of runes, plus some bits of personal experience using them. There are more topics to cover to help you, fellow reader, ramp up more quickly with this new rendition of Svelte, namely:

In-depth knowledge of how $effect works
Advanced runes ($state.raw, $derived.by, $effect.pre, etc.)
Replacing stores with reactive state
Out-of-the-norm scenarios

Bonus: Performance Charts

Have a look at these benchmark results: Interactive Results (krausest.github.io)

Now, the list of frameworks is appalling, so you can copy the following JSON, and then paste it into the web page using the Paste button (see screenshot):

{"frameworks":["keyed/angular-cf","keyed/react-classes","keyed/react-compiler-hooks","keyed/react-redux","keyed/react-redux-hooks","keyed/react-redux-hooks-immutable","keyed/solid","keyed/solid-store","keyed/svelte","keyed/svelte-classic","keyed/vanillajs","keyed/vue","keyed/vue-jsx","keyed/vue-pinia","non-keyed/react-classes","non-keyed/svelte-classic","non-keyed/vanillajs","non-keyed/vue"],"benchmarks":["01_run1k","02_replace1k","03_update10th1k_x16","04_select1k","05_swap1k","06_remove-one-1k","07_create10k","08_create1k-after1k_x2","09_clear1k_x8","21_ready-memory","22_run-memory","23_update5-memory","25_run-clear-memory","26_run-10k-memory","41_size-uncompressed","42_size-compressed","43_first-paint"],"displayMode":1}

By the way, I think that simply focusing the window and pasting via keyboard works too.

This narrows down the list of frameworks to the more popular ones, or at least what I consider popular. Maybe you know better than me.

It is a shame that Svelte v4 is no longer available in the charts, but as you can see, out of the selected frameworks, the top 3 is undisputable: Vanilla JS, Solid and Svelte.

On the other end of the spectrum, it is just sad to see React v19 performing so poorly. Wasn’t the compiler supposed to make it like a lot better? It seems that it ended up being wasted effort. Sure, it seems to outperform React v18, but that’s about it. It is uncertain to me why Meta continues to invest money in React. Thoughts, anyone?

Finally! Cancel Web Workers' Work Without Terminating the Worker

José Pablo Ramírez Vargas — Mon, 26 Aug 2024 15:30:00 +0000

If you have never worked with web workers, the title doesn't really evoke emotion. Am I right? But if you have, you know that as of today, there is no equivalent to what AbortController does for fetch. Well, let's change that.

Meet @wjfe/async-workers, my most recent NPM package for front-end development. This package's mission is twofold:

To bring the asynchronous syntax to web workers (async/await).
To provide a solution to the long-standing issue of telling a worker to stop working without terminating it.

Why terminating a worker is not desirable? Well, several reasons exist, but the #1 and most practical reason is data loss. It is a common practice to "initialize" a worker's state by passing data to it. If a worker is terminated, a new worker needs to be initialized, again.

Let's see if I can interest you in using this package.

Motivation

If you don't care about this, skip this section and go straight to the package features.

Workers are basically separate threads that are spawned to run a pre-defined set of statements. JavaScript disallows all forms of communication between the UI thread and the worker thread except for one: Asynchronous messaging.

The UI thread may send messages to the worker thread and vice versa. In turn, each of these threads may receive and process messages every time the thread becomes idle so the browser engine (usually V8) goes to its message pump and pumps the code that picks up on messages. All this is automatic.

While not a terrible thing, programming under the messaging model partitions code. I personally thought this to be a drag. I searched the NPM package world and I did find some packages that provide async/await syntax that masks this messaging system, but in the end I did not like enough any of the implementations I saw.

Moreover, I really wanted to explore how to cancel web worker work from the UI thread. There's nothing out there. The best one can do (without using my package) is to program the worker code as a module and use asynchronous programming to await at some point (the cancellation checkpoint).

Awaiting puts the continuation of the code at the end of the JavaScript engine's message queue (behind the task that receives messages, if its promise has resolved). This means that, upon awaiting the cancellation checkpoint, there's an opportunity to pick up any messages the UI thread may have sent, including a potential cancellation message.

One would react to a cancellation message by saving the intent to cancel to a module-level variable. Once the worker resumes (after the cancellation checkpoint), the module-level variable is checked. If the variable is set, we cancel the work, otherwise we continue working.

Let's see this in code:

// Cancellation flag.
let cancelWork = false;

function yield() {
    return new Promise((rs) => setTimeout(() => rs(), 0));
}

aync function isPrime(n: number) {
    for (let i = 2; i <= n / 2; ++i)) {
        await yield();
        if (cancelWork) {
            cancelWork = false;
            // Easier to throw a specialized error.  Simpler to check for.
            throw new WorkerCancelledError();
        }
        if (n % i === 0) {
            return false;
        }
    }
    return true;
}

self.onmessage = async (ev: MessageEvent) => {
    if (ev.data.cancel) {
        cancelWork = true;
    }
    else {
        try {
            const itIs = await isPrime(ev.data.testValue);
            self.postMessage({ testValue: ev.data.testValue, itIs });
        }
        catch (error) {
            if (error instanceof WorkerCancelledError) {
                self.postMessage({ cancelled: true });
            }
        }
    }
};

This should work just fine, but let's re-write without the cancellation code, just to determine the boilerplate's weight that had to be added:

function isPrime(n: number) {
    for (let i = 2; i <= n / 2; ++i)) {
        if (n % i === 0) {
            return false;
        }
    }
    return true;
}

self.onmessage = (ev: MessageEvent) => {
    const itIs = isPrime(ev.data.testValue);
    self.postMessage({ testValue: ev.data.testValue, itIs });
};

Damn. From 12 lines to 33 lines, which is 3 lines shy from a whooping 200% increase in lines of code, and this doesn't show the code for the WorkerCancelledError class.

This is, as far as I can tell, the only way to allow on-demand cancellation of a web worker's current execution without terminating the web worker. Am I wrong? Hit me in the Comments section.

The other motivation for creating my own NPM package was the fact that I couldn't find an async/await implementation that really spoke to me.

Package Features

After several weeks of investigation, testing and playing around, I came up with @wjfe/async-workers. This package provides the following:

Asynchronous syntax (async/await). The package does the messaging boilerplate for you and delivers an object that mainly provides a promise that rejects if the worker's work throws, or resolves if the worker's work succeeds.
Smart queueing. This is something that you wouldn't notice unless you program the worker asynchronously. If you post messages to a synchronous worker, messages are processed one after the other, in sequence, without the messages ever interrupting work from previous messages. However, an asynchronous worker would pick up other messages the second it awaits for something. Smart queueing ensures messages are posted one at a time and only after the previous task has completed.
Out-of-order tasks. This is how one can bypass smart queueing. If you've been paying attention, smart queueing defeats asynchronous cancellation or any other form of send-data-while-running pattern. Out-of-order tasks skip the queue.
CancellationSource. This is the equivalent of AbortController. An instance of CancellationSource provides a cancellation token that is sent to the worker as part of the payload. This cancellation source can signal the token without the need of posting messages. CancellationSource can cancel synchronous workers.
Synchronization objects. Besides CancellationSource, the package provides ManualResetEvent, AutoResetEvent, and coming soon, Semaphore.

CancellationSource

So I lured you all for this: Cancelling a web worker's work-in-progress without having to terminate the worker. How does one write such code? Let's re-write the example worker above using my NPM package:

import { CancellationSource, workerListener, type PostFn, type Token } from "@wjfe/async-workers";

function _isPrime(n: number, cancelToken?: Token) {
    for (let i = 2; i <= n / 2; ++i)) {
        // Seems that the past tense of "signal" is "signaled", one L.
        // Expect this mispelling to be corrected soon.
        CancellationSource.throwIfSignalled(cancelToken);
        if (n % i === 0) {
            return false;
        }
    }
    return true;
}

export const primeWorkerTasks = {
    isPrime(tesValue: number, _post: PostFn, cancelToken?: Token) {
        return _isPrime(testValue, cancelToken);
    }
};

// For variable typing.
export type PrimeWorkerTasks = typeof primeWorkerTasks;

self.onmessage = workerListener(primeWorkerTasks);

This is 17 lines of code. This covers all the usual boilerplate associated to:

Message handling.
Throwing an exception if the token has been signaled.
Catching the thrown exception.
Rejecting the promise on the UI thread using a CancelledMessage object.

This, however, requires that the UI thread side be programmed using the NPM package as well. This is shown in the next section.

But I suppose the question that have in mind is: How is this form of cancellation possible? The answer is simple and not-so-simple: CancellationSource and the other synchronization objects use Atomics on SharedArrayBuffer objects. If you're interested on the topic, post a request in the Comments section, as this article won't explain this implementation detail.

Asynchronous Syntax

Ok, looking good so far. Let's see about the other main feature: How the UI thread is coded using promises instead of message listeners.

Because I love Svelte so much, let's do a Svelte component. The following is a simple component that tells the user if a given number is a prime number:

<script lang="ts">
    import PrimeWorker from "../workers/primeWorker.js?worker";
    import { AsyncWorker, CancelledMessage, type WorkItem } from "@wjfe/async-workers";
    import { primeWorkerTasks, type PrimerWorkerTasks } from "../workers/primeWorker.js";

    type Props = {
        testValue: number;
    };

    let {
        testValue,
    }: Props = $props();

    let worker: AsyncWorker<PrimeWorkerTasks>;
    let workItem = $state.raw<WorkItem>();
    // Worker's lifecycle.  Can also be done with onMount().
    $effect.pre(() => {
        worker = new AsyncWorker(new PrimeWorker(), primeWorkerTasks);
        return () => {
            worker?.terminate();
        }
    });
    // Runs on changes of the testValue property.
    $effect(() => {
        // Cancel any potential previous ongoing work.
        workItem?.cancel();
        workItem = worker.enqueue.isPrime(testValue, { cancellable: true });
    });
</script>

<span class="prime-result">
    {#await workItem?.promise}
        Working, please wait...
    {:then isPrime}
        {testValue} is {isPrime ? '' : 'not '}a prime.
    {:catch reason}
        {#if reason instanceof CancelledMessage}
            Calculation cancelled.
        {:else}
            Oops!: {reason}
        {/if}
    {/await}
</span>

<style>
    .prime-result {
        ...
    }
</style>

I don't really want to write the non-promise equivalent for this, so just imagine it: You would have to do worker.postMessage() on the effect for the testValue property to cancel the previous work, if any, using the asynchronous method shown in the Motivation section. Once cancellation takes place, another worker.postMessage() to start the new calculation for the new testValue. Then, set up a listener with worker.onmessage to receive the calculation result, and also a listener with worker.onerror to catch any potential errors. All this to replace the 2 lines inside the $effect() above.

But it doesn't stay there. There would be no promise unless you code one. If you don't go the promise route, you could not take advantage of Svelte's await block, which would make coding this component a lot harder. The list of additional chores probably goes on. I made @wjfe/async-workers so I don't have to think about this, so don't make me think about this, please! 😄

Synchronization Objects

The available synchronization objects in this package came to be because they pretty much were almost done by the time I finished implementing CancellationSource. As a matter of fact, CancellationSource extends ManualResetEvent.

Thread synchronization is not a topic I wish to cover in this article. If you would like me to do a piece on this topic, I'll be happy to do it. Ask for it in the Comments section. For now, I'll just say that ManualResetEvent objects don't reset after being awaited, so they are useful for things like pausing a web worker's work. On the other hand, AutoResetEvent objects automatically reset when a thread awakens by its token, making them useful for things like preventing/eliminating race conditions. Finally, the upcoming Semaphore object is useful to throttle/restrict access to resources, such as capping the maximum simultaneous requests to the back-end API to avoid overwhelming it.

Final Thoughts

Using web workers is not much fun. Its API is very simple, but cumbersome at the very least. It forces you to partition your code (the code that starts the task in one place, and the one that does something after completion in another place). There are currently no frameworks or libraries that would welcome them natively, and one is probably cornered to write boilerplate code to make them play nice with our framework or library of choice.

This is where @wjfe/async-workers come into play, by adding a far simpler API to code with workers, which happens to play well with the author's favorite framework, Svelte. This, of course, doesn't mean that the package cannot be used elsewhere. On the contrary, this is a zero-dependency NPM package that should make your life easier regardless of your user interface framework/library of choice.

If you like what you read, visit the GitHub repository and give it a star.

Stack Overflow Survey is out, and what is this??

José Pablo Ramírez Vargas — Fri, 26 Jul 2024 01:23:48 +0000

I have always been of the opinion that only hipsters/startups program in Mac or Linux. It is my experience that major companies (HP, IBM, Intel, Microsoft and the like) provide Windows machines to developers.

Well, what do you feel about these results?

Which factors could be driving MacOS and Ubuntu numbers to be so similar between work and personal use? Is this an indication that I'm right and only freelancers/startups/hipsters use these? My reasoning behind this would be: The numbers refer to the same PC, meaning the developer bought it, so it is a personal PC, but they also use it for freelance work. Am I right on the money?

Ok, enough oxygen on the flames of the OS feud. Honestly, what do you think is driving these numbers?

Are You in the NPM Package Business? Some Facts I Learned on the Road

José Pablo Ramírez Vargas — Fri, 01 Dec 2023 18:13:09 +0000

I love back-end development. I love C#. I would have never guessed, in a million years that I would end up creating not 1, not 2, but soon-to-be 3 NPM packages. C# is the love of my life, not to mention it ranks in the top 10 for performance in the HTTP servers category, putting the very popular NodeJS to shame, in position #212 according to the 2022 benchmarks. So how did I end up creating NPM packages? Good question. The short answer: Necessity.

A Bit of History

Just for the curious, this is the longer answer to the question above. Feel free to skip if you're not interested.

It all started when I saw the mess some contractor workers had done with the React projects' configurations at work. It was supposed to use dotenv and .env files, but I never understood why I had to configure the same value in 4 different places. Since I was hired as senior developer, I had the power to change it, so I did.

Did I mention I love C#? Can't remember. 🤔 Anyway, I love C# and I love .Net Configuration. The sight of the mess I found in the React projects made me yearn for .Net Configuration. So I said to myself: "Myself! You can create the JavaScript equivalent of .Net Configuration. Aren't you a senior, after all?". Myself was spot on, so I did. The first version was all in a single file, with basic merging functionality and a cool feature to build URL's out of configuration values found in the JSON. It was so good that I decided the world had to have it. Enter wj-config. The package works for browser and server (NodeJS) projects and everything was OK once more in the React (and NodeJS) world with this.

Time went by and destiny introduced me to my current lover: Svelte. At this point, I have been promoted to Technical Team Leader, so here comes the leader saying "To hell with React! We'll move all UI to Svelte". Being drunk with power is fun. So enter single-spa in my life. But I didn't want webpack! I wanted Vite, the one thing single-spa is not set up for. So enter once more a new NPM package: vite-plugin-single-spa. This one is currently ongoing, but the summary is: I already implemented single-spa in the React projects and started introducing Svelte.

The third package is not yet complete, but it is the extraction of the merge algorithm in wj-config into a new package, wj-merge. The merging algorithm is something that can prove very useful for a variety of situations. This is why I am refactoring it as a standalone package.

Ok, so that's the story. Let's go to the main course: My learnings.

Learning 1: People Hate Long Names

This is kind of shocking if one thinks about it. Give people an object named $, or _, or a function named t() and they love it! Give them meaningful and significant names and they'll hate it. I don't know why. Is it because people hate typing? Is it because the short/cryptic names are "cool"? I don't know. The learning here is: Try to use short names for things. The crowd will go nuts.

Learning 2: Typing a Package is Difficult

Who loves Intellisense? I do, and I bet most of you, avid readers. So what is an NPM package that doesn't provide Intellisense? A failure, that's what. If you want to be in the business of packaging for JavaScript, you better learn your TypeScript. And no, JsDoc is not enough, no matter how much hype people give it because Rich Harris (the creator of Svelte) dumped TypeScript. JsDoc cannot define complex structures. You'll still need some TypeScript in definition files. Furthermore, packages expect .d.ts files in them. So let's talk about JsDoc when it no longer piggyback rides on TypeScript's back.

When I created wj-config, I didn't know TypeScript. It was my first TypeScript-based project. I thought it went well back then. Now I can't believe how awful it is. After I conclude the extraction of the merging algorithm into its own package (wj-merge), I'll release v3.0 with much better TypeScript. For example, I have reached a point with wj-merge where the merged object is fully typed.

Learning 3: Learn How Package.json Works

This is the most difficult of them all. One must read countless articles and issue posts in order to gain some understanding. To complicate the process, things change over time: What needed to be done 4 years ago is usually superseded. To make matters even worse, there are features of package.json that had existed for a long time, and yet TypeScript have only recently started to support.

Learning 3.1: The main Field

This is something that theoretically isn't needed anymore if you use a more modern approach like Svelte does using the exports field. However, at least a year ago, if I didn't specify the main field, Visual Studio Code would complain. So the learning here is: Try exports first, but if it misbehaves, see if adding main solves the issue.

Of course, if all you need is one entry point, you can probably stick to the main field and forget exports.

Learning 3.2: Name your .d.ts File the Same As the Package

A year or so ago, if I had index.d.ts in wj-config, it wouldn't work in Visual Studio Code, but started working when I renamed it to wj-config.d.ts. Maybe this is no longer relevant, but have it in the back of your head, just in case.

Learning 3.3: The exports Field

If your package is meant to have multiple "entry points" like vite-plugin-single-spa, the types field is not enough because it can only hold the name of one definition TS file. Use the verbose version of the exports field instead. Here's an example from vite-plugin-single-spa:

  "exports": {
    ".": {
      "import": "./index.js",
      "types": "./vite-plugin-single-spa.d.ts"
    },
    "./ex": {
      "import": "./ex/index.js",
      "types": "./ex/index.d.ts"
    }
  },

This means that consumers of this package can import from "vite-plugin-single-spa" or "vite-plugin-single-spa/ex". Because each path has its own types field, you can specify all of your definition TS files. Fun fact: This only works with TypeScript v4.7 or newer.

Important: Specifying the exports field limits consumers of the package to import from the routes specified here. No other routes can be used to import.

Learning 4: Respect Semantic Versioning

I guess this one is pretty much given, but just in case: If don't want to be yelled at, respect semantic versioning. Your consumers will be very angry if all of the sudden a patch version increase carries a change in the exposed API. If you don't know semantic versioning, it is time for you to learn.

Also take the time to learn code strategies to create backwards-compatible upgrades, such as adding optional parameters, function overloads or creating new functions or objects but respecting the old ones. For example, you could move the logic of an existing function to a completely new function, and then calling this new function from the old function. This preserves the old signature while providing new functionality with the new function. This way your consumers get the improved logic, but don't have to worry about API changes.

Learning 5: Documentation!

No matter how good your package is: If it isn't well documented, people will complain. Learn to create good README files, and even Wiki's. The wj-config package has a ton of features. Its README grew up to 50kb in size! It was loooong. I finally reduced it to just some quick examples and moved everything else to the repository's Wiki.

Learning 6: You'll Screw Deployments Up

I went from wj-config v1.0.0 to v1.1.0 so fast I couldn't believe it. To this day, I continue to screw things up. From commented code you forget to uncomment, to forgetting to update the README, to forgetting to update your .d.ts files. Anything can happen. The learning here is: Use pre-releases. When I worked on version 2.0 of wj-config, I started doing them. I published 3 betas and 3 release candidates before publishing v2.0.0. The package's version history clearly tells the tale.

This learning has a corollary: When starting a new NPM package, start with v0.0.1. Versions that start with zero are regarded as "experimental" versions. Interestingly enough, this carries another corollary: The command npm version patch --preid beta doesn't append "beta" to an experimental version. So don't try to do pre-releases of experimental versions. Maybe this is a bug in npm, I don't know.

Learning 7: Don't Do Manual Deployments

I cannot teach you too much about this one as I haven't set up CI/CD for my NPM packages, but even if I haven't taken this learning into practice, I am fully convinced that this is very important. It will help you minimize your deployment issues. At the very minimum, do what I currently do: Script the deployment. I script using PowerShell, but the scripting language is largely unimportant.

Learning 8: Always Do Unit Testing

Never pretend to deploy a package that doesn't have unit testing. I have been coding for 20 years, and after 20 years I still cannot create bug-free code on the first try.

This learning also has a corollary: Always run unit testing before deploying. Then you won't screw a deployment up because you forgot to uncomment some code (true story).

Learning 9: Don't Spam the Console With Messages

It is incredibly rude for NPM packages to log things to the console, even if it is with console.debug(). The way to work this is to ask for a logger or logger factory function/object. If the consumer of the NPM package wants to see the logging from the NPM package, they can provide the logger or logger factory by following the package's instructions. An example of such package is @azure/msal-browser, if you are curious.

The debug NPM Package

This is an incredibly popular package found in countless other packages. I don't like it. It forces you to a specific logger. What if I wanted telemetry? No way, no how. Providing a logger object is, in my opinion, the best route.

Learning 10: Not All Packages Require Bundling/Minification

In my tests with vite-plugin-single-spa, I noticed that rollup would minify already-minified sources. In 100% of the cases I saw, this actually increased the size of the bundle: Minifying a minified source increases its size. The learning here is: At the very least provide a non-minified version of the code if it is expected to be bundled and minified.

Other cases require no bundling or minification at all. vite-plugin-single-spa is my example. This is code that only runs during the building or serving process in Vite, and the parts that do get into the user's bundle is minified by Vite. This means that providing a minified version of this package is wasted effort.

The opposite case is wj-config, which could be consumed by means of a script tag in the browser. This is something I did not foresee, and v3.0 will have a bundled + minified version in it. It will continue to provide the unminified source so people can bundle and minify it when installing it as a package in projects.

Learning 11: Forget CommonJS Modules

Write all your JavaScript in ES modules. It works everywhere. Nuff said.

Learning 12: Review Issues Daily

If you decided to go public with your NPM package (or pretty much any open-source software), be kind to your consumers and keep an eye out for reported issues. Ideally, reply within 24 hours. Even if it is your project, you don't get notified unless you start watching it. Watch your own projects to get e-mail notifications of new issues.

Conclusion

There is nothing trivial or simple in the NPM packaging business. It requires effort and a methodical mindset. It is usually never free of errors and is filled with best practices.

Happy coding!

Single-SPA Parcels and vite-plugin-single-spa

José Pablo Ramírez Vargas — Sun, 12 Nov 2023 19:45:26 +0000

UPDATE: vite-plugin-single-spa v0.4.0 is out and is compatible with parcels.

Welcome, everyone, to the next topic in the single-spa arena: Parcels. These are pieces of user interfaces that are meant to be used as "utilities" from anywhere in your application, and since your application is built by glueing together mini applications (micro-frontends), it means that parcels are meant to be used by any micro-frontend, regardless of the parcel framework or the micro-frontend framework.

What This Article is Not About

I apologize if I made you believe I was going to give a tutorial on single-spa parcels. I will not. However, that doesn't necessarily mean that this article won't have explanations around how to create them. It will. It is just that the article's objective is not to be a tutorial on single-spa parcels.

Instead, this article will talk about parcels in the context of the vite-plugin-single-spa plug-in and the general requirements to make projects that export them, from start to finish.

Setting Up Test Projects

Ok, since my interest in this topic involves "old" React code and new Svelte code, I'll be focusing on this combination.

Let's create a React root project and a Svelte parcels project, which would be a micro-frontend type project.

The root project:

PS C:\Users\webJo\src> npm create vite@latest
√ Project name: ... ReactRoot
√ Package name: ... reactroot
√ Select a framework: » React
√ Select a variant: » TypeScript + SWC

Scaffolding project in C:\Users\webJo\src\ReactRoot...

Done. Now run:

  cd ReactRoot
  npm install
  npm run dev

And then the parcels project:

PS C:\Users\webJo\src> npm create vite@latest
√ Project name: ... SvelteParcels
√ Package name: ... svelteparcels
√ Select a framework: » Svelte
√ Select a variant: » TypeScript

Scaffolding project in C:\Users\webJo\src\SvelteParcels...

Done. Now run:

  cd SvelteParcels
  npm install
  npm run dev

Great! In the root project, let's install the needful:

npm i vite-plugin-single-spa bootstrap single-spa single-spa-react
npm i -D sass

Let's do similarly in the parcels project:

npm i vite-plugin-single-spa single-spa-svelte
npm i -D bootstrap sass

Excellent. We can start.

Root Project Code

First, delete App.css and index.css and instead add src/App.scss. Remove all references to the deleted files (use the Find in Files functionality of your code editor). Then add import './app.scss'; to src/App.tsx.

Now create appropriate styling and new content for the App component.

This is src/App.scss:

@import "../node_modules/bootstrap/scss/bootstrap";

html {
    --main-color: rgb(73, 13, 130);
}

div.app {
    height: 100vh;
    display: flex;
    align-items: center;
    width: 100%;
}

.content {
    border-radius: 0.5em;
    padding: 1.5em;
    height: 100%;
}

.root-content {
    @extend .content;
    background-color: var(--main-color);
    color: white;

    & > h1 > span {
        margin-right: 0.3em;
    }
}

.parcel-content {
    @extend .content;
    border: 0.25em dashed (var(--main-color));
}

This is src/App.tsx:

import { useState } from 'react'
import reactLogo from './assets/react.svg'
// @ts-expect-error
import Parcel from 'single-spa-react/parcel'
import './App.scss'

function App() {
  const [loadParcel, setLoadParcel] = useState(false);

  return (
    <div className="app">
      <div className="row w-100">
        <div className="col-sm-5">
          <div className="root-content">
            <h1><span><img src={reactLogo} alt="React" /></span>React Root Project</h1>
            <p>
              Click the button below to load a Svelte parcel.
            </p>
            <button type="button" className="btn btn-primary">Toggle Parcel</button>
          </div>
        </div>
        <div className="col-sm-7">
          <div className="parcel-content">
            <h3>Parcel Display</h3>
            {loadParcel ? <Parcel /> : null}
          </div>
        </div>
      </div>
    </div>
  )
}

export default App

You should now see a root project similar to this:

Looking good so far. Let's stop for a moment here with the root project because now we need to know about our parcel, and that's the other (Svelte-powered) project.

Parcel Project Code

We start cleaning up. Delete the src/App.css file, and remove its reference in src/main.ts. Theoretically speaking, we should just be able to create the parcel component(s) we want without worrying about the index page or the src/main.ts script. However, if you would like to conserve the ability to see what you will mount in the root project without mounting in the root project, we can set something up for sure.

Since we are using Bootstrap here, let's create src/App.scss to get ourselves a copy of Bootstrap ready to go in the test page:

@import "../node_modules/bootstrap/scss/bootstrap";

Then add import './App.scss'; to src/main.ts. That should be it.

Now, unlike "regular" micro-frontends, we won't be exporting single-spa lifecycle functions that mount the App Svelte component. No sir! We will now mount potentially multiple Svelte components, each requiring single-spa lifecycle functions.

So src/App.svelte is only a concern when it comes to testing without mounting. Let's create a component that we can mount as a parcel now.

Add the file src/lib/Welcome.svelte:

<script lang="ts">
    export let name: string | undefined = undefined;
</script>

<div>
    <p>Welcome, <span class="text-primary">{name ? name : 'person or thing'}!</span></p>
    <button class="btn btn-secondary">{name ? 'Sign out' : 'Sign in'}</button>
</div>

This is a very simple component that welcomes the user. It has a single prop named name, and if no name is provided, we assume the user hasn't logged in. All styling is done through Bootstrap classes.

To see how it looks like in the test page, simply reduce src/App.svelte to this:

<script lang="ts">
    import Welcome from './lib/Welcome.svelte';
</script>

<main>
  <Welcome />
</main>

This should show you this:

I intentionally added part of Microsoft Edge's border and toolbar to remind us all how lacking is our project right now in terms of styling that our content is completely against the browser's edges. However, let's remind ourselves that we want mountable parcels, so this should not be a primary concern for us at this point in time.

Ok, let's call the initial setup of both projects complete at this point. We shall now proceed to export the Svelte-powered single-spa parcel.

Exporting Parcels

According to single-spa's documentation, we export a parcel very similarly to how we export micro-frontends. We are even encouraged to use the same helpers (single-spa-react, single-spa-svelte, etc.).

Add the file src/parcels.ts to the SvelteParcels project:

import Welcome from "./lib/Welcome.svelte";
// @ts-expect-error
import singleSpaSvelte from 'single-spa-svelte';

export const welcomeParcel = singleSpaSvelte({
    component: Welcome
});

Modify vite.config.ts:

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
import vitePluginSingleSpa from 'vite-plugin-single-spa'

export default defineConfig({
  plugins: [svelte(), vitePluginSingleSpa({
    serverPort: 4201,
    spaEntryPoint: 'src/parcels.ts'
  })],
});

Note: This changes our Vite server port! If your test page stopped working, note the new port value.

At this point, I am confident we successfully exported the Welcome Svelte component as a single-spa parcel. Let's go back to the root project.

Importing Parcels

Let's now take care of the configuration of the root project. We haven't added any of the single-spa things that we need.

Start by adding src/importMap.json:

{
    "imports": {
        "@test/parcels": "http://localhost:4201/spa.js"
    }
}

Then, src/importMap.dev.json:

{
    "imports": {
        "@test/parcels": "http://localhost:4201/src/parcels.ts"
    }
}

These should be familiar to you: It is almost identical to what we set up for micro-frontends.

Now, modify vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import vitePluginSingleSpa from 'vite-plugin-single-spa'

export default defineConfig({
  plugins: [react(), vitePluginSingleSpa({
    type: 'root',
    imo: '3.1.0'
  })],
})

So far, so good. Now to src/App.tsx to make the "Toggle Parcel" button work.

In case you didn't realize, we installed single-spa-react in the root project. Why? Because it comes with a React component called Parcel that can be used to easily mount single-spa parcels. We even added it to the markup very early on. Its documentation tells us that we must provide the config prop at the very least. Its value must be a parcelConfig object, or a loader function that returns said object asynchronously. Let's use the latter as it seems simpler because we won't have to work magic around the statement import { welcomeParcel } from '@test/parcels'; when running in development mode.

Ok, allow me to show the code for src/App.tsx with the modifications:

import { useState } from 'react'
import reactLogo from './assets/react.svg'
// @ts-expect-error
import Parcel from 'single-spa-react/parcel'
import './App.scss'

function App() {
  const [loadParcel, setLoadParcel] = useState(false);
  const parcelModuleName = "@test/parcels";

  async function loadWelcomeParcel() {
    const parcelsModule = await import(/* @vite-ignore */ parcelModuleName);
    return parcelsModule.welcomeParcel;
  }

  return (
    <div className="app">
      <div className="row w-100">
        <div className="col-sm-5">
          <div className="root-content">
            <h1><span><img src={reactLogo} alt="React" /></span>React Root Project</h1>
            <p>
              Click the button below to load a Svelte parcel.
            </p>
            <button
              type="button"
              className="btn btn-primary"
              onClick={() => setLoadParcel(v => !v)}
            >
              Toggle Parcel
            </button>
          </div>
        </div>
        <div className="col-sm-7">
          <div className="parcel-content">
            <h3>Parcel Display</h3>
            {loadParcel ? <Parcel
              config={loadWelcomeParcel}
              handleError={console.error}
              parcelDidMount={() => console.debug('Parcel mounted.')}
            /> : null}
          </div>
        </div>
      </div>
    </div>
  )
}

export default App

The modifications are rather minimal:

We defined the module name in a constant for two reasons: The first one is that Vite will complain if we put it directly inside the dynamic import() call; the second one is that we can use it in other loader functions as we add parcels to our parcels project. I don't know if I will do it, but I thought I might.
We defined the loadWelcomeParcel() function that imports and returns the named welcomeParcel export.
We provided functionality to the "Toggle Parcel" button we had.
We gave the Parcel component the needed properties, which are:
- config: The loader function we created.
- handleError: We added the console.error method as our error handler.
- parcelDidMount: We added a simple logging statement for good measure.

Great!, save, click the "Toogle Parcel" button and .... doesn't work! Nothing happens. Well, it took me some time to figure this one out. The issue has been raised as a bug since Jaunuary 13, 2023, here. I'm no React developer, so I don't know if what I'm about to say is bad: Solve this by removing <React.StrictMode> from src/main.tsx. If this is a bad thing, please, by all means don't take it against me! Go to the issue's page and bombard it with comments and upvotes so it gets fixed. Even better: If you can fix it, fix it and make a pull request for it!

Ok, back to topic. This is how I have src/main.tsx after removing <React.StrictMode>:

import ReactDOM from 'react-dom/client'
import App from './App.tsx'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <App />
)

Just the App component. Ok! Let's retry! Another error, that we see twice (once for our error handler, and once for the uncaught nature of the error):

Error: During 'mount', parcel threw an error: was not passed a mountParcel prop, nor is it rendered where mountParcel is within the React context. If you are using within a module that is not a single-spa application, you will need to import mountRootParcel from single-spa and pass it into as a mountParcel prop

This one can be understood easily: The Parcel component looks for the mountParcel function inside the SingleSpaContext context that single-spa-react provides to micro-frontends. However, since I'm a stubborn child that doesn't follow single-spa's recommendations, I have a root React project that wants to load a parcel. So how do I fix? Very simply: We use single-spa's mountRootParcel() function. Just import this function and add it to the Parcel component as a prop:

// This is src/App.tsx, just in case.

// Other imports here...
import { mountRootParcel } from 'single-spa'
// Rest of code here, up to the Parcel component...

            {loadParcel ? <Parcel
              config={loadWelcomeParcel}
              mountParcel={mountRootParcel}
              handleError={console.error}
              parcelDidMount={() => console.debug('Parcel mounted.')}
            /> : null}
// Rest of file here...

Save and try again. Success! Kind of. Something unexpected is in sight. Let me show you a screenshot:

Did you see? The name! It says "Welcome, parcel-0"! I was expecting "Welcome, person or thing!" which is what I programmed for the cases where the name prop was not specified. Furthermore, the button's caption is "Sign out", not "Sign in". One more learning, I suppose: One of the properties injected by single-spa to parcels is the name property, and its value is an automatically-assigned name. We need to avoid using name as a component prop, unless we are after the parcel's name.

Now that we are speaking about single-spa props sent to parcels, let's complete the list easily by looking at the warnings in the console:

This means that the complete list of props a parcel receives is:

Name	Description
`name`	The parcel's name.
`domElement`	The element where the parcel is mounted.
`mountParcel`	A function that can be used to mount parcels. At this point in time, I am unsure if this is `mountRootParcel`, or something else.
`singleSpa`	The `singleSpa` instance object; same as in micro-frontends.
`unmountSelf`	A function that unmounts the parcel, made available to the parcel.

This list of properties does not seem to be anywhere in the single-spa's official documentation website, so you might want to bookmark this article.

Excellent progress! We have managed to export parcels from Svelte and use them in React. Let's try to interact with the parcel from React.

Interacting With Parcels

Due to our unexpected outcome, let's first rename the name prop in the Welcome parcel to user:

<script lang="ts">
    export let user: string | undefined = undefined;
</script>

<div>
    <p>Welcome, <span class="text-primary">{user ? user : 'person or thing'}!</span></p>
    <button class="btn btn-secondary">{user ? 'Sign out' : 'Sign in'}</button>
</div>

Because of HMR, saving this immediately shows up correctly inside the React page.

Ok, let's add a text box for us to type a user from React and have React send this to the Welcome parcel as the user's name.

  // This is in src/App.tsx:
  // One more ugly state for the user:
  const [user, setUser] = useState<string | undefined>(undefined);

  // Then the modification in markup, including passing the prop to the parcel.
  <h3>Parcel Display</h3>
  <div className="mb-3">
    <label htmlFor="user">User's name:</label>
    <input className="form-control" type="text" id="user" onInput={(e) => setUser(e.currentTarget.value)} />
  </div>
  {loadParcel ? <Parcel
    config={loadWelcomeParcel}
    mountParcel={mountRootParcel}
    handleError={console.error}
    parcelDidMount={() => console.debug('Parcel mounted.')}
    user={user}
  /> : null}

Save and test:

Aw, stop! You're too kind. But, yes, yes I am.

In all seriousness now: The coupling works seamlessly, where the Svelte component quickly updates its state on every keystroke. There is no functional difference between this parcel and a component made in React in the same root project.

Let's now do the inverse: Have the Svelte parcel interact with the React code. For this, we will add a handler to the click event of the button in the parcel.

Because React doesn't work with events, the simplest is to provide a prop for a callback in the Svelte side. Add a new prop to the Welcome component, then add a handler function, and finally, inside the handler, both dispatch the event and call the callback prop:

// Import the usual createEventDispatcher and create the dispatch function:
import { createEventDispatcher } from 'svelte';
const dispatch = createEventDispatcher();
...
// The new prop:
export let onSignInOut: Function | undefined = undefined;
...
// The handler:
function signInOutHandler() {
    const detail = {
        user,
        signedIn: !!user
    };
    dispatch('signInOut', detail);
    (onSignInOut ?? (() => {}))(detail);
}

Finally, modify the button so it runs the handler on click:

<button class="btn btn-secondary ms-auto" on:click={signInOutHandler}>{user ? 'Sign out' : 'Sign in'}</button>

Now to the ReactRoot project, where we add the extra prop to the Parcel component in src/App.tsx:

{loadParcel ? <Parcel
  config={loadWelcomeParcel}
  mountParcel={mountRootParcel}
  handleError={console.error}
  user={user}
  onSignInOut={(e: any) => console.debug('Sign In/Out: %o', e)}
/> : null}

Test this by loading the parcel with the "Toggle Parcel" button, then clicking the "Sign In" button. The console should show you the data received in the call back. Very simple and straightforward.

NOTE: We did the event and the callback in Svelte for maximum compatibility. Maybe Svelte v5 surprises us with bubbling Svelte events in the future. If that's the case, maybe we can switch to consuming the event in a parent element of the Parcel component. We'll see.

We have covered the basic functionality of parcels with great success so far, but one important topic remains: The parcel's CSS.

CSS in Parcels

So far, our parcel has only had Bootstrap CSS classes applied, and since our root project provides Bootstrap, we haven't noticed any problems in the styling department. This demonstrates how useful a shared styleguide is when working with micro-frontends. But let's be honest: Real-life applications will more than likely need more CSS. So let's explore what happens in our current set up when we add styling to the Svelte component.

Before we start, go ahead and build the SvelteParcels project. You'll see its output consists of a single file: spa.js:

vite v4.5.0 building for production...
✓ 27 modules transformed.
dist/spa.js  6.65 kB │ gzip: 2.81 kB
✓ built in 299ms

There is no CSS needed for injection. This parcel works out of the box without us having to worry about CSS files.

So, back to topic: Let's pretend for a moment that Bootstrap doesn't provide utility classes, or that I simply don't know that I can do class="d-flex flex-nowrap align-items-baseline gap-3 w-100". So let's make the Svelte component line things up in one line.

Modify src/lib/Welcome.svelte like below:

<script lang="ts">
    export let user: string | undefined = undefined;
</script>

<div class="welcome">
    <p>Welcome, <span class="text-primary">{user ? user : 'person or thing'}!</span></p>
    <button class="btn btn-secondary ms-auto">{user ? 'Sign out' : 'Sign in'}</button>
</div>

<style>
    div.welcome {
        display: flex;
        flex-flow: row nowrap;
        gap: 1em;
        align-items: baseline;
        width: 100%;
    }
</style>

The only things that changed are that we applied a CSS class to the component's root DIV element, that we added automatic margin to the button to push it to the right, and of course, the main thing here: The style tag.

As soon as you save, the changes can be seen in the SvelteParcels test page and the ReactRoot page. This happens because Vite dev server injects the CSS for us. If you don't believe, just examine the contents of the HEAD HTML element. The last element will be:

<style type="text/css" data-vite-dev-id="C:/Users/webJo/src/SvelteParcels/src/lib/Welcome.svelte?svelte&amp;type=style&amp;lang.css">div.welcome.s-U5UaycqR-l4Y{display:flex;flex-flow:row nowrap;gap:1em;align-items:baseline;width:100%}.s-U5UaycqR-l4Y{}</style>

This luxury is gone in a built project, so we can expect to lose our gains if we were to run the projects in preview mode. Let's.

This is my build of SvelteParcels:

vite v4.5.0 building for production...
✓ 28 modules transformed.
dist/assets/vpss(svelteparcels)parcels-2d7e02d5.css  0.10 kB │ gzip: 0.11 kB
dist/spa.js                                          6.69 kB │ gzip: 2.83 kB
✓ built in 300ms

This is the build for ReactRoot, although of no particular importance to the topic at hand:

vite v4.5.0 building for production...
✓ 36 modules transformed.
dist/index.html                   0.90 kB │ gzip:  0.50 kB
dist/assets/react-35ef61ed.svg    4.13 kB │ gzip:  2.14 kB
dist/assets/index-37125051.css  226.14 kB │ gzip: 30.93 kB
dist/assets/index-c8b3e608.js   169.48 kB │ gzip: 54.44 kB
✓ built in 2.94s

Unrelated note: Amazing how heavy React is. Svelte, I shall be with you until my final days!

Now do npm run preview on both projects, then open ReactRoot's page. Sure enough, the scoped styling in the Svelte component is gone.

Using cssLifecycle from vite-plugin-single-spa

We solved the CSS mounting and unmounting of micro-frontends some time ago with a dynamic ES module called vite-plugin-single-spa/ex that provides the cssLifecycle object. This is used when exporting the single-spa lifecycle functions, and we can give it a go right now.

Open src/parcels.ts in the SvelteParcels project and modify it to look like this:

import Welcome from "./lib/Welcome.svelte";
// @ts-expect-error
import singleSpaSvelte from 'single-spa-svelte';
import { cssLifecycle } from 'vite-plugin-single-spa/ex';

const lc = singleSpaSvelte({
    component: Welcome
});

export const welcomeParcel = {
    bootstrap: [cssLifecycle.bootstrap, lc.bootstrap],
    mount: [cssLifecycle.mount, lc.mount],
    unmount: [cssLifecycle.unmount, lc.unmount],
    update: lc.update
};

Now build SvelteParcels one more time, but remember to add Vite's base property to vite.config.ts first, so the Link HTML element wil contain the correct URL, like this:

export default defineConfig({
  plugins: [svelte(), vitePluginSingleSpa({
    serverPort: 4201,
    spaEntryPoint: 'src/parcels.ts'
  })],
  base: 'http://localhost:4201' // <----  THIS!!!!
});

Build one more time, then refresh the ReactRoot's webpage. Now the style is in.

Although it might seem that we have all figured out, in reality we are far from correctness. To demonstrate this easily, let's duplicate the user text box and the parcel in the ReactRoot project, so we can see two instances of the Welcome parcel simultaneously.

Bug Found in single-spa-svelte!

The code I initially wrote for this part of the article revealed a problem with the current implementation of the singleSpaSvelte() function in the single-spa-svelte NPM package that prevents us from creating multiple instances of the same parcel. Long story short, we will be working the issue around.

If you are interested in the topic, I suggest you visit the issue I raised in GitHub.

Ok, because of the bug in single-spa-svelte, let's do some modifications to what we have right now. Let's open src/parcels.ts in the SvelteParcels project and modify it as follows:

import Welcome from "./lib/Welcome.svelte";
// @ts-expect-error
import singleSpaSvelte from 'single-spa-svelte';
import { cssLifecycle } from 'vite-plugin-single-spa/ex';


export function welcomeParcel() {
    const lc = singleSpaSvelte({
        component: Welcome
    });
    return {
        bootstrap: [cssLifecycle.bootstrap, lc.bootstrap],
        mount: [cssLifecycle.mount, lc.mount],
        unmount: [cssLifecycle.unmount, lc.unmount],
        update: lc.update
    };        
}

The short explanation is that we are now exporting a factory function that creates new parcel configuration objects whenever it is evaluated. Before, we were exporting a single parcel configuration object. Factories to the rescue!

Rebuild the SvelteParcels project, and then restart the preview Vite server.

Now let's modify src/App.tsx in ReactRoot one more time. The workaround for the bug required only one change (highlighted with a comment below). The rest of the changes pertain to the duplication of the parcel (second set of state data and markup):

import { useState } from 'react'
import reactLogo from './assets/react.svg'
// @ts-expect-error
import Parcel from 'single-spa-react/parcel'
import './App.scss'
import { mountRootParcel } from 'single-spa'

function App() {
  const [loadParcel, setLoadParcel] = useState(false);
  const [loadParcel2, setLoadParcel2] = useState(false);
  const [user, setUser] = useState<string | undefined>(undefined);
  const [user2, setUser2] = useState<string | undefined>(undefined);
  const parcelModuleName = "@test/parcels";

  async function loadWelcomeParcel() {
    const parcelsModule = await import(/* @vite-ignore */ parcelModuleName);
    return parcelsModule.welcomeParcel(); // <----- HERE!  Now welcomeParcel is a function that must be called.
  }

  return (
    <div className="app">
      <div className="row w-100">
        <div className="col-sm-5">
          <div className="root-content">
            <h1><span><img src={reactLogo} alt="React" /></span>React Root Project</h1>
            <p>
              Click the button below to load a Svelte parcel.
            </p>
            <button
              type="button"
              className="btn btn-primary"
              onClick={() => setLoadParcel(v => !v)}
            >
              Toggle Parcel
            </button>
            <button
              type="button"
              className="btn btn-primary ms-2"
              onClick={() => setLoadParcel2(v => !v)}
            >
              Toggle Parcel 2
            </button>
          </div>
        </div>
        <div className="col-sm-7">
          <div className="parcel-content">
            <h3>Parcel Display</h3>
            <div className="mb-3">
              <label htmlFor="user">User's name:</label>
              <input className="form-control" type="text" id="user" onInput={(e) => setUser(e.currentTarget.value)} />
            </div>
            {loadParcel ? <Parcel
              config={loadWelcomeParcel}
              mountParcel={mountRootParcel}
              handleError={console.error}
              user={user}
            /> : null}
            <h3>Parcel Display 2</h3>
            <div className="mb-3">
              <label htmlFor="user2">User's name:</label>
              <input className="form-control" type="text" id="user2" onInput={(e) => setUser2(e.currentTarget.value)} />
            </div>
            {loadParcel2 ? <Parcel
              config={loadWelcomeParcel}
              mountParcel={mountRootParcel}
              handleError={console.error}
              user={user2}
            /> : null}
          </div>
        </div>
      </div>
    </div>
  )
}

export default App

Re-build ReactRoot and restart the Vite preview server. Reload the webpage.

Start playing around with the "Toggle Parcel" and "Toggle Parcel 2" buttons. Notice any issues? After having both parcel instances on screen, hiding one of them also unmounts the parcel's CSS, making the remaining on-screen instance lose its correct appearance.

This behavior will also be present when simultaneously loading more than one parcel from the same parcel project, even if they are of different components. The current iteration of vite-plugin-single-spa (version 0.3.1) is unfit for parcels. Sad face.

Future Steps

Until vite-plugin-single-spa is updated to account for the parcels scenario, you will have to come up with your own CSS mounting/unmounting algorithm for your parcels project, or look for a solution elsewhere. The good news is that I, the author of vite-plugin-single-spa, will be actively working on this during the next week. You should be able to see v0.4.0 or greater coming up soon.

Potential Implementations

I'll confess I started writing this article knowing very well that my plug-in's cssLifecycle object was going to fail. This means that I have already thought about a few possible solutions. I'll explain now the two that appeal to me the most right now.

The first possible solution adds a new property to the options for micro-frontends:

    /**
     * Defines the plugin options for Vite projects that are single-spa micro-frontentds.
     */
    export type SingleSpaMifePluginOptions = {
        /**
         * The type of single-spa project (micro-frontend or root).
         */
        type?: 'mife';
        /**
         * The server port for this micro-frontend.
         */
        serverPort: number;
        /**
         * The path to the file that exports the single-spa lifecycle functions.
         */
        spaEntryPoint?: string;
        /**
         * Unique identifier given to the project.  It is used to tag CSS assets so the cssLifecyle object in 
         * the automatic module "vite-plugin-single-spa/ex" can properly manage the CSS lifecycle.
         * 
         * If not provided, the project's name (up to the first 20 letters) is used as identifier.
         */
        projectId?: string;
        /**
         * CSS strategy to be used by the cssLifecycle object in the extensions module.
         */
        cssStrategy: 'singleMife' | 'multiMife' // <----- THIS ONE !!!
    };

This new cssStrategy property will govern the CSS mounting algorithm to use. The first option, singleMife, would apply the logic that currently exists in v0.3.1. The second option, multiMife, would apply a similar logic, but this time using a counter that increases every time a parcel/micro-frontend is mounted, and decreases every time a parcel/micro-frontend is unmounted. Only if the counter reaches zero, the algorithm disables (unmounts) the HTML CSS Link elements in the HEAD element.

Why not simply upgrade to the counter version? The counter version would be incompatible with single-spa's unloading mechanism in the sense that cssLifecycle.bootstrap() currently resets the HEAD element by wiping clean any previously injected CSS Link elements. My experience with single-spa is yet very limited, and vite-plugin-single-spa hasn't reached a massive user audience yet; this might become important for users at some point in time. I just don't know if it is safe to forgo this reset feature because loading multiple single-spa lifecycle objects (be them parcels or micro-frontends) causes trouble with the current algorithm that doesn't expect bootstrap() to be called multiple times. This means that I must move the current logic inside bootstrap() to the module itself so it only runs once, so bye-bye to the CSS resetting of the HEAD element. Giving consumers the choice of strategy allows users to opt for one or another more comfortably.

Also, unloading modules exist to support potential HMR of parcel modules. Without the wiping of CSS Link elements, HMR might suffer.

The second solution that appeals to me is to create a parcel-specific project type with very specific rules about how to code it.

    /**
     * Defines the plugin options for Vite projects that are single-spa parcels.
     */
    export type SingleSpaParcelsPluginOptions = {
        type?: 'parcels';
        /**
         * The server port for this micro-frontend.
         */
        serverPort: number;
        parcelEntryPoints?: string | string[];
    };

Almost identical to the micro-frontend type, this type allows multiple entry points, but expects that the project:

Only exports parcels. It cannot export a micro-frontend.
Only exports one parcel per entry point.
Dynamic import of components is off the table because along with the JS splitting comes CSS splitting. This extra piece of CSS cannot be accounted for by my plug-in because it won't be listed in the list of CSS bundles for the entry point chunk and therefore cannot be managed.

With these guarantees in place, I can provide a CSS mounting algorithm that uses counters per CSS bundle to account for multiple instances of the same parcel and to account for any shared CSS bundles that may be needed by different parcels that might be present in the page simultaneously. The cssLifecycle object would need to be told the parcel name so it uses the correct list of CSS bundle filenames.

What do you think? Can you come up with a better solution? Let me know in the comments! I would appreciate the extra help.

Conclusion

Well, this was certainly a long journey. I think the best we can do right now is to summarize our learnings:

There is very little difference between a parcel and a micro-frontend.
Although you might hear that single-spa informally can load multiple instances of the same parcel/micro-frontend (in single-spa's slack, mostly), the reality is that this was never a design objective of the library. Attempting this requires thorough testing and probably a factory function here and there.
single-spa-react has a very handy Parcel component that simplifies the consumption of parcels, although it doesn't work with React's strict mode, most likely due to the double-render that it introduces.
The properties injected by single-spa's mountParcel() and mountRootParcel() are: name, domElement, mountParcel, singleSpa and unmountSelf. We must not use these names for other props in the component, or things will get messy. Furthermore, we cannot use as prop names the names of the props of the Parcel component, such as config, or wrapWith.
single-spa-svelte has a confirmed bug that prevents it to properly create multiple instances of a parcel/micro-frontend. Wrap the call to singleSpaSvelte() inside a factory function as a workaround.
vite-plugin-single-spa v0.3.1 is unfit for parcels in general. Wait for a newer version to come out.

That is all for today. Let me know if you have questions or would like me to cover a specific scenario or topic around single-spa, my plug-in or any combination of frameworks. I'll try to comply.

Happy coding!