Interface ImportEntity<K>

include a unique key that you can use to trace back the imported entity, because the path of the import in the bundled output will differ, whereas this key will remain the same.

the absolute/resolved path of the resource.

do not insert unresolved or relative paths! this is a strict design choice because you should ideally run a sub-build to acquire the resolved paths of your dependencies. of course, nothing is stopping your onTransform hook from either:

• using the build.resolve of the sub-build's parent PluginBuild (thereby not requiring re-instantiation of the plugins).
• re-instantiating the plugins in the sub-build, so that the path-resolution logic remains similar. although, this can have drawbacks; for instance, my esbuild-plugin-deno's setup method is generated based on the user's initial config (containing contextual information, such as the location of deno.json), which may not be desired in the sub-build (if for instance, the thing being resolved for the sub-build is actually inside a different package/scope than the primary package).

because there is a variablility in how you can potentially approach path resolution, we leave it up to the plugin designer to decide how they would want to resolve the paths in their onTransform hook's returned imports, rather than performing a default action ourselves.

associate a with import attribute to the import.

specify if this import should be marked as an external resource, so that it neither gets resolved, nor loaded/bundled as an output file.

if you wish for your import's path to get resolved, but not loaded/bundled as a file, then you should either:

1. set external: false and then capture path during the onResolve stage, followed by setting external to true in the returned OnResolveResult.
2. set external: true and make sure that your path is pre-resolved within the transformation stage, by simply using build.resolve(...) to resolve its path in your plugin.