Including typing definitions for virtual modules inside a package

[dburian]

Hi everybody,

I'm building a plugin (say with a name plugin-name), which intercepts imports of a virtual module and creates it dynamically (with resolveId and load hooks). The problem I am having is how to declare types for the virtual module or rather how to include them in my package.

So let's say I have a declaration of a virtual module:

declare module 'virtual:plugin-name/module' {
  import type {Graph} from 'plugin-name/types';
  let graph: Graph;
  export default graph;
}

The problem is, how to package this. I compile my code with Rollup with typescript plugin, but it gives me errors saying it cannot find the module plugin-name/types, where the definition of Graph lies in. This is intuitive as this module does not yet exist (the bundling creates this module). Similar exception occurs if I rewrite that import into a relative one - "Import or export declaration in an ambient module declaration cannot reference module through relative module name.".

Obviously one solution would be to let the user of the plugin define such declaration of manually include it in my dist/ folder. But I consider these a hacks since this declaration is part of my package and therefore should be bundled as such.

Do you have any advice on how to resolve this?

Thanks :).

[danielrentz]

@dburian I am stumbling over the same problem, did you find a solution in the meantime?

[dburian]

In the end I headed down a different path, which didn't use virtual modules, so unfortunatelly no ☹️.

[ramiel]

Same here, I'm struggling to get this working. I think I'm missing the appropriate typescript knowledge, but I'm really lost.

[danielrentz]

@ramiel In the meantime, I managed to find a solution ... or workaround:

The Vite-Plugin

• I did not find a solution to use import statements in the virtual module declaration file (virtual.d.ts in this example), therefore I declare the types there and import them from there as well.
• Your build step needs tro copy the virtual.d.ts into the package manually.
• Assuming you build src/* to dist/*.

// vite-plugin-example/src/virtual.d.ts

declare module "virtual:example" {
  export interface ExampleData { ... }
  const data: ExampleData
  export default data
}

// vite-plugin-example/src/main.ts

import type { ExampleData } from "virtual:example";

// vite-plugin-example/package.json

{
    "name": "vite-plugin-example",
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "default": "./dist/index.js"
        },
        "./virtual": {
            "types": "./dist/virtual.d.ts"
        }
    },
    "scripts": {
        "build": "npx --yes rimraf dist && tsc && npx --yes cpy-cli --flat src/virtual.d.ts dist/"
    }
}

Consumer Project

// example-project/tsconfig.json

{
    "$schema": "https://json.schemastore.org/tsconfig",
    "compilerOptions": {
        "types": [
            "vite/client",
            "vite-plugin-example/virtual"
        ]
    }
}

// example-project/src/main.ts

import type { ExampleData } from "virtual:example"

import exampleData from "virtual:example"

[ramiel]

Hey @danielrentz , I found a different solution just after posting my message. I'll share it soon but in short is similar to yours except there's no need to change tsconfig since you can update vite.d.ts that is meant for that

[pwang2]

I was doing something as below to wrap unplugin-icons for my projects. I managed to find the workarounds below. all have their caveats. @ramiel , can i ask what is your solution here?

Workaround 1

I have hundreds of icons here to reexport, so i need to repeat too many times.

import type { FunctionalComponent, SVGAttributes } from "vue"

// a workaround to export default in typescript does not keep the type after export
export { default as IconAlignJustify } from "~icons/prime/align-justify"
export type IconAlignJustify = FunctionalComponent<SVGAttributes>

export { default as IconAlignLeft } from "~icons/prime/align-left"
export { default as IconAlignRight } from "~icons/prime/align-right"

Workaround 2

use default export here requires the consumer to destruct after import. kinda ugly.

import IconWrench2 from "~icons/prime/wrench"
import IconYoutube2 from "~icons/prime/youtube"

export default { IconWrench2, IconYoutube2 } satisfies Record<
  string,
  FunctionalComponent<SVGAttributes>
>

Workaround 3

TODO: Use macro to generate the code for vite to process. not straightforward at all.