Import Assertions for Components, Assets, and Client Directives

[jonathantneal]

Problem

It’s hard to predict what a user wants from an import. We tend to put our expectations into variable names or TypeScript extensions, because file extensions are not reliable.

import MyReactAccordion from '../components/Accordion.js'

// vs

import MyPreactAccordion from '../components/Accordion.js'

import imageData from './data.jpg'
console.log(imageData.height / imageData.width) // 0.75

// vs

import imageURL from './data.jpg'
console.log(imageURL) // URL { href: "file://path/to/src/pages/data.jpg" }

// vs

import imagePath from './data.jpg'
console.log(imagePath) // "/path/to/src/pages/data.jpg"

Proposal 1: Allow Import Assertions

Allow import assertions to not throw in JavaScript, anywhere JavaScript is currently processed (JavaScript, TypeScript, Astro). It would be processed as currently defined in the specification.

• When type is "json", process the file data as an Object from JSON.

---
// load page data from a json endpoint

import pageData from './page.json' assert { type: 'json' }
---

Proposal 2: Allow Type Assertions

Allow a type assertion on any ECMAScript import, which would determine how the loaded file is processed.

• When type is "use+astro", process the file data as an Astro Component.
• When type is "use+preact", process the file data as a Preact Component.
• When type is "use+react", process the file data as a React Component.
• When type is "use+svelte", process the file data as a Svelte Component.
• When type is "use+vue", process the file data as a Vue Component.
• When type is present and matches none of these, process the file as a JavaScript Module.

---
// load a react component from a JS file, hydrating on element visibility

import Accordion from '../components/Accordion.js' assert { type: 'use+react' }
---
<Accordion client:load />

Question: Should we allow custom types?

That seems fine to me? Especially if you use a character outside of alpha and dash, like you did here.
— Tab Atkins

Proposal 3: Allow Client Assertions

Allow a client assertion on any ECMAScript import, which would determine how the loaded file is processed.

• When type is "use+astro", "use+preact", "use+react", "use+svelte", or "use+vue"; then,
  • When client is load, process the component so that it begins client hydration when the page loads.
  • When client is idle, process the component so that it begins client hydration when the main thread is free.
  • When client is visible, process the component so that it begins client hydration when the element enters the viewport.
  • When client is only, process the component so that it loads and hydrates when the page loads.
• Within an Astro file, allow Component with a client directive to override a client assertion.

---
// load a react component from a JS file, hydrating on element visibility

import Accordion from '../components/Accordion.js' assert { type: 'use+react', client: 'visible' }
---
<!-- load the first one immediately -->
<Accordion client:load />

<!-- load the other with the provided assertion -->
<Accordion />

---
// load an astro component as plain text, for component documentation

import contentOfHeading from '../components/Heading.astro' assert { type: 'text' }
---
<pre>{contentOfHeading}</pre>

Examples without Import Assertions

Proposal 1

---
// load page data from a json endpoint

const pageData = await fetch(new URL('./page.json', import.meta.url)).then(response => response.json())
---

Proposal 2

---
// load a react component from a JS file, hydrating on element visibility

const Accordion = await fetch(new URL('../components/Accordion.js', import.meta.url)).then(
  response => __MAGICAL_REACT_TRANSFORM_EVAL_AS_ASTRO_COMPONENT(response.text())
)
---
<Accordion client:load />

Proposal 3

---
// load a react component from a JS file, hydrating on element visibility

const Accordion = await fetch(new URL('../components/Accordion.js', import.meta.url)).then(
  response => __MAGICAL_REACT_TRANSFORM_EVAL_AS_ASTRO_COMPONENT(response.text(), { client: 'visible' })
)
---
<!-- load the first one immediately -->
<Accordion client:load />

<!-- load the other with the provided assertion -->
<Accordion />

---
// load an astro component as plain text, for component documentation

const contentOfHeading = await fetch(new URL('../components/Heading.astro', import.meta.url)).then(
  response => response.text()
)
---
<pre>{contentOfHeading}</pre>

Prototype / Demo

• Example
• React Component Example

[aFuzzyBear]

I really do think that this set of proposals helps to solidify alot of the concerns that were raised in the #67.

Restating the concerns that were raised in rfc #67 ,

1. Users having trouble when using a UI component without a client directive, The initial expectations of the users are not met, but from AStro's pov the onst is on the developer to tell Astro that they wish for JS to be progressively hydrated on the client.
2. Nested Frameworks and how they would interact with each other, how messy can this approach get before someone breaks? is really at the heart of this
   3 & 4) Are raised in tandem, where the concern felt is that where users are reaching for UI frameworks is only to provide brief aspects of interactivity. Which sacrificial lamb are we favouring at the expense of the others.

Use cases 3 and 4 are unfortunate circumstances where the intended design of the system has not been met fully with the consumer intuition of using the system. Causing this fall in UI component usage in Astro, and or providing a slightly dislocated approach to leveraging the partial hydration features.

Here @jonathantneal has proposed a very eloquent set of solutions that has been floated somewhat in the past to warm reception but wasn't really been an implementation requirement, however the concerns that have been expressed does warrant a better review over the client:hydration application and the intended developer user experience.

Given the success of Island architecture and the fundamentals that Astro ships 0kb of JS, to pivot away to where Astro supports the use-case of UI frameworks are client:idle by default, would indeed break the 0kb philosophy, this I think can be adjusted to be better suited to reflect the reality where "Astro can ship 0kb of Js by default", Here you would find the allowance needed to provided that extra bit of DX.

Looking at the Proposals, I personally am In favour of proposal 3, which takes the previous 2 proposals and introduces the "client" directive into the assertion object. This I feel is the piece of the jigsaw that has been missing.

the following statement helps bring a peaceful, bloodless end to the use-cases 1 through to 4:

---
import Accordion from '../components/Accordion.js' assert { type: 'react-component', client: 'visible' }
---

This can be standardised, and set out clearly in terms of documentation and adoption of its behaviour made gradual up until release of v1 can see better adoption of users existing bag of components. Hydration methods would be better understood and applied more appropriately. Also there is the statistical analysis benefit that can come from having this type of metadata next to the import statement.

I would like to forward a motion for the proposals provided to merit time within the next possible RFC call to further discuss amongst other stakeholders,

[matthewp]

I like this. We talked a little about this offline but to summarize here:

• I can see the use-case of Proposal 2. This would allow us to know the renderer statically. This is currently a little bit of a problem with client:only, for example.
  • However, I can also see this being contentious as it requires the user to add an assertion to a lot of their imports that they don't need to do so today.
  • Could maybe the assertion only be required if you are using more than 1 renderer? Since a lot of users are using a single renderer this would maybe make the idea more palpable.
  • Because Proposal 2 is potentially contentious I would recommend spinning it off into a separate proposal.
• The assert { client: 'load' } idea is very interesting. This could potentially be used to solve problems we don't currently have a great solution for:
  • 3rd party widget embeds that are not components (like a Google Analytics embed, a YouTube embed, etc).
  • Web components that are client-only.
• assert { type: 'text' } is also interesting. I would probably separate that proposal from the client one, as you wouldn't want one of them to block the other.

[aFuzzyBear]

I genuinely thought import assertions was DOA, but this is bringing back new life into it.
I must say though, with the proposal for import reflections there can be a bit of scope between the client and file type of assertions, if import assertions are strictly to control mime type, Jonathans use of "use+astro" can then be astro | jsx | ts | .... and us the as keyword as proposed in the tc39 proposal this can head off any future moves by the working group when it comes to this as adoption, if it even does.

import Accordion from '../components/Accordion.js' assert { type: 'tsx'}  as { render:'react' client: 'visible' }

[jonathantneal]

The key difference is that we can have assert today, and we are far from as.

The key motivator is that assert could "solve problems we don't currently have a great solution for".

[aFuzzyBear]

Let do it, 🥳

[vincerubinetti]

Sorry if this is not the right place to ask this or if this muddies the waters...

But is it possible to define the client directive for a particular component once, in the entire codebase? I feel like which client directive I need is most closely tied to the behavior/implementation of the component itself, not where it is used. Like, if I have a component that has dynamic logic in it, it's always going to need client:load or similar. That's not going to change in different places where it's used.

Context: I'm considering switching a big site with a lot of static blog-like content over from Next to Astro. I want all the components auto-imported into every mdx file, which already seems possible with this package. I also don't like the idea of having to specify client:load over and over and over, because these components can be used dozens of times in each of hundreds of post files. I want authors to be able to just focus on the content itself.

Perhaps if you end up going with an import assertion solution, that can be combined with the auto-import package to achieve what I'm after? Am I right in my assessment that what I'm trying to do is also not possible right now with custom client directives?

If you don't end up doing this RFC, or it won't work with auto-imports... it's ugly but maybe you could support like // Astro default client:load at the top of component files to specify their intended default directive.

[matthewp]

@vincerubinetti You can create a wrapper component like so:

Counter.astro

---
import Counter from './Counter.tsx';
---

<Counter {...Astro.props} client:load />

And then use Counter.astro everywhere.

[vincerubinetti]

Yeah I had considered making a barrel file like that. But wouldn't that lose type safety unless I redefined the prop types in Counter.astro somehow? Also don't love the idea of having another file for every component.

[delucis]

You can reflect the prop types out usually:

---
import Counter, { type CounterProps } from './Counter.tsx';
type Props = CounterProps;
---

<Counter {...Astro.props} client:load />