[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
	}

[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?