☂️ New visual component for compatibility information

[alexanderniebuhr]

Description:

In our continuous effort to uphold high-quality standards and promote best practices within the Astrolicious organization and Astro Tips, it has become evident that there's a need to make our content more informative and user-friendly regarding compatibility and recommended usage. This encompasses clear guidance on what is advised for Static Site Generators (SSG) versus Server-Side Rendering (SSR), Node runtimes versus other serverless runtimes, etc.

Suggested Implementation:

To address this, I propose the introduction of a visual element in our content that distinctly classifies and communicates these recommendations and compatibilities to our users. Drawing inspiration from resources like caniuse.com, MDN Baseline and the MDN Browser Compatibility, we can create a detailed and user-friendly visual component.

The envisioned component should cover:

• Runtime/Adapter Compatibility
• Output Modes
• Version Specificity

This component could be represented in a table format, with entries for runtime (or adapter), output mode, and version. Additionally, we should incorporate a three-state system (potentially through colors or icons) to indicate compatibility levels:

• Doesn't work
• Works
• Best-practice/Recommended

For nuances or specific considerations (e.g., server mode only works for pre-rendered pages), these can be denoted with footnotes, hover texts, or asterisks for detailed explanation.

Component Integration:

To facilitate easy integration into our content workflow, this component should be developed as a reusable component. This component can then be imported into MDX files and positioned appropriately, leveraging props to display the relevant data.

Conclusion:

This enhancement to our content standards not only aligns with our commitment to quality but also significantly improves the user experience by providing clear, actionable information regarding the compatibility and optimal use cases of our content.

[sarah11918]

I will just add for some extra context, because it's something we're currently needing to deal with in Astro Docs:

Just knowing the output: mode isn't always enough to distinguish betweet SSG/SSR features. In hybrid and server mode, it's also possible the individual page itself is prerendered, and is the reason that a feature isn't available on that route/endpoint in particular.

So, I'd encourage you to keep that in mind when building a helpful visual indicator! We had someone recently file an issue because an older warning/error message suggested "adding output: 'server' to make this work" when they already were in server mode. They were just trying to do something on a page that contained export const prerender = true!

[florian-lefebvre]

So maybe instead of output we could say prerendered? Then this should work no matter the output. We can even link to the official docs so that people know what the default behavior is depending on the mode

[alexanderniebuhr]

I think that should work. tbh I think we should have a two "part" component. I really like the idea to have something simple at the top (MDN Baseline) which shows general compatibility with runtimes/adapters, and then something at the bottom which shows more details which is in a table format (caniuse.com, MDN Browser Compatibility)

[florian-lefebvre]

Interesting. Do you think we can have a usecase for several compatibility tables on a same page? If not it should be done in the frontmatter directly, otherwise we'll have duplicated data

[alexanderniebuhr]

I don't think we would have a usecase for multiple tables, but I see one for having two kinds of compatibility info. At the top something like this (screenshot). But instead of browsers, we'll have icons/logos of node, cloudflare, vercel, netlify (adaper) or node, v8, winterjs (runtime).

While the second info would be the classical compatibility table

[alexanderniebuhr]

Agreeing on the fact that it should use the same underlaying compatibility data source.

[alexanderniebuhr]

@dreyfus92 is experimenting with this already 🚀

[dreyfus92]

Just to keep this up to date with what we've been talking on discord, this is what we have so far:

[adaliszk]

Looks pretty cool, not sure when there is a use-case for it, but I like how everyone starts to think about this. Here is how JSR does it: