Upgrade guide

Features get added and removed, and breaking changes are introduced! This documents how to migrate.

`0.13.0`

`Plugin` type simplified

The new Plugin signature added back in 0.9.0 returned the need for emitted declarations to include the full type for hook parameters from Astro (which was removed on 0.7.0). This was added along with support for a plugin to define new utilities for multiple hooks at once.

Now, the Plugin generics have been simplified again to allow for such support without having to replicate Astro’s hook parameters types. Just like in 0.7.0, this should be non-breaking for any plugin relying on type inference but plugins with explicitly declared signatures need to update the following:

1
type SomePlugin = Plugin<
2
    "utilityName",
3
    "astro:config:setup",
4
    {
5
        "astro:config:setup": (HookParameters<"astro:config:setup">) => {
6
        "astro:config:setup": {
7
            utilityName: (params: UtilityParams) => UtilityOutput
8
        }
9
    }
10
>;

`0.12.0`

`addDevToolbarFrameworkApp` removed

The addDevToolbarFrameworkApp has been removed in favour of the Astro defineToolbarApp utility added in Astro v4.7.0.

To migrate your Dev Toolbar App to the new Astro utility, please see their documentation here.

`0.11.0`

`defineIntegration` `setup` return type updated

Previously the return of the setup function passed to defineIntegration was the Astro hooks defined by the integration, and would be set as the hooks property in the final integration object.

Now, the expected return of setup is the properties of the integration object itself:

1
import { defineIntegration } from "astro-integration-kit";
2

3
export default defineIntegration({
4
  name: "my-integration",
5
  setup({ name }) {
6
    return {
7
      hooks: {
8
        "astro:config:setup": () => {
9
          // ...
10
        },
11
      },
12
    };
13
  },
14
});

`0.10.0`

`watchIntegration` renamed to `watchDirectory`

Since watchIntegration is not recommended for dev HMR anymore, it has been renamed according to what it really does, watching a directory:

1
import { watchIntegration } from "astro-integration-kit"
2
watchIntegration(params, resolve())
3
import { watchDirectory } from "astro-integration-kit"
4
watchDirectory(params, resolve())

`0.9.0`

New `withPlugins` utility, `plugins` removed from `defineIntegration`

Plugins are no longer passed to defineIntegration. Instead, there’s a new withPlugins utility.

1
import {
2
    defineIntegration,
3
    withPlugins
4
} from "astro-integration-kit";
5
import { hasVitePluginPlugin } from "astro-integration-kit/plugins";
6

7
export default defineIntegration({
8
    name: "my-integration",
9
    plugins: [hasVitePluginPlugin],
10
    setup({ name }) {
11
        return {
12
            "astro:config:setup": ({ hasVitePlugin }) => {}
13
        }
14
        return withPlugins({
15
            name,
16
            plugins: [hasVitePluginPlugin],
17
            hooks: {
18
                "astro:config:setup": ({ hasVitePlugin }) => {}
19
            }
20
        })
21
    }
22
})

New `Plugin` signature (and `definePlugin`)

You should not use the Plugin type manually but if you do, you’ll need to update it:

1
type SomePlugin = Plugin<
2
    "utilityName",
3
    "astro:config:setup",
4
    (params: UtilityParams) => UtilityOutput,
5
    {
6
        "astro:config:setup": (HookParameters<"astro:config:setup">) => {
7
            utilityName: (params: UtilityParams) => UtilityOutput
8
        }
9
    }
10
>;

The definePlugin signature has been updated as well:

1
import type { AstroConfig } from "astro";
2
import type { Plugin, PluginOption } from "vite";
3
import { definePlugin } from "astro-integration-kit";
4
import { hasVitePlugin } from "../utilities/has-vite-plugin.js";
5

6
export const hasVitePluginPlugin = definePlugin({
7
    name: "hasVitePlugin",
8
    hook: "astro:config:setup",
9
    implementation: (params) =>
10
        (plugin: string | PluginOption) =>
11
            hasVitePlugin(params, { plugin }),
12
    setup() {
13
        return {
14
            "astro:config:setup": (params) => ({
15
                hasVitePlugin: (plugin: string | PluginOption) =>
16
                    hasVitePlugin(params, { plugin }),
17
            }),
18
        };
19
    },
20
});

`0.8.0`

Removed plugins

The following plugins have been removed in favor of their standalone utility version:

addDevToolbarFrameworkAppPlugin
addDtsPlugin
addIntegrationPlugin
addVirtualImportsPlugin
addVitePluginPlugin
hasIntegrationPlugin
injectDevRoutePlugin
watchIntegrationPlugin

Only hasVitePluginPlugin remains.

`corePlugins` removed

corePlugins is no longer exported from astro-integration-kit. Import the plugin you want directly:

1
import { defineIntegration } from "astro-integration-kit"
2
import {
3
    corePlugins,
4
    hasVitePluginPlugin
5
} from "astro-integration-kit/plugins"
6

7
export default defineIntegration({
8
    // ...
9
    plugins: [...corePlugins],
10
    plugins: [hasVitePluginPlugin]
11
})

Updated utilities

`addDevToolbarFrameworkApp`

1
const { resolve } = createResolver(import.meta.url)
2

3
addDevToolbarFrameworkApp({
4
    framework: "vue",
5
    name: "Test Vue Plugin",
6
    id: "my-vue-plugin",
7
    icon: `<svg version="1.1" viewBox="0 0 261.76 226.69" xmlns="http://www.w3.org/2000/svg"><g transform="matrix(1.3333 0 0 -1.3333 -76.311 313.34)"><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-75.491l98.16-170.02 98.16 170.02z" fill="#41b883"/></g><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-36.227l58.896-102.01 58.896 102.01z" fill="#34495e"/></g></g></svg>`,
8
    src: resolve("./my-plugin.vue"),
9
    style: `
10
        h1 {
11
            font-family: Inter;
12
        }
13
    `,
14
    config,
15
    updateConfig,
16
    addDevToolbarApp,
17
    injectScript,
18
})
19
addDevToolbarFrameworkApp(params, {
20
    framework: "vue",
21
    name: "Test Vue Plugin",
22
    id: "my-vue-plugin",
23
    icon: `<svg version="1.1" viewBox="0 0 261.76 226.69" xmlns="http://www.w3.org/2000/svg"><g transform="matrix(1.3333 0 0 -1.3333 -76.311 313.34)"><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-75.491l98.16-170.02 98.16 170.02z" fill="#41b883"/></g><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-36.227l58.896-102.01 58.896 102.01z" fill="#34495e"/></g></g></svg>`,
24
    src: resolve("./my-plugin.vue"),
25
    style: `
26
        h1 {
27
            font-family: Inter;
28
        }
29
    `,
30
})

`addDts`

1
addDts({
2
    name: "my-integration",
3
    content: `declare module "virtual:my-integration" {}`,
4
    root: config.root,
5
    srcDir: config.srcDir,
6
    logger,
7
})
8
addDts(params, {
9
    name: "my-integration",
10
    content: `declare module "virtual:my-integration" {}`,
11
})

`addIntegration`

1
addIntegration({
2
    integration: Vue(),
3
    updateConfig,
4
    config,
5
    logger,
6
})
7
addIntegration(params,{
8
    integration: Vue(),
9
})

`addVirtualImports`

1
addVirtualImports({
2
    name: 'my-integration',
3
    imports: {
4
        'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
5
    },
6
    updateConfig,
7
    config,
8
})
9
addVirtualImports(params, {
10
    name: 'my-integration',
11
    imports: {
12
        'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
13
    },
14
})

`addVitePlugin`

1
addVitePlugin({
2
    plugin: VitePWA({ registerType: 'autoUpdate' }),
3
    config,
4
    logger,
5
    updateConfig
6
})
7
addVitePlugin(params, {
8
    plugin: VitePWA({ registerType: 'autoUpdate' }),
9
})

`hasVitePlugin`

1
hasVitePlugin({
2
    plugin: "vite-plugin-my-integration",
3
    config,
4
})
5
hasVitePlugin(params, {
6
    plugin: "vite-plugin-my-integration",
7
})

`hasIntegration`

1
hasIntegration({
2
    name: "@astrojs/tailwind",
3
    position: "before",
4
    relativeTo: "my-integration",
5
    config,
6
})
7
hasIntegration(params, {
8
    name: "@astrojs/tailwind",
9
    position: "before",
10
    relativeTo: "my-integration",
11
})

`injectDevRoute`

1
const { resolve } = createResolver(import.meta.url)
2

3
injectDevRoute({
4
    command,
5
    injectRoute,
6
    injectedRoute: {
7
        pattern: "/foo",
8
        entrypoint: resolve("./pages/foo.astro")
9
    },
10
})
11
injectDevRoute(params, {
12
    pattern: "/foo",
13
    entrypoint: resolve("./pages/foo.astro")
14
})

`watchIntegration`

1
const { resolve } = createResolver(import.meta.url)
2

3
watchIntegration({
4
    addWatchFile,
5
    command,
6
    dir: resolve(),
7
    updateConfig,
8
});
9
watchIntegration(params, resolve())

`0.7.0`

Updated `options` and `optionsSchema`

They’re not optional by default, you need to manually add .optional() at the end of your zod schema. If it’s optional, users can still pass nothing or undefined.

1
defineIntegration({
2
    // ...
3
    optionsSchema: z.object({ foo: z.string() }),
4
    optionsSchema: z.object({ foo: z.string() }).optional(),
5
})

Plugins types

Plugin generics have been simplified, allowing simpler plugin builds. This should be non-breaking for plugin relying on type inference, plugins with explicitly declared signature should update the following:

1
type SomePlugin = Plugin<
2
    "utilityName",
3
    "astro:config:setup",
4
    (p: HookParams) => (params: UtilityParams) => UtilityOutput
5
    (params: UtilityParams) => UtilityOutput
6
>;
7

8
export const somePlugin: SomePlugin = definePlugin();

`0.6.0`

Updated `addVitePlugin`

The addVitePlugin utility now requires a config and logger parameter to log warnings for duplicate plugins

1
"astro:config:setup": ({ config, updateConfig }) => {
2
    addVitePlugin({
3
        plugin,
4
        config,
5
        logger
6
        updateConfig
7
    })
8
}

Or you can turn off warnings for duplicate plugins using warnDuplicate: false

1
addVitePlugin({
2
    warnDuplicate: false,
3
    plugin,
4
    updateConfig
5
})

Updated `addVirtualImports`

The addVirtualImports utility now requires a config parameter

1
"astro:config:setup": ({ config, updateConfig }) => {
2
    addVirtualImports({
3
        updateConfig,
4
        config
5
        name: 'my-integration',
6
        imports: {
7
            'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
8
        },
9
    })
10
}

Updated `addDevToolbarFrameworkApp`

The addDevToolbarFrameworkApp utility now requires a config parameter

1
"astro:config:setup": ({ config, updateConfig }) => {
2
    addDevToolbarFrameworkApp({
3
        config,
4
        framework: "vue",
5
        name: "Test Vue Plugin",
6
        id: "my-vue-plugin",
7
        icon: `<svg>...</svg>`,
8
        src: resolve("./my-plugin.vue"),
9
        style: `
10
            h1 {
11
                font-family: Inter;
12
            }
13
        `,
14
    })
15
}

`0.5.0`

Updated `addVirtualImport`

addVirtualImport was removed in 0.5.0. Here is how to migrate:

Extended hooks
Standalone utilities

1
import { defineIntegration } from "astro-integration-kit";
2
import { addVirtualImportPlugin } from "astro-integration-kit/plugins";
3
import { addVirtualImportsPlugin } from "astro-integration-kit/plugins";
4

5
export default defineIntegration({
6
    name: "my-integration",
7
    plugins: [addVirtualImportPlugin],
8
    plugins: [addVirtualImportsPlugin],
9
    setup() {
10
        return {
11
            "astro:config:setup": ({ addVirtualImport }) => {
12
            "astro:config:setup": ({ addVirtualImports }) => {
13
                addVirtualImport({
14
                    name: 'virtual:my-integration/config',
15
                    content: `export default ${JSON.stringify({ foo: "bar" })}`,
16
                })
17
                addVirtualImport({
18
                    name: 'virtual:my-integration/context',
19
                    content: `export default ${JSON.stringify({ entrypoint: import.meta.url })}`,
20
                })
21
                addVirtualImports({
22
                    'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
23
                    'virtual:my-integration/context': `export default ${JSON.stringify({ entrypoint: import.meta.url })}`
24
                })
25
            }
26
        }
27
    }
28
})

1
import type { AstroIntegration } from "astro";
2
import { addVirtualImport } from "astro-integration-kit/utilities";
3
import { addVirtualImports } from "astro-integration-kit/utilities";
4

5
export default function myIntegration(): AstroIntegration {
6
    return {
7
        name: "my-integration",
8
        hooks: {
9
            "astro:config:setup": ({ config, updateConfig }) => {
10
                addVirtualImport({
11
                    updateConfig,
12
                    config,
13
                    name: 'virtual:my-integration/config',
14
                    content: `export default ${JSON.stringify({ foo: "bar" })}`,
15
                })
16
                addVirtualImport({
17
                    updateConfig,
18
                    config,
19
                    name: 'virtual:my-integration/context',
20
                    content: `export default ${JSON.stringify({ entrypoint: import.meta.url })}`,
21
                })
22
                addVirtualImports({
23
                    updateConfig,
24
                    config,
25
                    name: 'my-integration',
26
                    imports: {
27
                        'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,
28
                        'virtual:my-integration/context': `export default ${JSON.stringify({ entrypoint: import.meta.url })}`
29
                    },
30
                })
31
            }
32
        }
33
    }
34
}

`0.2.0`

Removed `defineOptions`

defineOptions has been removed in 0.2.0. Here is how to migrate:

1
import { defineIntegration, defineOptions } from "astro-integration-kit";
2
import { defineIntegration } from "astro-integration-kit";
3
import { z } from "astro/zod";
4

5
type Options = {
6
    /**
7
     * A comment
8
     *
9
     * @default `"bar"`
10
     */
11
    foo?: string | undefined;
12
}
13

14
export default defineIntegration({
15
    // ...
16
    options: defineOptions<Options>({ foo: "bar" }),
17
    optionsSchema: z.object({
18
        /**
19
         * A comment
20
         *
21
         * @default `"bar"`
22
         */
23
        foo: z.string().optional().default("bar"),
24
    }),
25
})

Upgrade guide

0.13.0

Plugin type simplified

0.12.0

addDevToolbarFrameworkApp removed

0.11.0

defineIntegration setup return type updated

0.10.0

watchIntegration renamed to watchDirectory

0.9.0

New withPlugins utility, plugins removed from defineIntegration

New Plugin signature (and definePlugin)

0.8.0

Removed plugins

corePlugins removed

Updated utilities

addDevToolbarFrameworkApp

addDts

addIntegration

addVirtualImports

addVitePlugin

hasVitePlugin

hasIntegration

injectDevRoute

watchIntegration

0.7.0

Updated options and optionsSchema