Thoughts about Arrow after building and launching an app

[Chaphasilor]

Hey there!

I've recently built and launched Jellyfin Rewind, a web app that offers something like "Spotify Wrapped", but for people listening to music via Jellyfin.

I've built the app entirely using ArrowJS, only used Vite as a bundler for convenience and slightly better performance.
Overall it was a very pleasant experience and I don't regret my choice at all! I just wanted to leave my thoughts here...

(I switched from using I to using you at some point, please bear with me)

Getting Started / Learning Curve

ArrowJS was really easy to pick up for me. I have a few years of experience using JavaScript, am self-taught without any bootcamps or major tutorials, but would still describe myself as someone who knows some of the intricacies of JS. I'm a big fan of using template literals wherever possible, so I felt right at home using Arrow.
When it comes to reactivity, I'm coming from a Vue background, so the concepts are mostly the same, at least when it comes to Vue 3.

Integrating Arrow into my workflow

As others have already mentioned on Reddit, I'm not a huge fan of unnecessary abbreviations (I hate this about C(++) and Rust), so I went with the aliases instead. reactive, watch, and html, pretty self-explanatory and fast enough to type. I don't mind that there are abbreviated versions, but I would like to see the non-abbreviated functions used in the docs, for clarity.
As for using Arrow, my preferred way is using it to build single-page apps (SPAs), so I have one <div id="app"></div> that I bind to using a single html template. Inside that root template, I add any "static" components, like headers, footers, or overlays/pop-ups, as well as the dynamic content, using a reactive expression.
Depending on my implementation, I use either an array or an object to hold the dynamic content. Depending on if I only want to "mount" a single instance or all instances.

As for reactive/dynamic data, I prefer to define a global "state" variable at the top of the file that contains all the data I'll need.

const state = reactive({
  foo: `bar`,
})

This makes it easy to use and combine data, but also makes sure that anything within the state is generally reactive and will properly update the templates.
As for components, I try to move everything into a "component" (assign the html-expression to a variable) that is either a) used multiple times, or b) a major logical unit. Inside the components, I tend to just use expressions, functional JavaScript, and raw HTML; I don't try to break every expression down into a variable.
If I need to parametrize a component, I write a function that accepts an object that is destructured into the individual parameters, and prefix that function with build:

function buildMyComponent({ param1, param2, }) {
// component logic goes here
const calculatedValue = state.foobar[param1] + param2

// return the tagged template string
return html`
<span>Value is ${() => calculatedValue}</span>
`
}

You could even pass a html-template string as one of the parameters and use it in the component (e.g. for custom dialogs). Think slots in Vue.
Then I can easily use that function somewhere else:

const state = reactive({
  foobar: {
    foo: 1,
    bar: 2,
  },
  showValue: false,
})
html`
  <button @click="${() => state.showValue = true}">Reveal Value</button>
  ${() => state.showValue ? buildMyComponent({
      param1: `foo`,
      param2: 5,
    )} : null
  }
`

Using booleans to control conditional rendering is pretty standard for most JS frameworks and works well with Arrow too.
Conditional rendering itself is done using simple ternary operators in a reactive context: ${() => condition ? onTrue : null}. Of course, instead of null, you could also render an alternative. If you have multiple alternatives, you could expand the arrow function's body by using curly braces and use a simple if-statement along with one or multiple return statements, or assign the options to an object and select the right option using the state: ${() => state.options[state.selectedOption]}. Whatever work best for the use case; you don't need to be consistent. You're programming, not competing for style points.

watch is used whenever I need side-effects. Pretty boring, not much to see here. Keep in mind there are currently some issues when modifying the state from inside a watcher; things might not re-render correctly. Depending on what you're trying to do, working around this might not be fun.

Things to note

• Always be careful what is reactive (${() => expression}) and what isn't (${expression}). In my experience, most of the time you'll want things to be reactive when building an app. However, if you're using Arrow for something like a blog, static might be the way to go instead. When in doubt, it's probably better to trade performance for reliability and make everything reactive. Maybe a snippet could help?
• When "mounting" mapped data, try to always provide a unique key. I've encountered an issue where some of the mapped items wouldn't disappear when the source data changed, so instead of five items, it kept two of the previous items mounted and added the new five items below. This happened, when the two items appeared both in the old and new source data, and Arrow probably got confused.
  If you don't have a unique key, you can use a random one in order to force re-mounting of all items:

  html`
    ${() => state.data.map(x => x.y}
  `.key((Math.random() * 100000).toString(16)) // assign a random key to force re-rendering of the list (and thus the indices)

  If you have a unique key to assign, make sure that if you're using the index from the mapping function, you're always using it in a reactive context (${() => <some expression containing the ID>}). Otherwise, items might only move around if the key stays the same, but will keep their original index, which is not correct anymore.

Things I would like to see

• Event modifiers!
  We have the @event for easily handling all kinds of events, but no easy way to add modifiers for this. Especially when using nested components, this could cause trouble, e.g. when you have a clickable item with another clickable button on it. Clicking the button should probably not also trigger the item's click event, but clicking anywhere else should.
  My solution so far is using a helper function that first modifies the event and then passes the event along:

  function stopPropagation(f) {
    if (!f || typeof f !== `function`) {
      f = () => {}
    }
    return (e) => {
      e.stopPropagation()
      f(e)
    }
  }

  It's fairly straight-forward to use:

  html`<input type="text" @input="${stopPropagation((e) => {
    state.foo = e.target.value
  })}"
  >
  // or also just
  html`<a href="#" @click="${stopPropagation()}">Link</a>

  It would be nice to have such modifiers officially provided, maybe via @arrow-js/util? :P
• Lifecycle hooks
  While trying to workaround some of the watch bugs, I've had some instances where I would've loved to know once a html-tagged template got mounted/re-rendered or unmounted.
  This would also be super useful for implementing more advanced components. Doing something on mount is relatively easy using the "builder" pattern from above, but unmounting seems much harder to me.
  There have been some suggestions on Reddit about how this could be implemented: https://www.reddit.com/r/webdev/comments/10162jv/comment/j2ognqk/?context=3
• Maybe some sort of element references? Like Vue's refs, just a way to identify components in the same or parent scope.
  I know this does technically work by using IDs and/or document.querySelector(), but that is always a bit verbose. Maybe, similar to the @event handling we could get #ref, and the tagged template function exposes the ref object as a parameter to the provided expressions? Here's a mockup:

  html`
    <input #exampleRef type="text">
    <button @click="${(refs) => alert(refs.exampleRef.value)}">Get value</button>
  `

  Not only would this be easier to use, but probably also more robust, as it is quite easy to use the same ID twice in an SPA, and that could cause problems. And I'm guessing if it's possible to add event handlers to specific elements after rendering, it is also possible to add some other attribute to keep track of the refs. Maybe making refs a function would be easier to implement and stateless, not sure. I'm also not sure if this would be feasible for nested html-tagged templates...

Okay, I think that's enough for now. Really love the library, it's almost exactly how I want it to be. Use vanilla JavaScript (concepts) wherever possible, and add some useful utilities where there it too much friction/repetition.
I'd love to see more a bit more development, mostly the bug fixes. Once #36 has been fixed, I think a beta release would be in order :)

Docs could also use some more detailed explanations, and I'd be happy to help with that. I think SolidJS does a pretty good job of explaining the edge cases, although I don't really like the docs overall. Because of the similarity between Solid and Arrow, I'd imagine some of the edge-cases to also apply to Arrow, but the documentation is probably still missing for that.

Keep up the good work!

[justin-schroeder]

Incredible write up @Chaphasilor — Love the opinionated descriptions of how you chose to structure your code too. Really great stuff.

#36 is probably the most obvious bug out there right now. Another known issue lurking in the code that I haven't fixed is reactive data inside 2 other reactive datas would cause unexpected results:

const a = reactive({
   foo: 'bar'
})
const b = reactive({ a })
const c = reactive({ a })

// "a" can only have "parent" in Arrow right now.

Your suggestions:

• Event modifiers: yeah, would be nice. I want to be careful not to add too much "built in" weight, but a few basics would be good. I like your solution too.
• Lifecycle hooks: something very basic like "mounted" would be nice I think.
• Dom Refs: Yes — I agree we should do this, its very doable too since we have DOM instances available directly in arrow.
• Docs: I would love any assistance you're willing to give on improving it. No gate keeping here.

Thanks for taking the time to write this up. It’s very insightful. Honestly it would make a pretty good dev.to article as well if you tweak it just a bit to be a little more of the "how I did x".

[Chaphasilor]

Thanks!

Haven't stumbled over that bug yet, I try to use reactive only if I have to, and that's usually only once for the global state. But that definitely looks like a gotcha!

I agree about the built-in weight, the three helper functions are fine for core I think. Only thing I might also put into core would be refs and the lifecycle hooks, but everything else (like the event modifiers) should end up in @arrow-js/util imo (as long as it's properly tree-shakable, otherwise you could even break it out into individual packages).

Love that you're on board regarding the DOM refs!

Any area of the docs you want me to focus on?

[irskep]

I spent the day rewriting some vanilla JS to use Arrow and want to add some additional use cases and thoughts to this thread.

• Event modifiers: +1
• Lifecycle hooks and refs: I would really appreciate this in order to incorporate third party libraries like CodeMirror that require direct DOM access. It's doable to work without but feels bad. If you could make refs and "mounted" work, it would immediately go from "experimental" to "practical" in my mind, worth investing in (as a contributor).
• Docs: I could potentially help out on docs. The main things I found myself wanting were:
  1. Examples of nesting "components" and reuse. I'm still unsure if it's better to dynamically make html templates, or to make one template instance and reuse it across renders, for sub-components.
     • I can probably contribute something here once I figure out if I'm really doing the right thing.
  2. Examples of how to integrate raw-DOM stuff (e.g. CodeMirror)
  3. Roadmap (I don't get a sense that there's a roadmap per se, but maybe there should be?)
  4. Some discussion of internals; I'm a potential contributor but it's a little daunting :-)

Overall, I strongly prefer this general approach over raw DOM, or Backbone.js, with the constraint of "no fancy build systems." I got burned bad by some deprecations in a recent side project, so I'm very invested in the idea of a build-tool-agnostic frontend framework, without a special snowflake syntax, that I can just point esbuild at until the end of time.

You might be interested in Pinia as inspiration for state management.

I see your docs are written in plain JS + Arrow, which is cool, but might make it difficult to do a lot of writing. Would you be open to using a tool purpose-built for docs, like VuePress or Material for MkDocs?