Isomorphic (Reflected) Import Attributes Support

[thescientist13]

Overview

Coming out of #923 (and the PR for it at #1215 ), there were a few lingering items that would be nice to resolve by the 2.0 version if possible, around the experience and expectations as it relates to using Import Attributes in Greenwood.

Use Case

Take for example this standard use case:

import sheet from '../styles/theme.css' with { type: 'css' };
import data from '../data.json' with { type: 'json' };

When used in a browser, the type value does not carry over to the server. The closest thing we can get from the client side is the Sec-Fetch-Dest header which, while it can provide some contextual clues around if the request is coming from a module or not (e.g. empty), as far as I can tell there is no way currently for us to get any of the attributes used as part of a Request, which is a challenge primarily for resource plugins understanding if they should transform responses or not.

For example, if I have a CSS file

# theme.css
* {
  color: red;
}

Browser

In the browser I don't want any processing because for those browser it will get turned into a Constructable Stylesheet (CSSStylesheet) automatically.

This is nice, because from Greenwood's perspective, we also don't have to worry about distinguishing from normal CSS files either, e.g.

<link rel="stylesheet" href="main.css"></link>

Server / SSR (NodeJS)

On the server, for CSS for example, this needs be instrumented manually since Node will not do this automatically as it does not support CSS modules, e.g.

const sheet = new CSSStyleSheet();sheet.replaceSync(`* { color: red;}`);

Although we're not using it now, NodeJS does provide use access to all the attributes via a context object when resolving within a custom loader script.

export async function resolve(specifier, context, defaultResolve) {
  const { parentURL } = context;
  const type = context?.importAttributes?.type;
  ...
}

Current Behavior

For this reason, the best that Greenwood can do is a couple things

(Un)Bundling / Native Formats

As it stands now, although the Rollup version we're on (3.x) seemingly already supports attributes syntax without needing a custom acorn plugin (it already supports assertions), and so for now we basically just do the same thing NodeJS does, which is we explicitly pass an Accept: text/javascript header to all resource plugins as a hint to this special use case.

the only issue we have is just what to do with say a CSS Module

# before
* {
  color: red;
}

// after
const sheet = new CSSStyleSheet();sheet.replaceSync(`* { color: red;}`);

But going forward, should we still inline it? Or say if we allowed Greenwood to be deployed unbundled, ship it as something like an asset like we do with import.meta.url + new URL and just let the browser do all the work:

import sheet from './theme.234ss258.css' with { type: 'css' };

Extension Inference (?type= Opt-Out query param)

For this reason, the best that Greenwood can do is to infer the type value based on the extension which while not ideal, is at least a start. From there, if the URL / request does contain a type query param, then Greenwood will ignore it and defer it to any plugins instead like the raw plugin, e.g.
https://github.com/ProjectEvergreen/greenwood/blob/master/packages/cli/src/plugins/resource/plugin-standard-css.js

async shouldIntercept(url, request) {
  const { pathname, searchParams } = url;
  const type = pathname.split('.').pop();
  const dest = request.headers.get('Sec-Fetch-Dest');

  return url.protocol === 'file:' && type === this.extensions[0] && dest === 'empty' && searchParams.has('type') !== true';
}

And so the new raw plugin would support the "legacy" behavior of getting any arbitrary file contents (e.g. CSS) back as a string

import css from './some.css?type=raw';

It also begs the question of a query param is the right option or even needed if we infer automatically? Maybe it could be a case-by-case basis per plugin, but not sure how you would do it any other way from the browser, e.g.

<script type="module" src="./components/card.ts?type=ts">

<!-- or -->

<script type="module">
  import "./components/card.ts?type=ts";
</script>

Where would the header go?

---

For custom extensions like .gql or .ts this isn't as much of an issue, but when overlapping on standard web formats like CSS, JSON, and eventually HTML, having a clear line in all contexts; browser, server, and bundler, would be a big benefit.

Outcomes / Goals

Basically, we need to figure out how to get / express import attributes via a browser request, or best way to infer and provide to a resource plugin so we can handle it best across runtimes / platforms

• Browser - Bundle it as unbundled
• Server - Bundle it with a shim

From there we can

1. Best design how resource plugins can expect an import attribute
2. Confirm support for import attributes in Rollup >= 4.x (where custom acorn plugins were deprecated)
   • Import Attributes support in Acorn #1218
3. Obtain them from Rollup during loading of bundles and pass them to resource plugins
4. Allow Rollup to "pass through" import attribute based modules if user chooses unbundled
5. Obtain attributes during NodeJS custom loaders and pass them to resource plugins
6. Update any and all plugins along this convention
7. What to do about custom extensions in a <script> tag though?

   <script src="/components/footer.jsx"></script>

[thescientist13]

One thing that should be taken into account here is that for extending this to non-standard types, like say our own for raw or jsx, e.g.

import styles from './some.css' with { type: 'raw' };

this could / would fail in certain host environments, like a browser. this seems to be corroborated when using Web Test Runner with a browser, as I'll see errors when attempting to use that syntax both in the terminal, and of course when debugging through the browser

So perhaps ?type=xxx will always have to be a fallback of sorts for anything not supported directly by standards? 🤔

Some links to ongoing discussions around this in the standards space to keep up with

• Semantics of unrecognized types tc39/proposal-import-attributes#27
• Use cases for module attributes besides module type tc39/proposal-import-attributes#8
• Import assertions with loaders nodejs/loaders#39
• Import assertions integration whatwg/html#5883

In # 8, the topic of sending these attributes to the server also came up, which would be extremely valuable for our use case. 🥺

---

Not sure if we can get around this for local dev using es-module-shims and then re-write somehow for Rollup?
https://github.com/guybedford/es-module-shims#polyfill-hook

[thescientist13]

Interestingly in this PR, I noticed that in this PR where I had multiple sheets being used some actually didn't inline bundle?
https://deploy-preview-98--practical-fermat-fa2c48.netlify.app/

Taking this component for an example

// source code
/* eslint-disable max-depth */
import { html, LitElement, TemplateResult } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { unsafeHTML } from 'lit/directives/unsafe-html.js';
import { getEvents } from '../../services/events/events-service.ts';
import eventsCalendarSheet from './events-calendar.css' with { type: 'css' };
import themeSheet from '../../theme.css' with { type: 'css' };

@customElement('app-events-calendar')
export class EventsCalendarComponent extends LitElement {
  static styles = [themeSheet, eventsCalendarSheet];

  // ...
}

https://deploy-preview-98--practical-fermat-fa2c48.netlify.app/events-calendar.2a50650b.js

// output
import {t as e, s as t, x as a} from "./custom-element.89d57e7e.js";
import {n} from "./property.837b91b0.js";
import {o as r} from "./index.ec45f5c4.js";
import {a as s} from "./events-service.23790085.js";
import {s as i} from "./theme.1cbc327b.js";
const o = new CSSStyleSheet;
o.replaceSync(":host .as-events-calendar__header ...");

// ...

  )(),
  _.styles = [i, o],  // i sheet is untouched!
  c(_, A)
}
)();

So there is an example where something isn't being lined using replaceSync 🤔

[thescientist13]

Was actually able to make some good progress on this in #1259 through a combination of a couple things:

1. Treating (self identified) files like CSS and JSON as external to the bundler
2. At the bundle generation phase, find those import attribute references and emit them to the bundler
3. Then link the emitted bundle references back to the original import attribute references

In place of getting import attributes from the bundler, we know for sure which of these assets are bound for the browser, so we can differentiate one set of bundling as needed externalized assets for CSS / JS, where-as for SSR, we can simply shim it for the sake of interop.

So I think with this and eventually #1218, I think we should have a decent enough solution here, that we can probably close this out.

---

One random thought that came up was what if we could incorporate Greenwood's inlining optimization using this API? 🤔

import theme from '../styles/theme.css' with { type: 'css', optimization: 'inline' };

[thescientist13]

Just a heads up for #1275