[RFC] Proper Import Attributes support

[yyx990803]

Context: Import Attributes is now stage 4: https://github.com/tc39/proposal-import-attributes

Related PR / issues:

• feat(imports): support for import attributes in Vite #17485
• Supporting multiple modules corresponding to the same id but with a different import attributes rollup/rollup#5694

---

There are few different aspects regarding properly import attributes support in Vite:

1. Import Attributes are currently not passed to plugins during development (when the plugins are run by Vite's PluginContainer)
2. Rollup currently only passes import attributes to resolveId
3. Rollup currently does not allow the same module to be imported multiple times with different import attributes
4. We need to align the behavior between Vite dev server, Rollup and Rolldown to ensure consistent behavior down the road.
5. There are some internal Vite features, specifically the magic-query-string based ones, that can migrate to be using import attributes instead.

Rollup Behavior Alignment

Currently in Rollup, support for import attributes is somewhat lacking. Only the resolveId hook receives parsed attributes via the 3rd options argument:

const plugin = {
  // ...
  resolveId(source, importer, options) {
    console.log(options.attributes)
  }
}

load and transform do not have access to this information via arguments.

In Vite we already augment resolveId, load, and transform hooks with an extra options argument to pass the SSR flag (relevant docs):

const plugin = {
  // ...
  transform(code, id, options) {
    if (options?.ssr) {
      // perform ssr-specific transform...
    }
  }
}

In Rolldown, we should provide the attributes property via options in resolveId, load, and transform so we can do:

const plugin = {
  // ...
  transform(code, id, options) {
    if (options.attributes?.type === 'xxx') {
      //
    }
  }
}

This information should also be made available to equivalent hooks in the Rust plugin API.

Note: Rollup has the intention to align the behavior here, see rollup/rollup#5694

ID uniqueness

Should we include serialized attributes as part of the module ID? Internally this is definitely a yes as this is required to ensure unique id -> module mapping, the question is more about the public module IDs provided to plugin hooks:

import './foo.js' with { x: 1 }

const plugin = {
  // ...
  transform(code, id, options) {
    // should `id` here include `{ x: 1 }` somehow?
  }
}

There are multiple issues if we include serialized attributes in ids provided to hooks:

• It can break resolveId for bare specifiers
• If prepended, it can break checks for absolute / relative paths.
• If appended, it can break file extension checks.

The potential breakage seems to be too costly.

The downside of not including attributes in ids is this makes ids no longer unique. A practical case where this can cause issues is plugins that use ids as keys for custom caching behavior. However, this should be rare in practice and the impact surface is much smaller than including attributes.

Proposed actions:

1. Don't include attributes in ids passed to hooks - keep them working like before.
2. For resolveId, add the following attributes to the options object:
   • importerAttributes: JsonValue
   • fullId: string
   • fullImporterId: string
3. For load, add a 2nd options argument in the shape of { attributes: JsonValue, fullId: string }
4. For transform, add the following to the 3rd options argument: { attributes: JsonValue, fullId: string }

With this, the only possible breakage would be users using id as custom cache keys. The migration is also relatively simple: use options.fullId as the key instead. The serialization format of attributes in fullId is now also free from constraints as long as they are guaranteed to be unique.

The naming of fullId is open to suggestions.

Migrating Vite magic queries to import attributes

In Vite, many built-in features and plugins rely on query strings in module IDs for this type of metadata, for example:

• ?raw
• ?url
• ?inline (for CSS & Workers)
• ?worker / ?sharedworker (for Workers)
• ?init (for WebAssembly)

With import attributes being standardized, I think we should eventually deprecate query string usage and move towards import attributes.

Examples

Raw Text

Before

import txt from './foo.txt?raw'

After

import txt from './foo.txt' with { type: 'raw' }

Asset URL

Before

import assetAsURL from './asset.js?url'

After

import assetAsURL from './asset.js' with { type: 'url' }

Side note: maybe this should be deprecated in favor of

const assetAsURL = new URL('./asset.js', import.meta.url)

Inline CSS

Before

import cssText from './foo.css?inline'

After

import cssText from './foo.css' with { type: 'inline-css' }

Open question: should we also require import attributes for CSS modules?

Worker Import

Before

import MyWorker from './worker?worker'
import MyWorker from './worker?worker&inline'

After

import MyWorker from './worker' with { type: 'worker' }
import MyWorker from './worker' with { type: 'inline-worker' }

@vitejs/plugin-vue block imports

Before

import _sfc_main from './Foo.vue?vue&type=script&lang=ts'

After

import _sfc_main from './Foo.vue' with { type: 'vue-script', lang: 'ts' }

type namespace

In the above examples, we are using type with values that map to the current built-in features of Vite. According to the spec:

This proposal does not specify behavior for any particular attribute key or value. The JSON modules proposal will specify that type: "json" must be interpreted as a JSON module, and will specify common semantics for doing so. It is expected the type attribute will be leveraged to support additional module types in future TC39 proposals as well as by hosts. HTML and CSS modules are under consideration, and these may use similar explicit type syntax when imported.

Attributes in addition than type may also be introduced for purposes not yet foreseen.

So in theory, it is possible for future platform specs to make use of the type field - e.g. native CSS Modules. It is also possible for different JavaScript runtimes / environments to provide different handling of import attributes.

We have a few options here:

1. Use a different key from type. E.g. as
2. Prefix the key or the value. E.g. with { 'vite-type': 'inline-css' } or with { type: 'vite-inline-css' }.

Option (2) has the benefit of being more explicit about these being Vite features, but is much more verbose.

[ghost]

Great discussion. What I have to say is probably already part of your current plan, but it's worth adding that it would be good to prioritize accepting the standard with { type: 'css' } first, before moving on to the migration and deprecation of magic queries which is also relevant. At the moment, only with { type: 'json' } is recognized by Vite (for reasons we understand). #17700

[yyx990803]

Good point, and that should be easy to do once we have proper attributes support in transform hooks.

[thebanjomatic]

Another factor to consider in regard to deprecating the magic queries in favor of import attributes is that typescript does not appear to support ambient module declarations based on import attributes at this time:
microsoft/TypeScript#46135 (comment)

That means the following types which are currently used can't currently be expressed if they were migrated to import attributes:

vite/packages/vite/client.d.ts

Lines 189 to 258 in cf813cc

	declare module '*.wasm?init' {
	const initWasm: (
	options?: WebAssembly.Imports,
	) => Promise<WebAssembly.Instance>
	export default initWasm
	}
	// web worker
	declare module '*?worker' {
	const workerConstructor: {
	new (options?: { name?: string }): Worker
	}
	export default workerConstructor
	}
	declare module '*?worker&inline' {
	const workerConstructor: {
	new (options?: { name?: string }): Worker
	}
	export default workerConstructor
	}
	declare module '*?worker&url' {
	const src: string
	export default src
	}
	declare module '*?sharedworker' {
	const sharedWorkerConstructor: {
	new (options?: { name?: string }): SharedWorker
	}
	export default sharedWorkerConstructor
	}
	declare module '*?sharedworker&inline' {
	const sharedWorkerConstructor: {
	new (options?: { name?: string }): SharedWorker
	}
	export default sharedWorkerConstructor
	}
	declare module '*?sharedworker&url' {
	const src: string
	export default src
	}
	declare module '*?raw' {
	const src: string
	export default src
	}
	declare module '*?url' {
	const src: string
	export default src
	}
	declare module '*?inline' {
	const src: string
	export default src
	}
	declare module '*?no-inline' {
	const src: string
	export default src
	}
	declare module '*?url&inline' {
	const src: string
	export default src
	}

[redfox-mx]

TBH, vite treat with { type: 'json' } as *.json since vite remove all import attributes inside the pluginAnalysis.

[MrMarble]

At the moment, only with { type: 'json' } is recognized by Vite (for reasons we understand).

TBH, vite treat with { type: 'json' } as *.json since vite remove all import attributes inside the pluginAnalysis.

Maybe I'm missing something, but I'm trying to use the import attributes to import and externally injected JSON via <script type="module"/> and vite is removing the with { type: 'json' } from my import, which is breaking the code.

I have this helper function:

const importWithoutVite = (path: string) => import(/* @vite-ignore */ path, {
  with: { type: 'json' },
});

and running vite build generates this code:

const Wa=t=>ja(()=>import(t),[]);

[patak-dev]

About moving from

import txt from './foo.txt?raw'

to

import txt from './foo.txt' with { type: 'raw' }

I think this is good from an authoring POV. We'll still need to use the fullId (converted to a valid URL) during import analysis as the browser won't send the vite server the import attributes so in the browser there will only be fullId specifiers. Maybe it is fine and we have to accept an even bigger gap between the authored code and the transformed urls. I agree that a clean id can be easier to work with for plugins in the long run.

We can probably have environment.transformRequest(url, attributes) and environment.transformRequest(fullUrl) (and same for other APIs). Or we can define that it is always only the former and unwrap the attributes when the browser requests the fullUrl in the middleware transform. To be honest, if the attributes param is optional, I think we may see a lot of bugs in plugins because they authors will forget to pass it. Maybe we need a concept like FullId is an { id, attributes } and all APIs will get this object as a param so it is straight-forward to get this right.

[Westbrook]

This would be a huge benefit to the quality of experience that me and my team get from working with Vite and Vitest. Hopefully it is something that can come to life very soon!

Getting in position to both support native and non-standard types will prepare Vite to support the specification of future attributes type (like html) via polyfilling. In the cases that said polyfilling or other standing support for attributes clash with final specfications, how can Vite prepare to smooth the transition to other native implementations in the future?

[juner]

If the same type name were implemented natively, there would be a possibility of differences.
For that reason, wouldn't it be better to implement it with a key other than type ?
For example, vite-type ...?

tc39/proposal-import-attributes#147

[yyx990803]

We just discussed this again at the Vite team meeting yesterday, and we are now leaning towards option (2) described here - i.e., plugin hooks will receive the unique id with the attributes serialized as query strings.

In other words:

import txt from './foo.txt' with { type: 'raw' }

Would essentially become syntax sugar (but more standardized and type-friendly) for:

import txt from './foo.txt?type=raw'

And in plugin hooks:

transform(code, id, { rawId, attributes }) {
  // id: "./foo.txt?type=raw"
  // rawId: "./foo.txt"
  // attributes: { type: raw }
}

If there are no import attributes, then id would be the same as before.

---

Some reasoning behind this:

• Less impact on internal implementations

  Non-unique Ids introduces a more significant mental model shift when it comes to Rollup / Rolldown's internal architecture. Whereas always-unique ids keeps everything more aligned with before.

• Breakage might not be as significant as we thought

  We previously thought that including serialized attributes in id would lead to a lot of breakage, but in practice, the userland breakage might be smaller than we previous assumed because no one is using import attributes in Rollup / Vite at the moment because it's not fully supported.

  Moreover, semantically, the presence of import attributes indicates that the file should be handled differently from the version without import attributes, so no longer being matched by extension checks is to some extent expected, and there should a plugin dedicated to handle such ids. Including attributes as serialized query string would also allow plugins that rely on query strings (e.g. @vitejs/plugin-vue) to migrate to import attributes with relative ease.

[sapphi-red]

@redfox-mx
We haven't discussed how to handle that case. But IMHO Vite should treat them like:

import './foo.css' // works same as currently
import foo from './foo.css' with { type: 'url' } // same as `./foo.css?url`
import foo from './foo.css' with { type: 'inline' } // same as `./foo.css?inline`
import foo from './foo.css' with { type: 'css' } // constructable stylesheet
import foo from './foo.unknown' with { type: 'css' } // probably throw an error that it's not supported by default

What I think is important is that what works in the browser should work the same in Vite. Vite can add features, but shouldn't conflict with browsers.

[coxmi]

Is it worth considering the hash fragment part of the URL for the unique id?

import './foo.css' with { type: 'url' } // id equals `./foo.css#type=url`
import './foo.css?type=url' with { type: 'css' } // id equals `./foo.css?type=url#type=css`

Or alternatively, a hash of the stringified import attributes — the attributes don't need to be readable from the fragment, it only needs to provide a unique id:

import './foo.css' with { type: 'url' } // id equals `./foo.css#33c6f540242dd55f09c087f1ebdd50b328324d19`

That's compatible with all three points above, particularly if new plugins are expected to deal with import attributes separately.

[lilnasy]

Browsers don't send the hash in HTTP requests. In fact, it's not part of the HTTP protocol at all. It's just for page-internal state.

[coxmi]

If the problem is allowing unique IDs in rollup, import attributes that don't conflict with query parameters, as well as browser compatibility with the same source code, that sounds like a useful feature to me!

[redfox-mx]

What I think is important is that what works in the browser should work the same in Vite. Vite can add features, but shouldn't conflict with browsers.

@sapphi-red Thats a good point but..

import foo from './foo.unknown' with { type: 'css' }

It is a totally valid import, browser does not look for file extension, instead, MIME types indicates the nature and format of a document, file, or assortment of bytes..

IMO, vite can process modules like

For example

import styles from './foo.unknow?css-module' with { type: 'css' };

1. ResolveId: look for file extension, then for type attribute (type: css)
2. Load: look for file extension, then for type attribute (type: css)
3. Trasnform:
   4.1 1) parse query transforms (loadded css to css modules) (css-modules)
   4.2 2) parse import attributes (css modules to constructable stylesheets) (type: css)

import foo from './foo.css' with { type: 'url' } // same as `./foo.css?url`

1. ResolveId: look for file extension, then for type attribute (file .css)
2. Load: look for file extension, then for type attribute (file.css)
3. Trasnform:
   4.1 1) parse query transforms (none)
   4.2 2) parse import attributes (css as url)

Ofc, order is importan, css plugin needs be added before url... probably allow only one, attributes or queries?

[ArnaudBarre]

We will need microsoft/TypeScript#46135 to support the worker&url one

[Hebilicious]

Regarding the type namespace, I think it's a legit concern, maybe we could make the default key vite, and process all type keys that are un-supported by the runtime:

import foo1 from './foo.css' with { type: 'css' } // runtime behaviour
import foo2 from './foo.css' with { vite: 'css' } // override default behaviour with vite
import foo3 from './foo.css' with { type: 'url' } // same as `./foo.css?url`
import foo4 from './foo.css' with { vite: 'url' } // same as foo3

[m-jung]

It may not be a common use case, but it is possible that the written source code is not bundled with Vite. In fact, it may not be bundled at all.
Import Attributes are natively supported, so there is no strict need for bundling in Vanilla JavaScript projects.
However, developers might want to bundle the source, which they cannot manipulate, using Vite or other bundlers, and here I see a potential issue.
The standard syntax should be understood by Vite without further guidance. Anything beyond that should be supplementary in a way that does not conflict with current or future web standards.

That said, i'd suggest to:

1. Leave the URL as is. './foo.css' instead of './foo.css?type=inline'.
2. Use name-spaced attributes alongside standard ones. { type: 'css', 'vite-type': 'inline' }
3. Provide an easy way to configure how to deal with imports.

// vite.config.ts
export default {
    resolve: {
        importAttributes: ( id: string, attributes: Record<string, any> ): Record<string, any> => {
            return { ...attributes, 'vite-type': 'inline' };
        }
    }
}

[jpzwarte]

‪Stefan Judis‬
‪@stefanjudis.com‬
· 20h
It was about time, wasn't it? 😅 👇

But now, with Firefox 138 all major browser engines support import attributes to import JSON from within your ECMAScript modules. 👇

✅ Chromium: 123+
✅ Safari: 17.2+
✅ Firefox: 138+ (released 2w ago)

PS. This syntax works in modern Node.js, too!

Still no support in vite? Unless i'm missing something?

[jpzwarte]

We are now in a weird situation where using a plugin like https://www.npmjs.com/package/rollup-plugin-css-modules works fine for vite build, but breaks vite dev.

[otomad]

inline is often used with other types, how about separating it into a single property? For example:

// Before
import cssText from "./foo.css?inline";
// After
import cssText from "./foo.css" with { type: "css", inline: true };

// Before
import MyWorker from "./worker?worker&inline";
// After
import MyWorker from "./worker" with { type: "worker", inline: true };