RFC - Metadata & JSX Head Tags

[ryansolid]

Summary

In this RFC I'm looking for feedback on the potential of a core handling of head tags. Things like <title>, <metadata>, <link>, <script> and <style>. This proposal aims to be not only a useful feature for core but to make the development of 3rd party libraries easier when handling things like streaming SSR.

Background

Current Concerns

I admit this is an area (like CSS) where I haven't wanted to touch with a 10 foot pole because no one seems to agree and everyone seems to get really opinionated and passionate about this stuff. However, I haven't been happy with how Solid's useAssets primitive works for head tags for a couple of reasons.

1. It defers running until flush which while useful for systems that collect things it can have unexpected consequences.
2. It has no client side consideration. Solutions built on it still need to handle the equivalent client side logic.
3. It only works on first flush, which means to reach consistent state with the client we need to do work during hydration.

The 3rd point is especially annoying. If someone tries to add a head tag lower down in a Suspense boundary and we've already flushed it's when that boundary hydrates in the client that we finally see the update. But it is more than that. If you write code to "correct" on hydration then latency delays can cause work to be undone and redone. For example if you have code splitting the server might know that the final title is the one inside the lazy component not the one outside. But if there is a delay loading that lazy code when shell runs first it might revert the title momentarily before applying the correct title again.

So while one can take a position that all metadata should be resolved before flushing it also means always blocking which I don't think is a good place to be. That isn't always a reasonable request. You could have to wait on the longest to load piece of data before showing the user anything. You could argue that deduping is the problem but showing some less descriptive title before the fully formed one is probably still beneficial.

Research

I did research on the head solutions used in React 19, Svelte, Next, Nuxt 2, Nuxt 3(unhead), Remix, React Helmet (Async), to understand how these libraries work and realized that few of them supported streaming properly. Solid Meta's approach while less than ideal is still adequate in this field.

The biggest point of contention is the approach to deduping. While this is not conclusive I hope it gives you an idea of how these solutions perspectives are different.

Library	Scope	Dedupes Meta on "name"	Dedupes Title	Dedupes with Explicit Keys
React 19	everywhere	No	No	No
Svelte	everywhere	No	Yes	svelte:unique
Next	route section(grouped)	Yes (Shallow Merge of keys)	Yes	No
Nuxt2	everywhere	No	Yes	Yes
Nuxt 3(unhead)	everywhere	Yes	Yes	Yes
Remix	route section(grouped)	~*	Yes*	No
React Helmet	everywhere(grouped)	Yes	Yes	No

Remix does a replace + optional merge approach so in a sense the naive behavior is deduping it could be as easily merging given the data structure. Next also supports this with generateMetadata.

Analysis

Let's start with a summary of results from my perspective. Every library supports deduping title except React 19. Grouped solutions (mostly route section based) are more comfortable deduping metadata and don't need explicit keys to do so. This is likely because they use a layered approach. So uniqueness at the same level doesn't conflict and can be replaced at a lower level. React Helmet has this characteristic too which is why it doesn't use explicit keys. You can have multiple open graph meta tags with the same name on the same level even if it overrides with other head entries.

React 19 is really the anomaly of this bunch and probably requires further exploration to understand the intent. Every library has some means to dedupe what you would want to except it. One thing to consider is that all deduping strategies that aren't purely hierarchical are fundamentally flawed. This means that while Router based solutions can provide good guarentees others cannot at all. All it takes is something being rendered anywhere in the tree and it wins. Order mattering on rendering is the least predictable approach possible and when dealing with singletons very hard to track. Arguably even harder than saying there should only be one on the page and not following that perfectly.

That being said in the past decade I've rarely heard anyone complain about this feature for things like title, yet demand a solution when one doesn't exist for it. So while flawed it is basically universally accepted. Is that sufficient criteria here for inclusion?

Proposal

So there are a lot of ways to take this. But in order to play nicely with streaming the way we'd want it needs to be core. Userland short of intercept the streamed chunks has no good tools here. But assuming someone wants to be able to dedupe it means we need to have the means built in otherwise this won't all work.

So for this I suggest a 2 prong approach. One that appeals to the general developer and one that appeals to library authors. This approach is heavily inspired by React 19 and along with our current experience with Solid Meta.

useHead

We introduce a new core primitive into solid-js/web to handle head management of tags. It will take a single tag description and manage it in the head both for client and server.

useHead({
  tag: "meta",
  props: {
    name: "description"
    content: "My very cool website"
  },
})

This API optionally can be given a key which will be used to dedupe entries, last one wins. The key property can be a getter so it can be made reactive and change so it is possible to do some pretty complicated updates.

Mechanically this will register all tags in a list that can be updated and deduped as changes occur keeping the head in sync in the client. During SSR it will collect the same way and at first flush render these tags into the head (in order link/style, meta, others, script). Subsequent flushes will diff the flushed value against the new changes and stream updates to the client from the server. On hydration we will collect the tags but not render or update anything. Only subsequent client changes will update the DOM.

If streaming is cancelled (like someone navigates the page) we will bail out of future server updates.

useHead is intended to be used internally in things like Solid Meta etc or other libraries so they can come up with their own keys and stricter deduping logic and own custom interfaces for more control. This gives a lot of power and full access to streamable APIs without digging into internals.

JSX tags

Certain JSX tags will automatically be turned into useHead calls. This only works with native tags and not with <Dynamic> components and elements that don't have their defining attributes for inclusion inside a spread since the mechanism is based on compilation not runtime.

<title> - This tag will be added to the head and given a special key to ensure only one ends up in the document. The exception is if it is found under known SVG elements as <title> is a legitimate svg element or elements with itemprop attribute. Don't overuse this with siblings and keep it top level in your route sections preferably to avoid inconsistent behavior.

<meta> - This tag will be added to the head except for when it has itemprop attribute. No deduping.

<link> - This tag will be added to the head except for when it has itemprop attribute. Links with the same href will be deduped.

<style> - This tag will be added to the head when it has a href attribute and no itemprop attribute. Styles with the same href will be deduped.

<script> - This tag will be added to the head when it has a src attribute and async attribute. Scripts with the same src attribute will be deduped.

Possible Additions

1. precedence or equivalent.

Some means to prioritize other than document order. Usually render order is sufficient because of the hierarchical nature of things. But this could be worth exploring.

2. Triggering nearest Suspense Boundary in the client until stylesheets have loaded.

This seems like a powerful feature if used properly.

Impact

Other than the JSX transform aspect this has minimal impact as it doesn't impact existing code and is completely treeshakable behavior in the client. I've attempted to keep the implementation minimal and it looks to be even smaller than current Solid meta so I'm thinking ballpark of 500 bytes minified and gzipped in the client.

I'm proposing that this be turned on by default in the next minor with the ability to turn it off via compiler option as to allow codebases that need to be updated or can't support this feature to not be impacted. Since meta data is intrinsically part of your application I don't expect this to impact many 3rd party libraries.

---

As always appreciate feedback very much.

[DaniGuardiola]

If I understood correctly, this aligns with my proposal here regarding meta tags: solidjs/solid-meta#39

But, it would be built into solid, and libraries can customize the deduping behavior by using useHead internally in components like <Meta>. Is that right?

This seems like a great approach to me. For many people (including myself), the core behavior would be more than enough if we don't mind setting explicit keys. Then, Solid Meta & co. can get smart and do more "out of the box" and opinionated deduping. And it's also quite easy for devs to create their own heuristics by wrapping useHead themselves.

It's a great win because it abstracts the hard part (making deduping work in all contexts, client/server/etc) while providing enough freedom to users to implement advanced heuristics with a good enough default.

Nice work Ryan!

[DaniGuardiola]

One thing I'd like clarification on: would <meta key={something}> be supported and transformed into useHead({ tag: 'meta', key: something })?

I think it should, personally. Otherwise it feels like it's just one little step short of being useful for me. I don't want to pull in another library or abstraction just so I can pass a key.

[ryansolid]

No I wasn't intending to make the key part of the JSX API. I don't want to make too many assumptions configurability on the JSX side. If we so decide that it is worth it in the future then we can but I'm hesitant to introduce that and keep to it if isn't ultimately where we want to go here.

This suggested usage of JSX with exception to the <title> tag does keep us very aligned with React. If their patterns of just not deduping in general tend to be good I'd rather that be the default than any complicated system that encourages keys. I mean they could be right and in that you should only have one title on the page. But I think deduping is good here because of what happens when you don't. I'm willing to play out this experiment considering that we enable 3rd party libraries so well.

And in so I expect SolidMeta 0.30.x to just be a wrapper over this using useHead with specifically this purpose of exposing more power and adding a few more capabilities.

[DaniGuardiola]

Okay, that makes sense. As long as Solid Meta doesn't get too bloated, I'd be willing to use it to set keys for de-duplication.

I wonder if Solid Meta could ship with the only behavior of wrapping these tags BUT with support for key, basically a 1:1 between <Meta key={key} {...props}> and useHead({ tag: 'meta', key, props }). And then maybe in the provider, one could pass a function to a heuristics prop that compares two tags and its props + key and returns true to de-duplicate or false to leave alone. That way it'd be very modular, easy to set up and customize, and tree-shakable if you don't want the overhead. Solid Meta could also ship with one or more built-in heuristics for users.

I know I'm getting ahead of myself and that this is beyond the scope of this proposal, but it might be worth imagining what can be done on top of useHead. What do you think?

[rickhanlonii]

Wow, this is a great writeup and research into the different approaches.

Just to explain the React approach here, as design principle, we try to avoid forcing a common abstraction on users that has unresolved pitfalls like the ones you mention. That's why React supports deduping for link, script, and style tags in cases where there are no pitfalls, but not for title.

Instead, we encourage libraries and frameworks to choose their own tradeoffs, and users can choose different libraries with different tradeoffs. That's why the two React frameworks listed have support for deduping the title, but in different ways which suit them, and React doesn't force them into doing it one way with unresolved pitfalls.

That's a choice we make and live with, but for Solid or other libraries you may have different design principles that work better for your users. I don't think one way is better, it's just a different set of tradeoffs.

[manniL]

Do you think it’d be possible to use the mentioned https://github.com/unjs/unhead library as base for the use head composable or is there anything speaking against it?

[ryansolid]

Streaming is the challenge really and for Solid a non-starter. unjs/unhead#396

I'm not sure what unhead's intended streaming solution will be to be fair. What I'm proposing here I don't believe has been done in any framework or library. I imagine most solutions for streaming will look more like React 19's or what we do today with Solid Meta. But I think we can do more. Figuring it out at a framework level has been essential. There will probably be a day where these learnings can filter back and we can adopt unhead. But as usual we are plowing ahead in unexplored territory and in those cases I like having complete control of the solution and the ability to move fast.

[harlan-zw]

Just some thoughts while I'm here, good luck with it! Happy to chat about any of this with you if you'd like.

Streaming

Streaming will be solved in Unhead, realistically it's a couple of months away. Although someone did (?) make a workaround here unjs/unhead#27 (comment)

I have a feeling there will be a lot of surprise complexity involved in getting it right and for many of the tags it may not make sense if they're streamed in late which becomes a dx issue. (i.e which meta description will google honour if a streaming in replacement is done, preloading, etc).

Tackling a smaller scope in this RFC seems like a good way to explore the issue though versus trying to get Unhead stable with it.

useHead API

Unhead inherited its API from Vue Meta which was used for Vue 2. You may want to consider a similar API though for future compatibility possibilities. However, your implementation makes more semantic sense and has cleaner boundaries

// Vue / Nuxt usage
useHead({
  meta: [
    {
      name: "description",
      content: "My very cool website"
    },
  }
})

I do like the lack of boilerplate in the above, Unhead may consider switching to a stricter structure without arbitrary boundary cutting.

// Vue / Nuxt usage
useHead({
  meta: [
    {
      name: "description",
      content: "My very cool website",
      tagPriority: 100  // ! Bad boundaries :(
    },
  }
})

Deduping

The deduping you described doesn't cover all use cases, consider <link rel, <meta char, <meta name="viewport" <base, <meta http-equiv, the below:

<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />

Unhead honours some duplicate tags within the same useHead call to work around this. This also allows things like multiple og:image's to be replaced.

// duplicates allowed within context
useHead({
  meta: [
    { property: 'og:image', content: 'https://example.com/image1.jpg' }
    { property: 'og:image', content: 'https://example.com/image2.jpg' }
  ]
})

// new call will de-duplicate image1 and image2
useHead({
  meta: [
    { property: 'og:image', content: 'https://example.com/image3.jpg' }
  ]
})

Also how to remove the child tag can be a bit of an issue.

Other Considerations

• Ordering of tags is important not only for the page to work (<meta charset) but for performance <link rel="preload"
• Handling element events, i.e <script onload
• XSS protection, i.e do you allow end users to dangerously set innerHTML
• htmlAttr / bodyAttr not sure if this is solved elsewhere
• useSeoMeta is quite popular, it does provide a safer API for setting the meta tags - probably overkill for this RFC

[DaniGuardiola]

The key approach should cover these by just setting different keys. Sure, it's a manual thing if you use it directly, but libraries on top of the utility can take care of these heuristics.

[ryansolid]

Yeah. It sounds like I miscategorized unhead. It should be grouped like React Helmet. Which follows why automatic meta deduping can happen there a lot easier.

I did identify that grouped same keys was a different behavior that is not so easily emulated with one off key approach. Because while you could easily solve overrides with keys it isn't actually easy to have one descendant override multiple parents. From that perspective it probably makes sense to support some sort of multi-tag interface.

That being said what brought this to my attention was the React approach of per JSX tag which is really attractive. It takes something that is native looking that you'd otherwise have no use for and makes it have purpose. The problem there is with that you can't do grouped deduping by the nature of the interface. You'd need a container element. I considered briefly doing this at a per template chunk level but I don't think it would be obvious to developers. Which means if you want to do any sort of overrides per element a key is all that is available.

It is possible that grouped is the only thing that makes sense ultimately but it does have the downside from the JSX perspective of introducing a new non-existent element/Component which is less than ideal.

[katywings]

This is looking very promising 🥰! One question about useHead: will it handle unmounting on the server? That would be important for things such as Suspense and Show fallbacks. Currently the head tags from temporary fallbacks don't get unmounted during ssr, resulting in wrong styles.

[ryansolid]

Yes this will handle unmounting on the server. In addition it will communicate that unmounting to client during streaming. My intent is to only flush head with Suspense boundaries so we don't get too many intermediate states. But we will need to test this pretty thoroughly.