The Case for Spark

[bencroker]

Sprig has been a labour of love for the past 4 years, and while it has proven extremely popular, I’ve noticed some shortcomings to its overall approach.

1. Its API is coupled to that of htmx.

Sprig builds on top of htmx and is closely coupled to it. As new features (and scope creep) are added to htmx, they are naturally added to Sprig. So while Sprig adds its own concept of Twig components, the mechanism by which it works is heavily dependent on that of htmx.

2. It only solves part of the problem.

Sprig provides the ability to re-render Twig templates on the back-end and swap them into the DOM on the front-end, but it lacks pure front-end reactivity. I’ve written about the htmx API and how it can be used to react to events on the page, but most developers still reach for a JavaScript library like Alpine JS to facilitate front-end reactivity.

3. It uses an antiquated, suboptimal approach.

Sprig adds reactive components to Twig. While the concept is relatively straightforward to grasp, it results in more Twig code rendered than necessary, more HTML sent over the wire than necessary, and more of the DOM swapped out than necessary. Also, swapping multiple parts of the DOM requires either multiple request-response cycles, or the use of out-of-band swaps (a clumsy API that Sprig attempts to simplify but which can still be confusing).

---

Spark aims to address the shortcomings above by:

1. Decoupling the mechanism (as much as possible).
2. Solving both back-end and front-end reactivity in a cohesive manner.
3. Using a more modern, optimal approach.

Part of how it does this is by leveraging Datastar, a JavaScript library that combines the core functionality of Alpine JS with that of htmx. Datastar takes a hypermedia-first approach, meaning that you won’t find history support, JavaScript execution in responses, nor any other “bells and whistles”. This is intentional. By embracing the simplicity of hypermedia, the encapsulation of web components (natively or using Lit) and the optimised DOM operations of web browsers, you can build highly performant, hypermedia-driven web apps, without requiring a full-blown JavaScript framework.

Read Datastar’s getting started guide.

Spark uses Datastar for interacting with the back-end (via its back-end plugins), and provides a simple API for which to do so. Take a look at the usage docs to see what it looks like.

So how does Spark actually address the shortcomings above?

By giving you less functionality, Spark encourages forces you to drive your web apps using hypermedia. It is a very thin layer on top of Datastar, which gives you a front-end data store that shares its state with (and is driven by) the back-end.

Datastar uses SSE (server-sent events), which allows a web server to push multiple, real-time updates to the browser over a single HTTP connection. As each template is rendered, it is sent to the web browser via a server-sent event, meaning that elements are streamed in the response and modified in the DOM as soon as the web browser receives them. This may seem like an unusual super-power, but it makes creating highly performant responses possible [needs more explanation].

But what does one do without all the “bells and whistles” that htmx provides? Is this really progress?? Wasn’t “htmx sucks” only meant as tongue-in-cheek?!?

The idea with Datastar (and Spark) is to go back to first principles while moving the web forward. Web components should be used (natively or using Lit) to provide reusable, encapsulated, and framework-agnostic custom elements. Because when you embrace custom elements you are embracing hypermedia.

---

If you are interested in hypermedia driven apps (and concepts such as HOWL and HATEOS, I encourage you to give Datastar and Spark a go. I’m specifically interested in your thoughts on the Spark API and its approach to performing actions and modifying the DOM and state.

In my experience, adopting this approach means unlearning a lot of the concepts that using Sprig has spoiled me with. Thanks go to Delaney Gillilan, author of Datastar, who has patiently answered my questions and addressed my reservations, and who has persistently reminded me that “just because you can, doesn’t mean you should”.

[delaneyj]

I think this is amazing and will elevated the usage of PHP forward a ton!

[bencroker]

I’ve extracted most of the Datastar specific functionality to a framework agnostic PHP package:
https://github.com/putyourlightson/datastar-php

[bencroker]

I’ve created a Spark demo of an inline table editing app. It was a fun process and took me around half an hour to build. It uses signals (via data-store) for most of its interactivity, making it extremely snappy to use. Only on saving an entry is a POST request made to the server, which responds with an element containing the new title, an element containing an empty alert (to clear out errors), and resetting the store value of entryId to 0. If there’s an error then it sends back the first errors in an alert.

This nicely demonstrates the power of signals combined with real-time Twig template rendering, resulting in only the parts of the DOM that need swapping being sent down over the wire.

Go check out the source code (and run it on your own Craft development environment).

spark-demo-inline-table-editing.mp4

Note

editingId (as seen in the video) was changed to entryId in the source code, for clarity.

[wsydney76]

@bencroker Thanks, im using this now, passing only the relevant params:

{% set response = spark.runAction('entries/save-entry', {
    entryId: store.entryId,
    title: store.title,
}) %}

This slug is still updated however, so query params are not completely replaced, but merged?

Not sure if this helps but using a _prefix means that signal won't be sent

@delaneyj Yes, looks like that would help for frontend-only things.

PS.
Would be a fun thing to make this example real-world-usable in Spark, but doubt I'll find time/skills/energy to work on it. For now I have thrown together a reference Alpine implementation, mostly recycling existing logic/code, that shows how it might look like in the end.

Gist

[bencroker]

Yes, because you’re running the same version of Spark. I just released 0.0.12, in which the store is no longer passed through to controller actions, so they must be passed in the second argument of spark.runAction.

Quickly looking at your Gist, my guess is that you could end up deleting around half of your code when using Spark.

[delaneyj]

Half is a good number!

[wsydney76]

@bencroker Thanks, works now in 0.0.12.

my guess is that you could end up deleting around half of your code when using Spark.

Hm, not sure where that should come from...

- drop fetch command
- drop translation handling in JS
+ add unsupported stuff like x-trap.inert.noscroll (no, not willing to drop that)
+ whatever it takes to live in the context of a 'global store'
+/- all other things like calling the server, evaluating action response, displaying errors, fine grained keyboard and focus control etc. etc. have to be coded somewhere in some way. Suspecting that every x-something becomes a data-something with a comparable amount of code behind it.
----------------------------------
= only an equally featured port will tell.

(Having no custom backend component at all in this example is hard to beat...)

PS.
Either way, you will spend most of your time going through 47 iterations with your client.

[bencroker]

Having no custom backend component at all in this example is hard to beat...

With close to 200 lines of JavaScript code, I tend to disagree.

[mandrasch]

Great write-up! 👏👏

Shared this with some other craft devs and one question that came back was: What are possible performance implications with SSE (compared to something like Sprig with regular fetch/ajax calls)?

Couldn't find much info about it online.

[mandrasch]

When I read about Websockets vs SSE this was mentioned:

There is also a problem that impacts both technologies - long-running connections.

Both technologies need to maintain long-lived open connections to send a continuous stream of events.

Managing such connections, especially on a large scale, can be a challenge as we can quite quickly run out of resources. Additionally, they may require special configurations like extended timeout and are more exposed to any network connection problems.

https://softwaremill.com/sse-vs-websockets-comparing-real-time-communication-protocols/

Or does this not apply to datastar/Spark?

[croxton]

Helpful answer here on using SSE on Cloudflare and Nginx:

https://community.cloudflare.com/t/using-server-sent-events-sse-with-cloudflare-proxy/656279

[bencroker]

Spark renders the template, sends a response and closes the connection, just like a regular response in Craft. Please don't get too caught up on the SSE thing, it's just an implementation detail that Spark handles for you.

[mandrasch]

Ah okay, thanks very much for clarification 👍

In CraftQuest Livestream the progress bar example was shown https://data-star.dev/examples/progress_bar, therefore I was interested in this.

And I read that some webspace providers (especially shared hosting) do not allow listening for Websocket connections. So I was unsure about SSE. 🤷

This here might be a special case: https://www.digitalocean.com/community/questions/does-app-platform-support-sse-server-sent-events-application

A statement from a hosters like "SSE with no long running connections will be fine" would be re-assuring to dive deeper into this approach, at least from my personal perspective.

And do I understand it correctly that Spark uses SSE mainly because of lightweight protocol, not because of real time updates? Because real time updates are mentioned as primary advantage for SSE in every article. Guess that's what's confusing me.

Or is it just because datastar uses it and the main advantage of datastar is htmx + alpine in one bundled solution? 🤔

Update: Just saw you added " [needs more explanation]." in the original post, I'll wait for this section to be updated.

Much further success with it!

[bencroker]

Datastar uses SSE for back-end requests, hence SSE. I may explore taking advantage of SSE more in the future, but for now, the benefit is the ability to send multiple fragments, update store values, and use helper functions all in the same response.