Remove support for define:vars on <script> elements

[delucis]

Body

Summary

Currently, Astro supports a define:vars directive on <style> and <script> elements. I propose to drop support for define:vars on scripts. Support with styles would be unchanged.

Related

• define:args #705
• Support `define:vars` and `hoisted` imports #295
• Improved inline script support #995

Background & Motivation

define:vars was introduced as a way to help pass data from the server to the client. For example:

---
const message = "Astro is awesome!";
---
<script define:vars={{ message }}>
  alert(message);
</script>

However, it has many gotchas that confuse users and is arguably an anti-pattern with better options available (and documented by us).

• define:vars forces a script to be inline and not bundled, which surprises users given this is a first-class feature, and pushes them to use a less performant technique.
  • This means the same script is included repeatedly for each component usage, which is not clear from the API and surprises people. It’s also less performant than other approaches.
  • It also means users are forced away from import, TypeScript usage etc. because inline scripts are rendered as-is without processing.
• define:vars is one reason we can’t improve the experience of using is:inline: we can’t work on optimizing inline scripts, providing CSP support, etc. when define:vars can make scripts only knowable at render time (see e.g. Improved inline script support #995)

By removing define:vars we could stop confusing users and focus on our other techniques we document like our “Pass frontmatter variables to scripts” docs.

Goals

• Simplify our script story and unblock wider improvements to Astro’s script handling.
• Deprecate and then remove define:vars support on scripts.

Non goals

• A new ergonomic API for passing data to scripts. This would be something good to think about (see e.g. define:args #705) but is out of scope for this proposal.

Example

One migration path for users is to switch to the custom element approach we recommend in docs. In this case this has the added benefit of switching to a bundled script.

---
const message = "Astro is awesome!";
---
- <script define:vars={{ message }}>
-   alert(message);
- </script>
+ <my-component data-message={message}></my-component>
+ <script>
+ customElements.define('my-component', class Component extends HTMLElement {
+   connectedCallback() {
+     alert(this.dataset.message);
+   }
+ });
+ </script>

In this minimal example the additional boilerplate does stand out so is worth discussing. However, it is not a goal of this proposal to invent a replacement, and in real-world usage the boilerplate difference is minimal.

For users who want to keep the inline behaviour for some reason they can still do so and avoid the boilerplate:

---
const message = "Astro is awesome!";
---
<script is:raw data-message={message}>
  alert(document.currentScript?.dataset.message);
</script>

^ For me, this is a good example of why our custom API may be superfluous. Our feature isn’t really adding something you can’t already do, but it promotes it even though it’s not the best approach.

Impact

There are almost twelve thousand example usages of <script define:vars={ on GitHub at time of writing, so no doubt this is a breaking change with significant impact, but a deprecation period of one major followed by removal in the next major could realistically mean this would be a two-year process, which is a long time for people to adjust.

[jdtjenkins]

I like the idea of getting rid of define:vars for scripts, it's never really seemed that useful for me given it's downsides. But I do wonder why the docs immediately push for Custom Elements? Is there a reason we want users to use custom elements for this? It just seems overkill to define one just to pass a variable to the client side.

This could be just as easily achieved with just setting a data attribute on a div or any other element. Or even on the script itself and use document.currentScript, but then I'm not sure if it'll get inlined by Astro 🤔 But either way, I don't see any benefits to a custom element over:

---
const data = {title: "My Page Title"}
---

<div id="my-data" data-data={JSON.stringify(data)}></div>

<script>
const dataElement = document.getElementById("my-data")

const data = JSON.parse(dataElement.dataset.data)
</script>

[delucis]

The main reason is just because it encapsulates the component logic given components can be used repeatedly (your example would work for the first component usage but not later ones).

But yeah, with a little tweaking you don’t need a custom element:

---
const data = {title: "My Page Title"}
---

<div data-data={JSON.stringify(data)}></div>

<script>
document.querySelectorAll("[data-data]").forEach((element) => {
  const data = JSON.parse(element.dataset.data)
});
</script>

[Adammatthiesen]

The main reason is just because it encapsulates the component logic given components can be used repeatedly (your example would work for the first component usage but not later ones).

But yeah, with a little tweaking you don’t need a custom element:

---
const data = {title: "My Page Title"}
---

<div data-data={JSON.stringify(data)}></div>

<script>
document.querySelectorAll("[data-data]").forEach((element) => {
  const data = JSON.parse(element.dataset.data)
});
</script>

Depending on how complex the script gets... this would need to get way more explicit... 😅 potentially quickly becoming painful to maintain... @jdtjenkins Custom Elements on the other hand allow you to act as if your only interacting with the current component instead of all of them at once from a script that may get injected multiple times (plenty of examples in StudioCMS)

[jdtjenkins]

Yeah no and that makes sense. At the moment you'd have to have some kind of workaround to select the specific element if you have multiple components.

It just feels like quite a leap to immediately go to custom elements from nothing, especially if it's only trivial data you need exposing on the client. So if the docs included maybe a version without using custom elements would be less daunting for users making the switch. But then again maybe people would actually really like them if they tried them and not want a different solution 🤷 who knows!

But yeah I think there's currently enough workarounds without using define:vars that I'm happy to see it go anyways.

---

Just leaving this here because it's currently in my head, I know this is out of scope for this issue so don't expect anything about it here. But want to have it to come back to if/when a new solution is ever discussed 😅

I would probably like Astro's focus in this case should be some kind of magic which encapsulates client-side scripts and their respective markup.

Like a helper to get the specific element that is being created, something like.

---
---

<div class="foo"></div>

<script>
const myDivElement = AstroHelper(".foo") // [{...}] - now myDivElement will only contain elements that match within THIS specific component
</script>

[ascorbic]

I don't think this should be removed without an ergonomic replacement. The dataset workaround is pretty awkward for cases other than custom elements. A new vars API that fixed the drawbacks of define:vars would give an easy migration path.

[delucis]

Even the last example?

<script is:raw data-message={message}>
  alert(document.currentScript.dataset.message);
</script>

vs

<script define:vars={{ message }}>
  alert(message);
</script>

It’s obviously slightly more verbose, but it’s much more explicit about what’s happening and avoids us elevating the inline script approach to seem like a pattern we recommend.