Astro Integration API
Astro Integrations add new functionality and behaviors for your project with only a few lines of code.
This reference page is for anyone writing their own integration. To learn how to use an integration in your project, check out our Using Integrations guide instead.
Examples
Section titled ExamplesThe official Astro integrations can act as reference for you as you go to build your own integrations.
Quick API Reference
Section titled Quick API ReferenceHooks
Section titled HooksAstro provides hooks that integrations can implement to execute during certain parts of Astro’s lifecycle. Astro hooks are defined in the IntegrationHooks
interface, which is part of the global Astro
namespace.
The following hooks are built in to Astro:
astro:config:setup
Section titled astro:config:setupNext hook: astro:config:done
When: On initialization, before either the Vite or Astro config have resolved.
Why: To extend the project config. This includes updating the Astro config, applying Vite plugins, adding component renderers, and injecting scripts onto the page.
config
option
Section titled config optionType: AstroConfig
A read-only copy of the user-supplied Astro config. This is resolved before any other integrations have run. If you need a copy of the config after all integrations have completed their config updates, see the astro:config:done
hook.
command
option
Section titled command optionType: 'dev' | 'build' | 'preview' | 'sync'
dev
- Project is executed withastro dev
build
- Project is executed withastro build
preview
- Project is executed withastro preview
sync
- Project is executed withastro sync
isRestart
option
Section titled isRestart optionType: boolean
false
when the dev server starts, true
when a reload is triggered. Useful to detect when this function is called more than once.
updateConfig
option
Section titled updateConfig optionType: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
A callback function to update the user-supplied Astro config. Any config you provide will be merged with the user config + other integration config updates, so you are free to omit keys!
For example, say you need to supply a Vite plugin to the user’s project:
addRenderer
option
Section titled addRenderer optionType: (renderer:
AstroRenderer
) => void;
Examples: svelte
, react
, preact
, vue
, solid
A callback function to add a component framework renderer (i.e. React, Vue, Svelte, etc). You can browse the examples and type definition above for more advanced options, but here are the 2 main options to be aware of:
clientEntrypoint
- path to a file that executes on the client whenever your component is used. This is mainly for rendering or hydrating your component with JS.serverEntrypoint
- path to a file that executes during server-side requests or static builds whenever your component is used. These should render components to static markup, with hooks for hydration where applicable. React’srenderToString
callback is a classic example.
Added in:
astro@5.0.0
Beta
The functions clientEntrypoint
and serverEntrypoint
accept a URL
.
addWatchFile
option
Section titled addWatchFile optionType: URL | string
If your integration depends on some configuration file that Vite doesn’t watch and/or needs a full dev server restart to take effect, add it with addWatchFile
. Whenever that file changes, the Astro dev server will be reloaded (you can check when a reload happens with isRestart
).
Example usage:
addClientDirective
option
Section titled addClientDirective option
Added in:
astro@2.6.0
Type: (directive:
ClientDirectiveConfig
) => void;
Adds a custom client directive to be used in .astro
files.
Note that directive entrypoints are only bundled through esbuild and should be kept small so they don’t slow down component hydration.
Example usage:
You can also add types for the directives in your library’s type definition file:
addDevToolbarApp
option
Section titled addDevToolbarApp option
Added in:
astro@3.4.0
Type: (pluginEntrypoint: string) => void;
Adds a custom dev toolbar app.
Example usage:
addMiddleware
option
Section titled addMiddleware option
Added in:
astro@3.5.0
Type: (middleware:
AstroIntegrationMiddleware
) => void;
Adds middleware to run on each request. Takes the entrypoint
module that contains the middleware, and an order
to specify whether it should run before (pre
) other middleware or after (post
).
Middleware is defined in a package with an onRequest
function, as with user-defined middleware.
Added in:
astro@5.0.0
Beta
The function also accepts a URL
for entrypoint
:
injectRoute
option
Section titled injectRoute optionType: ({ pattern: string; entrypoint: string; pattern?: boolean }) => void;
A callback function to inject routes into an Astro project. Injected routes can be .astro
pages or .js
and .ts
route handlers.
injectRoute
takes an object with a pattern
and an entrypoint
.
pattern
- where the route should be output in the browser, for example/foo/bar
. Apattern
can use Astro’s filepath syntax for denoting dynamic routes, for example/foo/[bar]
or/foo/[...bar]
. Note that a file extension is not needed in thepattern
.entrypoint
- a bare module specifier pointing towards the.astro
page or.js
/.ts
route handler that handles the route denoted in thepattern
.prerender
- a boolean to set if Astro can’t detect yourprerender
export.
Example usage
Section titled Example usageFor an integration designed to be installed in other projects, use its package name to refer to the route entrypoint.
The following example shows a package published to npm as @fancy/dashboard
injecting a dashboard route:
When publishing your package (@fancy/dashboard
, in this case) to npm, you must export dashboard.astro
in your package.json
:
Added in:
astro@5.0.0
Beta
The function also accepts a URL
for entrypoint
:
injectScript
option
Section titled injectScript optionType: (stage: InjectedScriptStage, content: string) => void;
A callback function to inject a string of JavaScript content onto every page.
The stage
denotes how this script (the content
) should be inserted. Some stages allow inserting scripts without modification, while others allow optimization during Vite’s bundling step:
-
"head-inline"
: Injected into a script tag in the<head>
of every page. Not optimized or resolved by Vite. -
"before-hydration"
: Imported client-side, before the hydration script runs. Optimized and resolved by Vite. -
"page"
: Similar tohead-inline
, except that the injected snippet is handled by Vite and bundled with any other<script>
tags defined inside of Astro components on the page. The script will be loaded with a<script type="module">
in the final page output, optimized and resolved by Vite. -
"page-ssr"
: Imported as a separate module in the frontmatter of every Astro page component. Because this stage imports your script, theAstro
global is not available and your script will only be run once when theimport
is first evaluated.The main use for the
page-ssr
stage is injecting a CSSimport
into every page to be optimized and resolved by Vite:
createCodegenDir
Section titled createCodegenDirType: () => URL;
astro@5.0.0
Beta
A function that creates the <root>/.astro/integrations/<normalized_integration_name>
folder and returns its path.
It allows you to have a dedicated folder, avoiding conflicts with another integration or Astro itself. This directory is created by calling this function so it’s safe to write files to it directly:
astro:config:done
Section titled astro:config:donePrevious hook: astro:config:setup
Next hook: astro:server:setup
when running in “dev” mode, or astro:build:start
during production builds
When: After the Astro config has resolved and other integrations have run their astro:config:setup
hooks.
Why: To retrieve the final config for use in other hooks.
config
option
Section titled config optionType: AstroConfig
A read-only copy of the user-supplied Astro config. This is resolved after other integrations have run.
setAdapter
option
Section titled setAdapter optionType: (adapter: AstroAdapter) => void;
Makes the integration an adapter. Read more in the adapter API.
injectTypes
options
Section titled injectTypes options
Added in:
astro@4.14.0
Type: (injectedType: { filename: string; content: string }) => URL
Allows you to inject types into your user’s project by adding a new *.d.ts
file.
The filename
property will be used to generate a file at /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts
and must end with ".d.ts"
.
The content
property will create the body of the file and must be valid TypeScript.
Additionally, injectTypes()
returns a URL to the normalized path so you can overwrite its content later on, or manipulate it in any way you want.
astro:server:setup
Section titled astro:server:setupPrevious hook: astro:config:done
Next hook: astro:server:start
When: Just after the Vite server is created in “dev” mode, but before the listen()
event is fired. See Vite’s createServer API for more.
Why: To update Vite server options and middleware, or enable support for refreshing the content layer.
server
option
Section titled server optionType: ViteDevServer
A mutable instance of the Vite server used in “dev” mode. For instance, this is used by our Partytown integration to inject the Partytown server as middleware:
refreshContent
option
Section titled refreshContent optionType: (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>
astro@5.0.0
Beta
A function for integrations to trigger an update to the content layer during astro dev
. This can be used, for example, to register a webhook endpoint during dev, or to open a socket to a CMS to listen for changes.
By default, refreshContent
will refresh all collections. You can optionally pass a loaders
property, which is an array of loader names. If provided, only collections that use those loaders will be refreshed. For example, A CMS integration could use this property to only refresh its own collections.
You can also pass a context
object to the loaders. This can be used to pass arbitrary data such as the webhook body, or an event from the websocket.
The loader can then access the refreshContextData
property to get the webhook body. See the refreshContextData
property for more information.
astro:server:start
Section titled astro:server:startPrevious hook: astro:server:setup
Next hook: astro:server:done
When: Just after the server’s listen()
event has fired.
Why: To intercept network requests at the specified address. If you intend to use this address for middleware, consider using astro:server:setup
instead.
address
option
Section titled address optionType: AddressInfo
The address, family and port number supplied by the Node.js Net module.
astro:server:done
Section titled astro:server:donePrevious hook: astro:server:start
When: Just after the dev server is closed.
Why: To run any cleanup events you may trigger during the astro:server:setup
or astro:server:start
hooks.
astro:build:start
Section titled astro:build:startPrevious hook: astro:config:done
Next hook: astro:build:setup
When: After the astro:config:done
event, but before the production build begins.
Why: To set up any global objects or clients needed during a production build. This can also extend the build configuration options in the adapter API.
astro:build:setup
Section titled astro:build:setupPrevious hook: astro:build:start
Next hook: astro:build:ssr
When: After the astro:build:start
hook, runs immediately before the build.
Why: At this point, the Vite config for the build has been completely constructed, this is your final chance to modify it. This can be useful for example to overwrite some defaults. If you’re not sure whether you should use this hook or astro:build:start
, use astro:build:start
instead.
astro:build:generated
Section titled astro:build:generatedPrevious hook: astro:build:setup
When: After a static production build has finished generating routes and assets.
Why: To access generated routes and assets before build artifacts are cleaned up. This is a very uncommon use case. We recommend using astro:build:done
unless you really need to access the generated files before cleanup.
astro:build:ssr
Section titled astro:build:ssrPrevious hook: astro:build:setup
When: After a production SSR build has completed.
Why: To access the SSR manifest and map of the emitted entry points. This is useful when creating custom SSR builds in plugins or integrations.
entryPoints
maps a page route to the physical file emitted after the build;middlewareEntryPoint
is the file system path of the middleware file;
astro:build:done
Section titled astro:build:donePrevious hook: astro:build:ssr
When: After a production build (SSG or SSR) has completed.
Why: To access generated routes and assets for extension (ex. copy content into the generated /assets
directory). If you plan to transform generated assets, we recommend exploring the Vite Plugin API and configuring via astro:config:setup
instead.
dir
option
Section titled dir optionType: URL
A URL path to the build output directory. Note that if you need a valid absolute path string, you should use Node’s built-in fileURLToPath
utility.
routes
option
Section titled routes optionType: IntegrationRouteData[]
A list of all generated routes alongside their associated metadata.
You can reference the full IntegrationRouteData
type below, but the most common properties are:
component
- the input file path relative to the project rootpathname
- the output file URL (undefined for routes using[dynamic]
and[...spread]
params)
IntegrationRouteData
type reference
Section titled IntegrationRouteData type referencepages
option
Section titled pages optionType: { pathname: string }[]
A list of all generated pages. It is an object with one property.
pathname
- the finalized path of the page.
astro:route:setup
Section titled astro:route:setup
Added in:
astro@4.14.0
When: In astro dev
, whenever a route is requested. In astro build
, while bundling and transforming a route file.
Why: To set options for a route at build or request time, such as enabling on-demand server rendering.
route
option
Section titled route optionType: RouteOptions
An object with a component
property to identify the route and the following additional values to allow you to configure the generated route: prerender
.
The component
property is a readonly string path relative to the project root, e.g "src/pages/blog/[slug].astro"
.
route.prerender
Section titled route.prerenderType: boolean
Default: undefined
astro@4.14.0
The prerender
property is used to configure on-demand server rendering for a route. If the route file contains an explicit export const prerender
value, the value will be used as the default instead of undefined
.
If the final value after running all the hooks is undefined
, the route will fall back to a prerender default based on the output
option: prerendered for static
mode, and on-demand rendered for server
mode.
Custom hooks
Section titled Custom hooksCustom hooks can be added to integrations by extending the IntegrationHooks
interface through global augmentation.
Astro reserves the astro:
prefix for future built-in hooks. Please choose a different prefix when naming your custom hook.
HookParameters
Section titled HookParametersYou can get the type of a hook’s arguments by passing the hook’s name to the HookParameters
utility type. In the following example, a function’s options
argument is typed to match the parameters of the astro:config:setup
hook:
Allow installation with astro add
Section titled Allow installation with astro addThe astro add
command allows users to easily add integrations and adapters to their project. If you want your integration to be installable with this tool, add astro-integration
to the keywords
field in your package.json
:
Once you publish your integration to npm, running astro add example
will install your package with any peer dependencies specified in your package.json
. This will also apply your integration to the user’s astro.config
like so:
This assumes your integration definition is 1) a default
export and 2) a function. Ensure this is true before adding the astro-integration
keyword!
AstroIntegrationLogger
Section titled AstroIntegrationLoggerAn instance of the Astro logger, useful to write logs. This logger uses the same log level configured via CLI.
Methods available to write to terminal:
logger.info("Message")
;logger.warn("Message")
;logger.error("Message")
;logger.debug("Message")
;
All the messages are prepended with a label that has the same value of the integration.
The example above will log a message that includes the provided info
message:
To log some messages with a different label, use the .fork
method to specify an alternative to the default name
:
The example above will produce logs with [astro-format]
by default, and [astro-format/build]
when specified:
Integration Ordering
Section titled Integration OrderingAll integrations are run in the order that they are configured. For instance, for the array [react(), svelte()]
in a user’s astro.config.*
, react
will run before svelte
.
Your integration should ideally run in any order. If this isn’t possible, we recommend documenting that your integration needs to come first or last in your user’s integrations
configuration array.
Combine integrations into presets
Section titled Combine integrations into presetsAn integration can also be written as a collection of multiple, smaller integrations. We call these collections presets. Instead of creating a factory function that returns a single integration object, a preset returns an array of integration objects. This is useful for building complex features out of multiple integrations.
Community Resources
Section titled Community Resources- Build your own Astro Integrations - by Emmanuel Ohans on FreeCodeCamp
- Astro Integration Template - by Florian Lefebvre on GitHub