Registry / web-framework / astro-integration-kit

astro-integration-kit

library0.20.0jsnpmunverified

Astro Integration Kit (AIK) is a utility package designed to simplify and streamline the development of Astro integrations. Currently stable at version 0.20.0, the library is actively maintained with minor versions released periodically, often to align with new Astro releases and introduce new features or refinements. AIK provides a high-level API to abstract away common complexities of the Astro Integration API, such as managing Vite plugins, generating virtual modules, and resolving paths. It aims to make building robust and performant community-driven Astro integrations more accessible, differentiating itself by offering a structured and less verbose approach compared to interacting directly with Astro's lower-level integration hooks. The project has a clear upgrade guide detailing breaking changes across versions, indicating continuous evolution and improvement to keep pace with the Astro ecosystem.

web-framework

npm install astro-integration-kit

github ↗package ↗

INSTALL

IMPORT

SIG · ASTRO-INTEGRATION-

astro-integration-kit

web-frameworkjavascriptv0.20.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

defineIntegration

✓ import { defineIntegration } from 'astro-integration-kit';

✗ const defineIntegration = require('astro-integration-kit');

Astro integrations are ESM-only. `defineIntegration` is the primary entry point for creating an integration.

addVitePlugin

✓ import { addVitePlugin } from 'astro-integration-kit';

`addVitePlugin` is a common utility for extending Astro's Vite configuration within an integration's `astro:config:setup` hook.

addVirtualImports

✓ import { addVirtualImports } from 'astro-integration-kit';

`addVirtualImports` simplifies the creation and management of Vite virtual modules, a common pattern for injecting runtime data into Astro projects.

createResolver

✓ import { createResolver } from 'astro-integration-kit';

`createResolver` helps in correctly resolving module paths, particularly useful for integrations that might be published as npm packages.

This quickstart demonstrates defining a basic Astro integration using `defineIntegration` with a Zod schema for options. It conditionally adds a Vite plugin during `astro:config:setup` and logs a message on build completion.

import { z } from 'astro/zod'; import { defineIntegration, addVitePlugin } from 'astro-integration-kit'; import vitePlugin from 'vite-plugin-example'; // Replace with an actual Vite plugin const optionsSchema = z.object({ enabled: z.boolean().default(true), logMessage: z.string().default('Hello from my Astro Integration!'), }); export default defineIntegration({ name: 'my-custom-integration', optionsSchema, setup({ options, logger }) { if (!options.enabled) { logger.info('My Custom Integration is disabled.'); return; } return { hooks: { 'astro:config:setup': (params) => { logger.info(`Injecting Vite plugin: ${options.logMessage}`); addVitePlugin(params, { plugin: vitePlugin() }); }, 'astro:build:done': ({ dir, routes }) => { logger.success(`Build done for ${routes.length} routes in ${dir.pathname}`); } }, }; }, });

Debug

Known issues

breakingBreaking changes are frequently introduced in minor versions of `astro-integration-kit` as the library evolves and adapts to changes in Astro's core. Always consult the 'Upgrade guide' in the official documentation when updating between minor versions.

fix

Review the 'Upgrade guide' (e.g., for v0.16.0, v0.15.0, v0.13.0, v0.12.0, v0.11.0, v0.10.0, v0.9.0, v0.8.0) and adapt your integration code accordingly. Key changes have included renaming utilities, refactoring plugin APIs, and updating hook return types.

affects: >=0.5.0

breakingThe `addDevToolbarFrameworkApp`, `watchIntegration`, and `addDts` utilities were removed or renamed in specific versions. Direct usage of these may lead to errors.

fix

`watchIntegration` was renamed to `watchDirectory` in v0.10.0. `addDevToolbarFrameworkApp` and `addDts` were removed in v0.12.0, requiring alternative approaches for those functionalities. Refer to the upgrade guide for migration details.

affects: >=0.10.0

gotchaAstro, and by extension `astro-integration-kit`, requires specific Node.js versions. Running with an unsupported or outdated Node.js environment can lead to build failures or unexpected behavior.

fix

Ensure your Node.js version is compatible with your Astro installation. Astro 4.x/5.x/6.x generally requires Node.js 18.17.1+ or 20.3.0+. Update your Node.js environment to a supported LTS version (e.g., 20.x or 22.x).

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: Cannot find module 'astro-integration-kit' or its corresponding type declarations.

The `astro-integration-kit` package is not installed or incorrectly resolved in your project.

fix

Run `npm install astro-integration-kit` or `pnpm add astro-integration-kit` to install the package. Ensure your `tsconfig.json` includes `node_modules` in its `typeRoots` if using TypeScript.

Error: Expected a default export in `src/integration.ts`

Astro integrations, including those built with `astro-integration-kit`, must export the integration function as the default export.

fix

Ensure your integration file uses `export default defineIntegration(...)` rather than named exports or direct function exports.

ReferenceError: document is not defined

Your integration code or a dependency it uses is attempting to access browser-specific APIs (like `document` or `window`) in a server-side context (e.g., during build or SSR).

fix

Ensure that any code interacting with browser APIs is guarded (e.g., `if (typeof window !== 'undefined') { ... }`) or is explicitly marked for client-side execution, which is generally handled by the Astro components themselves, not typically within integration setup.

Upgrade

Version history

0.20.0latest on npm

Audit

Dependencies

astrorequiredPeer dependency for building Astro integrations, requires Astro 4.14.0, 5.0.0, or 6.0.0.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/florian-lefebvre/astro-integration-kit ↗

packagehttps://www.npmjs.com/package/astro-integration-kit ↗