{"id":12841,"library":"astro-integration-kit","title":"Astro Integration Kit","description":"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.","status":"active","version":"0.20.0","language":"javascript","source_language":"en","source_url":"https://github.com/florian-lefebvre/astro-integration-kit","tags":["javascript","withastro","astro","utils","utilities"],"install":[{"cmd":"npm install astro-integration-kit","lang":"bash","label":"npm"},{"cmd":"yarn add astro-integration-kit","lang":"bash","label":"yarn"},{"cmd":"pnpm add astro-integration-kit","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for building Astro integrations, requires Astro 4.14.0, 5.0.0, or 6.0.0.","package":"astro","optional":false}],"imports":[{"note":"Astro integrations are ESM-only. `defineIntegration` is the primary entry point for creating an integration.","wrong":"const defineIntegration = require('astro-integration-kit');","symbol":"defineIntegration","correct":"import { defineIntegration } from 'astro-integration-kit';"},{"note":"`addVitePlugin` is a common utility for extending Astro's Vite configuration within an integration's `astro:config:setup` hook.","symbol":"addVitePlugin","correct":"import { addVitePlugin } from 'astro-integration-kit';"},{"note":"`addVirtualImports` simplifies the creation and management of Vite virtual modules, a common pattern for injecting runtime data into Astro projects.","symbol":"addVirtualImports","correct":"import { addVirtualImports } from 'astro-integration-kit';"},{"note":"`createResolver` helps in correctly resolving module paths, particularly useful for integrations that might be published as npm packages.","symbol":"createResolver","correct":"import { createResolver } from 'astro-integration-kit';"}],"quickstart":{"code":"import { z } from 'astro/zod';\nimport { defineIntegration, addVitePlugin } from 'astro-integration-kit';\nimport vitePlugin from 'vite-plugin-example'; // Replace with an actual Vite plugin\n\nconst optionsSchema = z.object({\n  enabled: z.boolean().default(true),\n  logMessage: z.string().default('Hello from my Astro Integration!'),\n});\n\nexport default defineIntegration({\n  name: 'my-custom-integration',\n  optionsSchema,\n  setup({ options, logger }) {\n    if (!options.enabled) {\n      logger.info('My Custom Integration is disabled.');\n      return;\n    }\n\n    return {\n      hooks: {\n        'astro:config:setup': (params) => {\n          logger.info(`Injecting Vite plugin: ${options.logMessage}`);\n          addVitePlugin(params, { plugin: vitePlugin() });\n        },\n        'astro:build:done': ({ dir, routes }) => {\n          logger.success(`Build done for ${routes.length} routes in ${dir.pathname}`);\n        }\n      },\n    };\n  },\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Breaking 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.","severity":"breaking","affected_versions":">=0.5.0"},{"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.","message":"The `addDevToolbarFrameworkApp`, `watchIntegration`, and `addDts` utilities were removed or renamed in specific versions. Direct usage of these may lead to errors.","severity":"breaking","affected_versions":">=0.10.0"},{"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).","message":"Astro, 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `astro-integration-kit` package is not installed or incorrectly resolved in your project.","error":"TypeError: Cannot find module 'astro-integration-kit' or its corresponding type declarations."},{"fix":"Ensure your integration file uses `export default defineIntegration(...)` rather than named exports or direct function exports.","cause":"Astro integrations, including those built with `astro-integration-kit`, must export the integration function as the default export.","error":"Error: Expected a default export in `src/integration.ts`"},{"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.","cause":"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).","error":"ReferenceError: document is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}