Usage

Astro Integration Kit can be used in 2 ways: as extended hooks or as standalone utilities.

Which flavor should you use?

Extended hooks provide a way better DX and we recommend picking this one by default. However, if you have an existing integration that you want to migrate to astro-integration-kit, using standalone utilities will allow you to migrate progressively. Any standalone utility is also available as an extended hook argument.

Extended hooks

Note

Extended hooks provide great DX. Using this flavor allows you to take fully advantage of Astro Integration Kit’s power. We recommend picking this one by default.

Plugins

Astro Integration Kit is built in a modular way. By default, it brings a solid foundation that makes it easily extendable by plugins. By default, no plugin is enabled but the package ships with some corePlugins (documented on this website), that you can easily enable, either all at once or one by one as needed.

All plugins

my-integration/index.ts

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

export default defineIntegration({
    name: "my-integration",
    plugins: [...corePlugins],
    setup() {
        return {
            "astro:config:setup": ({ addDts }) => {}
        }
    }
})

One by one

my-integration/index.ts

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

export default defineIntegration({
    name: "my-integration",
    plugins: [addDtsPlugin],
    setup() {
        return {
            "astro:config:setup": ({ addDts }) => {}
        }
    }
})

This allows other developers to easily add their own plugins.

Using plugins (soon) Learn how to use plugins to fully take advantage of Astro Integration Kit.

Defining an integration

To define your integration, use the defineIntegration utility:

my-integration/index.ts

import { createResolver, defineIntegration } from "astro-integration-kit";
import { corePlugins } from "astro-integration-kit/plugins"

export default defineIntegration({
    name: "my-integration",
    plugins: [...corePlugins],
    setup() {
        const { resolve } = createResolver(import.meta.url);
        return {
            "astro:config:setup": ({ watchIntegration }) => {
                watchIntegration(resolve())
            }
        }
    }
})

Learn more about defineIntegration A powerful wrapper around the standard Astro Integrations API. It allows to provide extra hooks, functionality and best-practices when creating Astro Integrations.

Standalone utilities

Note

Standalone utilities will allow you to migrate progressively if you have an existing integration you want to migrate to astro-integration-kit. Any standalone utility is also available as an extended hook plugin.

Use utilities exported from astro-integration-kit/utilities:

integration/index.ts

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

export default function myIntegration(): AstroIntegration {
    const { resolve } = createResolver(import.meta.url);
    return {
        name: "my-integration",
        hooks: {
            "astro:config:setup": ({ addWatchFile, command, updateConfig }) => {
                watchIntegration({
                    addWatchFile,
                    command,
                    dir: resolve(),
                    updateConfig,
                });
            },
        }
    }
}