Upgrade guide
Features get added and removed, and breaking changes are introduced! This documents how to migrate.
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:
1import { watchIntegration } from "astro-integration-kit"2watchIntegration(params, resolve())3import { watchDirectory } from "astro-integration-kit"4watchDirectory(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.
1import {2 defineIntegration,3 withPlugins4} from "astro-integration-kit";5import { hasVitePluginPlugin } from "astro-integration-kit/plugins";6
7export 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:
1type 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) => UtilityOutput8 }9 }10>;
The definePlugin
signature has been updated as well:
1import type { AstroConfig } from "astro";2import type { Plugin, PluginOption } from "vite";3import { definePlugin } from "astro-integration-kit";4import { hasVitePlugin } from "../utilities/has-vite-plugin.js";5
6export 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:
1import { defineIntegration } from "astro-integration-kit"2import {3 corePlugins,4 hasVitePluginPlugin5} from "astro-integration-kit/plugins"6
7export default defineIntegration({8 // ...9 plugins: [...corePlugins],10 plugins: [hasVitePluginPlugin]11})
Updated utilities
addDevToolbarFrameworkApp
1const { resolve } = createResolver(import.meta.url)2
3addDevToolbarFrameworkApp({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})19addDevToolbarFrameworkApp(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
1addDts({2 name: "my-integration",3 content: `declare module "virtual:my-integration" {}`,4 root: config.root,5 srcDir: config.srcDir,6 logger,7})8addDts(params, {9 name: "my-integration",10 content: `declare module "virtual:my-integration" {}`,11})
addIntegration
1addIntegration({2 integration: Vue(),3 updateConfig,4 config,5 logger,6})7addIntegration(params,{8 integration: Vue(),9})
addVirtualImports
1addVirtualImports({2 name: 'my-integration',3 imports: {4 'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,5 },6 updateConfig,7 config,8})9addVirtualImports(params, {10 name: 'my-integration',11 imports: {12 'virtual:my-integration/config': `export default ${JSON.stringify({ foo: "bar" })}`,13 },14})
addVitePlugin
1addVitePlugin({2 plugin: VitePWA({ registerType: 'autoUpdate' }),3 config,4 logger,5 updateConfig6})7addVitePlugin(params, {8 plugin: VitePWA({ registerType: 'autoUpdate' }),9})
hasVitePlugin
1hasVitePlugin({2 plugin: "vite-plugin-my-integration",3 config,4})5hasVitePlugin(params, {6 plugin: "vite-plugin-my-integration",7})
hasIntegration
1hasIntegration({2 name: "@astrojs/tailwind",3 position: "before",4 relativeTo: "my-integration",5 config,6})7hasIntegration(params, {8 name: "@astrojs/tailwind",9 position: "before",10 relativeTo: "my-integration",11})
injectDevRoute
1const { resolve } = createResolver(import.meta.url)2
3injectDevRoute({4 command,5 injectRoute,6 injectedRoute: {7 pattern: "/foo",8 entrypoint: resolve("./pages/foo.astro")9 },10})11injectDevRoute(params, {12 pattern: "/foo",13 entrypoint: resolve("./pages/foo.astro")14})
watchIntegration
1const { resolve } = createResolver(import.meta.url)2
3watchIntegration({4 addWatchFile,5 command,6 dir: resolve(),7 updateConfig,8});9watchIntegration(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
.
1defineIntegration({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:
1type SomePlugin = Plugin<2 "utilityName",3 "astro:config:setup",4 (p: HookParams) => (params: UtilityParams) => UtilityOutput5 (params: UtilityParams) => UtilityOutput6>;7
8export 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 logger6 updateConfig7 })8}
Or you can turn off warnings for duplicate plugins using warnDuplicate: false
1addVitePlugin({2 warnDuplicate: false,3 plugin,4 updateConfig5})
Updated addVirtualImports
The addVirtualImports
utility now requires a config
parameter
1"astro:config:setup": ({ config, updateConfig }) => {2 addVirtualImports({3 updateConfig,4 config5 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:
1import { defineIntegration } from "astro-integration-kit";2import { addVirtualImportPlugin } from "astro-integration-kit/plugins";3import { addVirtualImportsPlugin } from "astro-integration-kit/plugins";4
5export 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})
1import type { AstroIntegration } from "astro";2import { addVirtualImport } from "astro-integration-kit/utilities";3import { addVirtualImports } from "astro-integration-kit/utilities";4
5export 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:
1import { defineIntegration, defineOptions } from "astro-integration-kit";2import { defineIntegration } from "astro-integration-kit";3import { z } from "astro/zod";4
5type Options = {6 /**7 * A comment8 *9 * @default `"bar"`10 */11 foo?: string | undefined;12}13
14export default defineIntegration({15 // ...16 options: defineOptions<Options>({ foo: "bar" }),17 optionsSchema: z.object({18 /**19 * A comment20 *21 * @default `"bar"`22 */23 foo: z.string().optional().default("bar"),24 }),25})