[RFC Early Feedback] Require client directive for all framework components

[FredKSchott]

A couple of discussions & threads have recently connected in my brain, and I want to throw out an idea that may be a way to address all of them at once.

I know that this idea probably sounds spicy but give it some thought before responding:

Background

1. Users continue to have trouble when they use a framework component without a client directive and expect it to be interactive and clicking on the page, seeing nothing happen. This is a feature of Astro, not a bug, and a part of our "easy to do the right thing" mentality. But, it's still confusing when it happens to you, and feels like Astro is broken. The result is a poor user experience for new users and pro users alike.
2. @jonathantneal kicked off a discussion around the idea of nested framework components, and how much nesting was okay. In broad usage, it can make a lot of sense (ex: a hydrated button inside of a hydrated sidebar panel). But in more complex cases, it's unclear whether Astro will or won't break (ex: multiple connected components) because we make island usage so effortless/invisible in our syntax.
3. That spun off a separate convo on Discord voice chat where we discussed this idea: "as an Astro user, you seem to convert more of your site to Astro components over time, and progressively only use React/Svelte/Vue when you need client behavior". Our own sites that we've built are almost all Astro components, and every framework component exists because we need it hydrated on the page.
4. This set off a red flag for me: are we optimizing our default behavior for a new user who has lots of React/Svelte/Vue components, at the expense of our biggest users? And at the same, are we also harming the new user experience due to this confusing default behavior?"

Proposal

I want to throw this idea out for feedback:

1. Require a client:* directive on every framework component.
2. Give a friendly warning if one is not given, and default to client:idle.
3. Add a client:none directive to opt-in to current default behavior.

I think this addresses all of the issues above:

1. No more "why isn't this component working?" issues due to user error/misunderstanding of our current default behavior. By default, you would instead get hydrated behavior + a clear warning. I can't emphasis how huge this would be in improving the Astro onboarding experience.
2. More clear that Astro is creating an island when you add a client directive, which is currently unclear when you don't use client directives. This dissuade users from thinking that interconnected framework components would "just work" and makes the island idea more explicit to the user.
3. Supporting power users who don't need the default client:none behavior since most of their site is Astro.

Thoughts? Too wild? Not wild enough?
I would love to hear from some power users here on whether they use static, client:none framework components often.

[tony-sull]

I actually really like the idea of requiring a hydration directive and adding a client:none option!

My main hesitation is defaulting to a build warning + client:idle behavior. I've never really been a big fan of build warnings - like a yellow light, I see a build warning and blow right by it before the light turns red 😂

The story of Astro so far has really leaned into the no JS by default idea, and I'd hate to lose that. If we throw a build error and require a client directive I think we're still true to that idea, but if the default behavior is to assume client:only that could be a bit of an asterisk to the no JS pitch.

What if we added client:none now to a pre-v1 release and add a build warning for now as a deprecation notice? In v1 it will be required, for now we assume client:none with a friendly reminder to make that behavior explicit for all your framework components

[aFuzzyBear]

like a yellow light, I see a build warning and blow right by it before the light turns red

you and me both, 😅

[FredKSchott]

haha agreed! Maybe warning in dev, and error in build? The core idea here is that a user (especially a new user) wouldn't be penalized by not knowing about or forgetting a client directive but would still be pushed to add one. Totally open to other ideas like this that also achieve that goal!

[d-alleyne]

2. Give a friendly warning if one is not given, and default to client:idle.

Updating the VS Code extension to show warnings would definitely nudge developers in the right direction.

[aFuzzyBear]

I must say, I feel that if they user is using a ui framework then its a given that they are using that to augment their site with JS of whichever flavour. To default this would be somewhat breaking the 0kb shipped model. But that is somewhat subjective in its interpretation.
0Kb JS .... when using only Astro components and files,
Using UI frameworks, well they are just not going to work without the JS, so its a nice tradeoff. However Fred is right, the number of users misinterpreting the client: directives is significant.
Thinking about this bit,, I would say Tony has hit it on the head, if we can phase this behaviour in over the next couple of major releases and have the behaviour established prior to v1, this would be suitable strategy.
I would agree with all three points, including the Amber warnings in the build system. I feel that not all are racers, and alot of people do stop at the lights when they start changing, (infuriating as it is)

[FredKSchott]

thanks @aFuzzyBear! I would love to make as many of these core, "how does Astro syntax work" changes before v1.0 is cut. v0 is the best time to formalize core behaviors like this, before the mass majority of users have arrived!

But, I'm definitely in support of a phased rollout to help mitigate this, like you suggest. For example:

1. add client:none, don't change default behavior
2. later, add opt-in warning if no client directive exists (--strict mode?)
3. later, make warning opt-out
4. later, turn warning into an error on build

[okikio]

thanks @aFuzzyBear! I would love to make as many of these core, "how does Astro syntax work" changes before v1.0 is cut. v0 is the best time to formalize core behaviors like this, before the mass majority of users have arrived!

But, I'm definitely in support of a phased rollout to help mitigate this, like you suggest. For example:

1. add client:none, don't change default behavior
2. later, add opt-in warning if no client directive exists (--strict mode?)
3. later, make warning opt-out
4. later, turn warning into an error on build

@FredKSchott I prefer this

[aFuzzyBear]

Me too...
@FredKSchott I think on a more general note to have any other potential changes to deprecated features be bundled together and rolled out in groups, this would help mitigate any problems in userland to being only with those changes being fed through in a very gradual fashion

[jonathantneal]

Require a client:* directive on every framework component.

I would suggest the other way around. As a user, if I’m using a client-side framework, I’d prefer Astro respect my choice.

If specifying a directive is important enough to require, then let’s embrace import assertions, and at least let devs write it once.

---
import Date from '../components/Date.js' assert { client: 'idle' }
---

... in more complex cases, it's unclear whether Astro will or won't break (ex: multiple connected components) because we make island usage so effortless/invisible in our syntax.

I think only frameworks with limited support for islands benefit from this. React can fail managing independent, inter-connected components on a page, but it’s a purposeful design choice by React. Web Components support independent, inter-connected components on a page. When we can render Web Components on a page, we will not want to dupe client directives all over the page.

[tony-sull]

Oh that's an interesting idea, using import assertions to set the hydration method

I'm not too familiar with the working spec for assertions, but this jumped out to me as really just changing component defaults. Could Astro include a programmatic way of changing the default client: directive after the component is imported?

---
import Date from '../components/Date.js'

// one idea, an Astro global?
Astro.withClient(Date, 'idle')

// or as a prop added to the component?  Could be risky
Date.Astro.client = 'idle'
---
<!-- This would use client:idle by default -->
<Date />
<Date />
<!-- This would override idle only for this instance -->
<Date client:none />

There's a bunch of different ways the API could be designed, but the basic idea being let the dev set a default client: for the component per-import

[FredKSchott]

I'd love to treat a change to how client load directives work as different from this proposal. Mind spinning up a separate discussion around that idea?

[jonathantneal]

This proposal has now been made in #69

[matthewp]

This is definitely spicy. There's a flip-side to the problem that this seeks to solve.

Case A

1. New developers accidentally forget to add client: and don't see interactivity in dev.
2. Developers don't accidentally add JS when it's not needed.

If we implement this suggestion then we have the opposite problem.

Case B

1. New developers see interactivity in dev mode.
2. Users get JavaScript they don't need because developers forgot to disable it.

When we created Astro we decided that Case A was preferable. I'd hate to see us backtrack from that. We fixed a footgun, adding JS when it is not needed, and I think this reverses that.

[FredKSchott]

I'm just not sure I'm following how Case B is a risk here, logically. Could you illustrate it with a user story so that I can better understand why this is a concern? Something like:

1. A new user uses a component without a client directive
2. Astro returns a warning, telling them that they must use a client directive, and recommends client:none to silence the warning.
3. The user adds the client directive, and the warning goes away, and the user is happy.

[okikio]

Assuming there is a warning then sure that can be a solution, plus, we can add a config option to ignore the warning and to build with client first, however, should the warning block the building of the page, or should it allow the page to be build with ".........." default behavior, we are currently discussing what the default behavior should be, so, this is more of an implementation details, than a core detail of this RFC.

Adding mandatory client directive will annoy devs, and probably lead to devs not caring and applying client:load on all components, which fundamentally invalidates the point of Astro, IMO, Case B is the worst possible situation one can have for a islands architecture focused framework like Astro.

IMO, we can have warning but the default behavior should stay the same as what we currently have, namely Case A. We can encourage devs to use explicit client directives (via warnings), but we shouldn't force them.

[matthewp]

A warning is not a requirement. Developers regularly ignore warnings because they are used to be inundated with them.

[tony-sull]

Developers regularly ignore warnings

Busted! For better or worse, I stopped paying attention to dev build output a couple years ago when NPM got a little heavy handed with project funding messages

@FredKSchott When I first found Astro I very quickly jumped down the rabbit hole of rebuilding a SvelteKit site with Astro. At first that mainly meant copying over existing Svelte components and wiring everything back up for data loading and routing (I assume it'd be similar coming from something like NextJS or NuxtJS)

I had a couple Svelte components that needed client: for interactivity, but most of those Svelte components really were either layout components or the state never changed after SSR. I've since replaced all those with Astro components, but it really did feel like a huge win to reuse all the components I already built and see client JS drop by 80-90% 🚀

[okikio]

I agree with @tony-sull

[matthewp]

@FredKSchott

Do we though? By always requiring a directive, you couldn't forget to disable it, right? I'm also trying to avoid Case B and I believe that this proposal does that.

This is one thing I don't understand about this proposal as it also says:

Give a friendly warning if one is not given, and default to client:idle.

So a client directive is not required in this proposal, and the default is to include JavaScript unless specified not to.

[FredKSchott]

@aFuzzyBear called this out above, and we talked through a warning on dev that becomes an error on build being a possible middle-ground here, if that point is a concern. #67 (reply in thread)

I'd also like to call out that this proposal is going more strict, not less. That means that if this theory proves wrong (I'd be happy to be proven wrong!) we could easily back this out and revert to old behavior. Worth testing the theory to find out?

[tony-sull]

Crazier spicy take - could this be an interactive dev warning in the browser? During dev builds, Astro adds a default click handler for any framework component without a client: directive. Component doesn't work, they click it, and get a fancy on-screen message or alert with details and a link to the docs

[okikio]

Yeah, I was going to suggest this as well

[jasikpark]

I think a really powerful part of Astro for someone coming from Nextjs for example, is that they can take all of their components, copy them over to their Astro site, and get a no-js website that works out of the box with no client side directive additions

example: https://www.youtube.com/watch?v=LAVZyaFG73g where Chris Coyier (@chriscoyier) and Dave Rupert (@davatron5000) transition https://github.com/CSS-Tricks/serverless over to Astro via CSS-Tricks/serverless#182

If we remove client:none as the default for hydration, we lose that ease of use.

[AGS1130]

From above

Background

Users continue to have trouble when they use a framework component without a client directive and expect it to be interactive and clicking on the page, seeing nothing happen. This is a feature of Astro, not a bug, and a part of our "easy to do the right thing" mentality. But, it's still confusing when it happens to you, and feels like Astro is broken. The result is a poor user experience for new users and pro users alike.

Proposal

Give a friendly warning if one is not given, and default to client:idle.

Hey there 👋🏽
I haven't read through this entire thread, but just wanted to say that I spent almost an hour trying to debug a non-existent issue in a Svelte component only to find out that I did not load the component correctly 😫

I don't know the status of this, but it would be really helpful if you can include a warning that a JS Framework Component is not loading correctly because a client directive was not set. If this is a major lift, maybe you can create a ESLint plugin to optimize an Astro project, similar to Next.js and default to client:idle.

Great work on the framework, and thanks again!

[okikio]

I think a friendly warning is a good idea, but I'm against defaulting to client:idle it goes against the no js by default. What we could do is have a vite like warning, popup if you try to interact with a component without a client directive.

[matthewp]

How would we know when to warn?

[okikio]

If the user tries to interact with a component