addVirtualImports

addVirtualImports allows you to create virtual modules and share data from your integration. For example:

Extended hooks

my-integration/index.ts

import { defineIntegration } from "astro-integration-kit";
import { addVirtualImportsPlugin } from "astro-integration-kit/plugins";

export default defineIntegration({
    name: "my-integration",
    plugins: [addVirtualImportsPlugin],
    setup() {
        return {
            "astro:config:setup": ({ addVirtualImports }) => {
                addVirtualImports({
                    'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
                })
                addVirtualImports([
                    {
                        id: "virtual:my-integration/advanced",
                        content: "export const foo = 'server'",
                        context: "server"
                    },
                    {
                        id: "virtual:my-integration/advanced",
                        content: "export const foo = 'client'",
                        context: "client"
                    },
                ])
            }
        }
    }
})

Standalone utilities

integration/index.ts

import type { AstroIntegration } from "astro";
import { addVirtualImports } from "astro-integration-kit/utilities";

export default function myIntegration(): AstroIntegration {
    return {
        name: "my-integration",
        hooks: {
            "astro:config:setup": ({ config, updateConfig }) => {
                addVirtualImports({
                    updateConfig,
                    config,
                    name: 'my-integration',
                    imports: {
                        'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
                    },
                })
                addVirtualImports({
                    config,
                    updateConfig,
                    name: 'my-integration',
                    imports: [
                        {
                            id: "virtual:my-integration/advanced",
                            content: "export const foo = 'server'",
                            context: "server"
                        },
                        {
                            id: "virtual:my-integration/advanced",
                            content: "export const foo = 'client'",
                            context: "client"
                        },
                    ]
                })
            }
        }
    }
}

Note

While you can choose any name for your virtual module, it’s a good idea to stick to this convention as much as possible:

• If the module is an “internal” module (ie. only supposed to be used by other parts of your integration), follow this pattern: virtual:${integrationName}/${moduleName}
• If you want your module to be used by your end user, in other words someone who will install your integration, follow this pattern: ${integrationName}/${moduleName}

You can now access the config somewhere else, for example inside a page injected by your integration:

my-integration/src/pages/index.astro

---
import config from "virtual:my-integration/config",

console.log(config.foo) // "bar"
---

Caution

Virtual modules defined with addVirtualImports cannot be referenced inside your integration code, for example inside integration/index.ts. That’s because integration code is running before vite injects the virtual imports.

Typing your virtual module

In order to get the types for your virtual modules while developing your integration, you’ll need to manually declare a virtual module.

First create a virtual.d.ts file in your integration root. Then you can define your virtual modules as global TypeScript modules:

my-integration/virtual.d.ts

declare module "virtual:my-integration/config" {
    export default { foo: string };
}

Note

Types defined in your virtual.d.ts are not accessible to end-users. They are only used whilst developing your integration.