Forem: BookOfCooks

HTMX is hard, so let's get it right

BookOfCooks — Sun, 03 Aug 2025 13:58:52 +0000

Disclaimer: I originally planned to make a simple non-functional uploader, then progressively bring it from "it works™" to "high-quality and production-grade with S3 Presigned, Multipart, and Accelerated Uploads " all in HTMX (hence the title).

However, just laying the foundation proved to be a really long post, so I'm breaking up into two pieces. This is the first piece, that establishes the basics.

Disclaimer over.

Imagine this, you're building a "Soundtrack Uploader" for the admin page.

You've built all the designs/screens, now it needs to work.

Here's a preview:

What's going on here?

We have a Go backend serving the Stepper page, with the 1st step being a form.

Each step is a <form> that calls an endpoint like /form/step1 and swaps out itself with the returned form (which should be the <form> of the next step).

templ Step1() {
    <form hx-post="/form/step1" hx-target="this" hx-swap="outerHTML">
        <fieldset class="fieldset mb-2">
            <legend class="fieldset-legend">Name of the instrument?</legend>
            <input type="text" name="name" class="input" placeholder="Ex: Piano" required/>
        </fieldset>
        <button class="btn btn-neutral">Submit</button>
    </form>
}

The backend then processes the data, and returns the next <form>:

func formStep1(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    name := strings.TrimSpace(r.FormValue("name"))
    if len(name) == 0 {
        return pox.Templ(http.StatusOK, templates.AlertError("Name cannot be empty")), nil
    }
    return pox.Templ(http.StatusOK, templates.Step2()), nil
}

What's wrong here?

Let's start with the obvious one. The step-labels on the left are not highlighted.

As we progress through this article, we'll face harder & harder problems as we bring this application to production-grade.

Challenge 1: Highlight Current Step

Difficulty: easy
Obviously, swapping the <form> was not enough, we need to swap the entire Stepper!

Or: If you had other elements in Stepper you didn't want to swap, then you'll need out-of-bound swaps to swap just the left column (OOB are always a context nightmare)

If your template language of choice allows you to embed children into a template, then you can break each step (<form>) into their own templates:

templ Step1() {
    <form hx-post="/form/step1" hx-target="this" hx-swap="outerHTML">
        ...
    </form>
}

templ Step2() {
    <form
        hx-post="/form/step2"
        hx-target="this"
        hx-swap="outerHTML"
        x-data
        x-ref="form"
        hx-encoding="multipart/form-data"
    >
        ...
    </form>
}

templ Step3() {
    <form hx-post="/form/step3" hx-target="this" hx-swap="outerHTML">
        ...
    </form>
}

templ Step4() {
    <form>
        ...
    </form>
}

Then render the initial page with Step1 as the child of the Stepper template:

templ Home() {
    <!DOCTYPE html>
    <html lang="en">
        <head>
            ...
        </head>
        <body>
            @header()
            @Stepper(1, Step1())
        </body>
    </html>
}

var steps = []step{
    {name: "Choose Name", number: 1},
    {name: "Upload File", number: 2},
    {name: "Upload Markers", number: 3},
    {name: "Review", number: 4},
}

templ Stepper(currentStep int, child templ.Component) {
    <div class="container flex mx-auto px-4" id="stepper">
        <ul class="steps steps-vertical">
            for _, step := range steps {
                <li class={ map[string]bool{"step": true, "step-primary": currentStep >= step.number} }>
                    { step.name }
                </li>
            }
        </ul>
        <div class="flex-1 p-4">
            @child
        </div>
    </div>
}

Let's see what we have so far:

Interesting? It seems we're losing the entire left column! Some of you already know why, but for those that don't, how can we debug this?

The most basic tool of all, "Inspect"!

Admittedly, it's a little hard to follow. But if you look closely, you can see that <div id="stepper"></div> gets replaced with just a <form>.

To illustrate:

That's because our backend endpoints only returns a <form>, and that swaps the entire #stepper. Let's make a change so each endpoint returns a new stepper:

func formStep1(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    // ...
//  return pox.Templ(http.StatusOK, templates.Step2()), nil
    return pox.Templ(http.StatusOK, templates.Stepper(2, templates.Step2())), nil
}

func formStep2(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    // ...
//  return pox.Templ(http.StatusOK, templates.Step3()), nil
    return pox.Templ(http.StatusOK, templates.Stepper(3, templates.Step3())), nil
}

func formStep3(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
//  return pox.Templ(http.StatusOK, templates.Step4()), nil
    return pox.Templ(http.StatusOK, templates.Stepper(4, templates.Step4())), nil
}

As a result, we've completed the first challenge:

Lesson learned: sometimes you need to make the unintuitive choice of replacing the entire parent to swap out a child.

Challenge 2: Passing data down each step

Difficult: Intermediate

You may have noticed at the beginning of the article, the name I wrote in Step 1 didn't match the name in Step 4 (Review).

Because it's all dummy data!

Fortunately, sending data to the server with HTMX is easy. State management on the other hand? That's a little harder.

How do you pass data from one step to the other?

There's several approaches that can integrate with our existing workflow:

Approach #1: each step/endpoint returns the next <form>, with a hidden <input> containing all the data from the previous steps.

This approach of passing down a copy of the data has a couple downsides. For one, you need to revalidate ALL OF THE DATA with each step.

Second, it's "just ain't it y'know".

Approach #2: create a temporary server-side long-lived form session, that is attached to the user's session via an ID.

We'll use approach #2.

So let's split this up in several steps:

The user opens /form

1.1: A FormSession is generated server-side with a unique id
1.2: Serve Step1 to the user, with FormSession.Id sent in an invisible <input>
When the user submits Step1:
2.1: HTTP POST /form/step1
2.2: the server validates the data, and saves it to the associated FormSession (via the id).
2.3: the server serves Step2 (with another invisible <input> having the id)
Repeat #2 for the rest of the steps
Profit

We're using Golang for this application, but this is applicable to any language.

Also note that we're using in-memory storage, in addition to no safety measures at all (no mutex or such), as the focus of this article is on HTMX, not production grade systems (YET!).

TLDR: Copy my ideas, not my implementation!

Step 1: Serve initial page with `FormSession`

Here's where we're at:

func home(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    return pox.Templ(http.StatusOK, templates.Home()), nil
}

Let's create a unique form session, and send it to the user:

type FormSession struct {
    Id         string
    Name       string
    Soundtrack string
    Markers    []Marker
}

type Marker struct {
    Name  string
    Start time.Duration
}

var sessions = map[string]*FormSession{}

func home(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    // In production-grade systems, you'll might save this into a Database
    sessionId := uuid.NewString()
    // In real code, don't write to `sessions` without mutex
    sessions[sessionId] = &FormSession{Id: sessionId}
    return pox.Templ(http.StatusOK, templates.Home(sessionId)), nil
}

Our Home template passes sessionId to Step1:

templ Home(sessionId string) {
    <!DOCTYPE html>
    <html lang="en">
        <head>
            ...
        </head>
        <body>
            @header()
            @Stepper(1, Step1(sessionId))
        </body>
    </html>
}

templ Stepper(currentStep int, child templ.Component) {
    <div ...>
        <!-- Render `child` -->
        @child
    </div>
}

templ Step1(sessionId string) {
    <form hx-post="/form/step1" hx-target="#stepper" hx-swap="outerHTML">
        <!-- This invisible input is where the magic is -->
        <input type="hidden" name="sessionId" value={ sessionId }/>

        <fieldset class="fieldset mb-2">
            ...
        </fieldset>
        <button class="btn btn-neutral">Submit</button>
    </form>
}

After submitting the first step of the form, you'll notice the sessionId sent along with the name:

Step 2: Mutate session on server, then send the next `<form>`

Right now, /form/step1 simply reads the name, does nothing with it, and sends the next form:

func formStep1(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    name := strings.TrimSpace(r.FormValue("name"))
    if len(name) == 0 {
        return pox.Templ(http.StatusOK, templates.AlertError("Name cannot be empty")), nil
    }
    return pox.Templ(http.StatusOK, templates.Stepper(2, templates.Step2())), nil
}

Let's read the sessionId, mutate the associated session, then send the <form> along with that same sessionId.

func formStep1(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    name := strings.TrimSpace(r.FormValue("name"))
    if len(name) == 0 {
        return pox.Templ(http.StatusOK, templates.AlertError("Name cannot be empty")), nil
    }

    sessionId := r.FormValue("sessionId")
    // In real code, protect with a mutex!
    // WARNING! ENSURE `sessionId` EXISTS IN `sessions`, OTHERWISE YOUR SERVER WILL PANIC AND CRASH!!!
    sessions[sessionId].Name = name

    return pox.Templ(http.StatusOK, templates.Stepper(2, templates.Step2(sessionId))), nil
}

Step 2.1: quick challenge, display the name chosen in Step 1 inside Step 2

When learning, it's good to make little milestones that, upon completion, give a sense of progress and achievement.

How can we achieve this?

Turns out to be incredibly easy actually!

Let's make the Step2 template take a name, and then display it:

templ Step2(sessionId string, name string) {
    <form ...>
        <p class="mb-2">Upload an audio file for <b>"{ name }"</b> (ex: mp3, wav, opus, etc)</p>
        ...
    </form>
}

Then pass the name into the template from the backend route:

func formStep1(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    name := strings.TrimSpace(r.FormValue("name"))
    //...

    sessionId := r.FormValue("sessionId")
    sessions[sessionId].Name = name

    // Passing `name` over here
    return pox.Templ(http.StatusOK, templates.Stepper(2, templates.Step2(sessionId, name))), nil
}

Step 3: (rapid fire) mutate session, give it to the next one

Most of the following will be rather tedious, so skip if you think you already got it.

Inside [Step 2's template], put invisible input:

templ Step2(sessionId string, name string) {
    <form ...>
        <input type="hidden" name="sessionId" value={ sessionId }/>
        ...
    </form>
}

Inside [Step 2's backend handler], we do a fake s3 upload and mutate the session:

func formStep2(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    file, headers, err := r.FormFile("file")
    if err != nil {
        return pox.Templ(http.StatusOK, templates.AlertError("Cannot open file, please contact tech support!")), fmt.Errorf("r.FormFile: %w", err)
    }

    // In real code, avoid using `headers.Filename` (or at least with safety precautions)
    uploadUrl, err := FakeS3Upload(headers.Filename, file)
    if err != nil {
        return pox.Templ(http.StatusOK, templates.AlertError("Cannot upload file, try again")), fmt.Errorf("FakeS3Upload: %w", err)
    }

    sessionId := r.FormValue("sessionId")
    sessions[sessionId].Soundtrack = uploadUrl

    // Let's log the data we have so far
    litter.Dump(sessions[sessionId])

    // Don't forget to pass `sessionId` to next step
    return pox.Templ(http.StatusOK, templates.Stepper(3, templates.Step3(sessionId))), nil
}

Again in [Step 3 Template]

templ Step3(sessionId string) {
    <form hx-post="/form/step3" hx-target="#stepper" hx-swap="outerHTML">
        <input type="hidden" name="sessionId" value={ sessionId }/>
        ...
        <button class="btn btn-neutral">Submit</button>
    </form>
}

Step 3 is a little unique in that we might upload a file if a certain method is picked. (As a matter of fact, it'll be its own challenge in the next blog post!)

For now, we'll just assign an empty array to the FormSession

[Step 3's Backend Handler]:

func formStep3(w http.ResponseWriter, r *http.Request) (http.Handler, error) {
    sessionId := r.FormValue("sessionId")
    session := sessions[sessionId]
    session.Markers = []Marker{}

    return pox.Templ(http.StatusOK, templates.Stepper(4,
        // This time we pass extra information, as this is the review step
        // Markers are TODO
        templates.Step4(sessionId, session.Name, session.Soundtrack),
    )), nil
}

Finally, [Step 4 Template]:

templ Step4(sessionId string, name string, soundtrackUrl string) {
    <form>
        <input type="hidden" name="sessionId" value={ sessionId }/>
        <p class="mb-4">Review all information</p>
        <hr class="mb-4"/>
        <p class="mb-4">Name: <b>{ name }</b></p>
        <p class="mb-4 flex gap-2 items-center">
            Audio:
            <audio src={ soundtrackUrl } controls></audio>
        </p>
        <table class="table table-zebra mb-4">
            ...
        </table>
        <button class="btn btn-neutral">Submit</button>
    </form>
}

Step 4 doesn't have its own backend handler yet.

Conclusion

It turns out this blog post ended up being WAY LONGER than I originally hoped. And we haven't even made it to the "HARD" parts (per the title).

I promise though, we'll be solving the real problems in the next continuation of the article.

So far though, we've managed to create a multi-step form in HTMX, and save the data from each step in the server.

The next challenges in the continuation will be architecturally focused (and less about the code).

Need help? Get in contact

I'm reachable through the comments on this blog, or at my email bookofcooks123@gmail.com. I'm willing to help answer questions and such anytime.

You might also find me on the FlutterDev and HTMX discords.

I'm also open to job opportunities, y'know if you need someone with expertise in Flutter, Golang, SvelteKit, and/or HTMX ;D

Maintaining large RxDart Projects Series - Part 1

BookOfCooks — Wed, 30 Jul 2025 13:41:56 +0000

I'm the developer of a family project, Prayershub, that aims to enhance worship services for families and church alike. At the core of the app is the Worship, which is a playlist of songs, bible verses, and prayers.

The app is now several years old, and the entire "Worship" section of the app is now a couple thousand LOC of tightly coupled RxDart streams, which I have to maintain.

As a way of keeping my sanity, I've decided to start write down approaches I'm taking to help keep the app more maintainable and make it easier to introduce new features into.

Today, I'm trying:

Bundle multiple streams into classes

Nothing too fancy or complicated, just basic refactoring to start with.

Above is a picture of the app. The "Play" button at the bottom of the screen will, upon being pressed, play each item in the worship one-after-another.

The black play button next to each item is a solo play button. It will only play that single item.

That single button combines 4 streams:

Stream<bool> running$: Is the worship playing (either solo or personal)
Stream<int?> soloing$: the current item being soloed (if null, we're not in solo mode)
Stream<bool> audio.playingStream: is the worship_audio_file (a single mp3 file that's the concatenation of all items (oversimplified)) playing?
Stream<bool> soloAudio.playingStream: is the solo_audio_file (a AudioPlayer who's src changes if an item is picked for solo) playing?

Here's the resulting code

StreamToWidget( // custom wrapper around StreamBuilder
// --- the stream
  Rx.combineLatest4(
    running,
    soloing$,
    audio.playingStream,
    soloAudio.playingStream,
    (running, soloing, playing, soloAudioPlaying) {
      return (
        running: running,
        soloing: soloing,
        playing: playing,
        soloAudioPlaying: soloAudioPlaying,
      );
    },
  ),
// --- the converter
  converter: (data) {
    bool isActive = data.soloing == contentIndex;
    bool isPaused = isActive && !data.playing;

    if (soloMap != null && soloMap![content.id] != null) {
      isPaused = isActive && !data.soloAudioPlaying;
    }

    if (data.running && data.soloing == null) {
      return const SizedBox();
    }

    return SoloButton(
        ...
    );
  },
)

Let's focus specifically on Rx.combineLatest4. This is a stream that combines multiple streams, and I've used this in many places across the app.

The BottomAppBar that contains all the buttons for controlling the playlist, combines a total of 7 streams!

StreamBuilder(
  stream: CombineLatestStream.combine7(
    contents$,
    running,
    audio.playingStream,
    soloAudio.playingStream,
    editing,
    soloing$,
    showCountdown,
    (a, b, c, d, e, f, g) => (
      contents: a,
      running: b,
      playing: c,
      soloPlaying: d,
      editing: e,
      soloing: f,
      showCountdown: g
    ),
  ),
  initialData: (
    contents: <WorshipContent>[],
    running: false,
    playing: false,
    soloPlaying: false,
    editing: false,
    soloing: null,
    showCountdown: false,
  ),
  builder: (context, snapshot) {
    var (
      :contents,
      :running,
      :playing,
      :soloPlaying,
      :editing,
      :soloing,
      :showCountdown
    ) = snapshot.requireData;
    if (contents.isEmpty || editing || showCountdown) {
      return const SizedBox.shrink();
    }

    // ... lots of code
  },
)

I decided to factor the resulting data of the stream into an actual class WorshipBottomBarModel (rather than a tuple, which makes for terrible error messages in VSCode (the LSP specifically)).

Then I add a fromStreams() method to this WorshipBottomBarModel, that accepts 7 streams and returns a Stream<WorshipBottomBarModel>.

The result looks like this:

StreamBuilder(
  stream: WorshipBottomBarModel.fromStreams(
    contents: contents$,
    running: running,
    playing: audio.playingStream,
    soloPlaying: soloAudio.playingStream,
    editing: editing,
    soloing: soloing$,
    showCountdown: showCountdown,
  ),
  initialData: WorshipBottomBarModel(
    contents: <WorshipContent>[],
    running: false,
    playing: false,
    soloPlaying: false,
    editing: false,
    soloing: null,
    showCountdown: false,
  ),
  builder: (context, snapshot) {
    var data = snapshot.requireData;
    if (data.contents.isEmpty || data.editing || data.showCountdown) {
      return const SizedBox.shrink();
    }

    // ... lots of code
  },
),

With this change, I can F2 rename the data on this model to better reflect their purpose or reason. In addition, I could add a default factory method that constructs the initialData for the StreamBuilder.

StreamBuilder(
  stream: WorshipBottomBarModel.fromStreams(
    contents: contents$,
    isWorshipRunning: running,
    isWorshipAudioPlaying: audio.playingStream,
    isSoloAudioPlaying: soloAudio.playingStream,
    isEditing: editing,
    isSoloing: soloing$,
    hideBar: showCountdown,
  ),
  initialData: WorshipBottomBarModel.defaultData(),
  builder: (context, snapshot) {
    var data = snapshot.requireData;
    if (data.contents.isEmpty || data.editing || data.showCountdown) {
      return const SizedBox.shrink();
    }

    // ... lots of code
  },
),

Going back to the Solo Button combiner, here's what theses changes look like (note we're using my custom StreamToWidget)

StreamToWidget(
  SoloDataModel.fromStreams(
    isWorshipRunning: running,
    soloedContent: soloing$,
    worshipAudioPlaying: audio.playingStream,
    soloAudioPlaying: soloAudio.playingStream,
  ),
  converter: (data) {
    bool isSoloed = data.soloedContentIndex == contentIndex;
    bool hasDedicatedSoloTrack =
        soloMap?.containsKey(content.id) == true;
    bool isSoloPaused = isSoloed &&
        (hasDedicatedSoloTrack
            ? !data.soloAudioPlaying
            : !data.worshipAudioPlaying);

    if (data.isWorshipRunning &&
        data.soloedContentIndex == null) {
      return const SizedBox();
    }

    return FloatingActionButton.small(
        // .. lots of code
    );
  },
)

Your ideas?

I'll continue what I can to bring new features into the app, and writing down any progress that I make.

If anyone else find themselves in this situation, how do you deal with it, please write your ideas down below.

In the meantime, if you find yourself struggling with difficult problems with RxDart (or even RxJS!), you can comment them down below, or email me at bookofcooks123@gmail.com.

I've dealt with this technology and reactive state management for more than half a decade, so I'm willing to help (no charge).

You can also ask on the FlutterDev and The Programmer's Hangout help channels. I'm active there, along with hundreds of people willing to help.

How I make teams productive

BookOfCooks — Wed, 23 Jul 2025 22:54:25 +0000

Below are a couple of practices I implement to not only boost my own productivity & speed, but the speed of my team.

Some of them are oriented around getting new devs up to speed quickly, while others are meant for enhancing current team members.

1. Invest in your Dev Environment

For one of the projects I've worked on, Prayershub, it takes about a week to setup a dev environment. It integrates with AWS, Typesense, MariaDB, PHPMyAdmin, CPanel, CaddyServer, on top of several dev tools to hot-reload HTML and connect with the accompanying Flutter app.

One day, I finally decided to invest 2-3 weeks into making a predictable, versioned, reliable dev environment. And that investment has paid off very well for itself. To get a new dev onboard (whether they use Windows Or Ubuntu Linux) is as simple as:

Install Docker (or Docker Desktop on Windows)
Install VSCode (with Devcontainers plugin)
Clone repository
Copy .env.sample to .env
Run

I've even setup some integration to get a filtered copy of the production database and import straight through PHPMyAdmin. The entire thing is seamless and takes about an hour.

The Go app automatically starts up and connects with the Flutter app, no problem.

What used to take 3 weeks to setup 3-5 devices can now done reliably in 1 hour, with no loss to hot-reloading tools or performance at all.

I have it setup in several layers, each building on top of each other:

A docker/prod/Dockerfile with the necessary components for production (Typesense & FFmpeg)
A docker/dev/Dockerfile that builds on docker/prod/Dockerfile and installs all the dev tools for local development (Go, Templ CLI, Actiongraph, Make, etc)
A compose.yaml (which builds upon docker/dev/Dockerfile) for setting up environments (separate from tools).

For example: MariaDB, Caddyserver, Apache (for PHPMyAdmin).
devcontainer/devcontainer.json (which builds upon compose.yaml) for setting up extensions for VSCode (and possibly others if the dev wishes to use something like Neovim)

1 is for production, #2 is for quick debugging or testing that don't require the full IDE experience. #3 and #4 are for fully fledged IDE experiences.

2. Fast Feedback Loop

This refers to the amount of time between making a code change and observing the result. What this means and what can be considered "fast", varies widely by context and industry.

For example, SvelteKit Hot Module Reloading works in the order of milliseconds. It's so well optimized that you can make a change, and observe it in your browser (no need to refresh, either manually or automatically).

It does have some quirks to it (a lot in my experience), but for the most part it's insanely productive compared to other solutions that require rebuilding the entire application to make a color change.

That doesn't mean you have to throw out your current stack to make your iterative cycles faster though. There's a couple things you can do across any language or stack to speed up development.

2.1: Decrease startup time

This is the amount of time it takes for the server to startup. You can do this by deferring as much work as possible for later. At Prayershub, startup time was around 5 seconds. This time would be spent downloading fonts, connecting to AWS, refreshing typesense, among others.

Simply deferring this tasks took the iterative cycle down from 5s to 0.4s. Of course, some are more difficult than others, and required new abstractions like Futures and such. Nevertheless, this was a worthwhile investment

2.2: Decrease compilation time

Decreasing compilation time for your projects can mean different things depending on the language.

PHP doesn't have a compilation time at all. Typescript does (and its among the slowest I've used). Golang does, and it's the fastest I've used.

That doesn't mean it's time to blame the language. It's the 100s of packages upon packages you import that determine how slow and bogged down your iterative cycle will be. The language merely puts that threshold a little lower or higher.

For example, in Go, recompiling one of the modules simply took too long, because that module depended on the AWS Go SDK (which hosted the APIs for ALL OF AWS, EVERY. SINGLE. SERVICE). At that moment, I had to make a decision.

Is it better that the whole team gets slowed massively throughout the years, like walking with ankle weights?

Or should I spend the necessary 2 days to make a tiny API that only called out to the single service of AWS we needed?

I went with the latter, and looking back, it turned out to be the best choice.

This advice carries over to other languages as well. It's not always necessary to import library to solve your every problem. Sometimes, it's worth it to pay an upfront cost right now, then a slow ongoing cost that charges interest.

2.2: Hot-Reloading Tools are good

I'll keep this brief, since this is quite obvious. In Go, I used Air when building CLIs, or Templ for websites (so I don't have to rebuild and rerun the server when I update the HTML, and still have typesafe templates).

Hot reloading is good, and applaud frameworks that strive to make it better. SvelteKit has one of the best, and even industry giants like Angular are finally investing time into making their HMR story better.

3. Invest in yourself outside work

This is probably the most controversial one, although it really shouldn't be! For an industry were it takes years to get a stable foot in the door, and many more years to become a highly sought-after expert, sticking to improving your skills solely during work is a recipe for failure.

Take time, outside work, to work on hobby projects. Not all of them (or even any of them) need to have an apparent purpose. Just something that interests and keeps your coding and building on your problem solving skills.

I say this because, in any project (work or hobby), there are many side quests you'll engange in to reach the goal. While the project itself may be of little value, those skills gained from those side quests are very much transferable to real work (and often niche).

As a matter of fact, the only reason I got into Docker was because I didn't want to setup Apache, then PHPMyAdmin, then find the specfific php.ini out of a 100 php.ini(s) to increase the upload_max_filesize.

Recently learned git blame while debugging & filing a bug for popular template language for Go.

How does this make the team productive?

Simply, being a good engineer with good skills means you can help coworkers. They are entire swaths of people who's whole job is just unblocking their team members on difficult issues.

Not everyone is willing to do this however. Some people probably aren't even in a situation where that's possible. And that's okay!

But you'll be a very valuable asset to the team if you do.

Read The Worst Programmer I Know.

Reconnecting Websockets with RxDart

BookOfCooks — Wed, 02 Jul 2025 15:00:28 +0000

Quick Background Context

Prayershub is an app that allows users to create playlists (called Worships) that contain songs, psalms, and prayers. A user can "Start" a Worship, which automatically plays through playlist's contents one-by-one.

In addition, users can "Broadcast" a Worship, which starts a 5-minute countdown, during which, other users can "Join" the worship. Upon the countdown's completion, the playlist starts simultaneously across all devices joined in.

The devices sync with the master controller (owner of the worship), who can go next/back/pause/resume or abort.

The state management of WorshipPage comprises entirely of RxDart and StreamBuilders, along with WebSockets as the backend technology for "Broadcast".

The Current State

The WorshipPage has a "socket" field of type Stream<WebSocket> that replays the latest stream.

class _WorshipPageState extends State<WorshipPage> {
  // ...
  late ReplayStream<WebSocket> socket = WebSocket.connect(
    "$websocketPath/live-worship/${widget.worship.id}",
    headers: {"accesstoken": mainAccessToken},
  ).asStream().shareReplay(maxSize: 1);
  // ...
}

Apparently, socket was made a Stream<WebSocket> to allow it to compose with other streams that would in turn be composed into more streams.

class _WorshipPageState extends State<WorshipPage> {
  // ...
  late ReplayStream<WebSocket> socket = WebSocket.connect(
    "$websocketPath/live-worship/${widget.worship.id}",
    headers: {"accesstoken": mainAccessToken},
  ).asStream().shareReplay(maxSize: 1);

  late var socketMessages = socket.switchMap((s) => s.map((m) => m.toString())).share();

  late var countdownEndedSocketMessage = socketMessages.where((p) => p == "countdown_ended").map((_) => true).share();
  late var abortSocketMessage = socketMessages.where((p) => p == "abort").map((_) => true).share();
  // ...
}

I personally believe there's better way to manage state than RxDart, and even with RxDart this could've been done better. However, it isn't all to bad and implementing reconnecting sockets shouldn't be too difficult.

Implementation

socketMessages listens to socket and maps the socket to a Stream<string> messages with switchMap. The switchMap operator means that when a new socket is passed through the socket stream, socketMessages will stop listening to the old WebSocket and will listen to the new WebSocket.

That's perfect!

All we need to do is have the socket stream emit a new WebSocket every time the old WebSocket disconnects.

class _WorshipPageState extends State<WorshipPage> {
  late ReplayStream<WebSocket> socket =
      createReconnectingSocket().shareReplay(maxSize: 1);

  Stream<WebSocket> createReconnectingSocket() async* {
    while (true) {
      var socket = await WebSocket.connect(
        "$websocketPath/live-worship/${widget.worship.id}",
        headers: {"accesstoken": mainAccessToken},
      );

      yield socket;

      await socket.onDisconnected;
    }
  }
}

Only one issue, onDisconnected is not a real property of WebSocket. Fortunately, doOnDone is, and we can change our code to:

  Stream<WebSocket> createReconnectingSocket() async* {
    while (true) {
      var socket = await WebSocket.connect(
        "$websocketPath/live-worship/${widget.worship.id}",
        headers: {"accesstoken": mainAccessToken},
      );

      yield socket;

      await socket.doOnDone(() {}).first;
    }
  }

However, starting up the app immediately panics with Bad state: Stream has already been listened to. Logs reveal this line as the problem: await socket.doOnDone(() {}).first;

Because WebSocket implements Stream<dynamic>, we can call listen and doOnData methods on it. Therefore, the steps to the exception can be modeled as followed.

We yield socket in createReconnectingSocket
The socket stream emits a WebSocket
socketMessages emits a Stream mapping over WebSocket, broadcasting the result
Multiple StreamBuilder(s) listen to socketMessages
doOnDone() listens to the WebSocket (already listened to by step #4 through a broadcast), and crashes the process

To get around this, we can broadcast the WebSocket, and then emit that broadcasted result, as well as wait for broadcast stream to end (which signals the WebSocket has closed/terminated.

  Stream<WebSocket> createReconnectingSocket() async* {
    while (true) {
      var socket = await WebSocket.connect(
        "$websocketPath/live-worship/${widget.worship.id}",
        headers: {"accesstoken": mainAccessToken},
      );

      // ↓↓↓↓↓
      var broadcast = socket.asBroadcastStream();

      yield broadcast;

      await broadcast.doOnDone((){}).first;
    }
  }

However, the Dart LSP complains:

A yielded value of type 'Stream<dynamic>' must be assignable to 'WebSocket'

Except the stream returned by asBroadcastStream cannot be casted to a WebSocket, simply because WebSocket is more than just a Stream.

But wait! We've practically achieved our objective haven't we? Sure we're not re-emitting WebSocket, but we are re-emitting Streams of messages Stream<String>, which is all the consumers need.

We can change createReconnectingSocket signature to:

// Stream<WebSocket> createReconnectingSocket() async* {
Stream<Stream<String>> createReconnectingSocket() async* {

Now the component looks like this:

class  _WorshipPageState  extends  State<WorshipPage> {
  late ReplayStream<Stream<String>> socket =
      createReconnectingSocket().shareReplay(maxSize: 1);

  late var socketMessages = socket.switchMap((messages$) => messages$).share();

  Stream<Stream<String>> createReconnectingSocket() async* {
    while (true) {
      var socket = await WebSocket.connect(
        "$websocketPath/live-worship/${widget.worship.id}",
        headers: {"accesstoken": mainAccessToken},
      );

      var broadcast = socket.asBroadcastStream().map((s) => s.toString());

      yield broadcast;

      await broadcast.doOnDone(() {}).first;
    }
  }
}

At this point, all errors disappear, except for one. At the very bottom of the file:

 @override
 void dispose() {
   socket.listen((ws) => ws.close()); // fails to build
   WakelockPlus.disable();
   for (var sub in subs) {
     sub.cancel();
   }
   audio.dispose();
   soloAudio.dispose();
   super.dispose();
 }

Originally, listening to Stream<WebSocket> socket would immediately emit a WebSocket that dispose would close. However, now that socket is a Stream<Stream<String>>, we lose that functionality.

What we could do is have createReconnectingSocket return both the socket and stream. Alternatively, createReconnectingSocket can accept a close stream to check if it receives the close message before the socket closes.

If close emits an item first, then we close the WebSocket and return. Now dispose just needs to send an event to close (of type Subject<void>).

Possible Improvements

You can very neatly reconnect WebSockets using Dart's async generators and RxDart. However, there are others ways of going about it depending on want you want.

For example, if you'd like the user to know if the WebSocket is connecting, connected, or failed, you might create a Stream<Future<WebSocket>> websocket along with publishReplay().

Each this Stream<Future<WebSocket>> emits a Future<WebSocket>, that represents a new attempt to connect a WebSocket.

When that emitted Future completes successfully, that represents a connected WebSocket. If the future fails, that represents a failed connection.

If you append publishReplay to this Stream<Future<WebSocket>> , thenconnect it in initState, late subscribers to this stream will get the latest Future<WebSocket>.

If that Future<WebSocket> has already completed, then the late subscribers immediately receives the WebSocket, which will be the latest established WebSocket.

Need Help?

I work with RxDart and Flutter on a daily basis, so I'm willing to help. You can either put your requests in the comments or contact me at bookofcooks123@gmail.com.

I also work on backends in JavaScript, PHP, or Golang, so I'm open to questions on working with WebSockets in those areas if needed.