diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index c1106a7eca069..42cc5d7a98d69 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -32,20 +32,26 @@ interface AstroIntegration { addClientDirective: (directive: ClientDirectiveConfig) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: ({ pattern: string, entryPoint: string }) => void; + logger: AstroIntegrationLogger; }) => void; - 'astro:config:done'?: (options: { config: AstroConfig }) => void | Promise; - 'astro:server:setup'?: (options: { server: vite.ViteDevServer }) => void | Promise; - 'astro:server:start'?: (options: { address: AddressInfo }) => void | Promise; - 'astro:server:done'?: () => void | Promise; - 'astro:build:start'?: () => void | Promise; + 'astro:config:done'?: (options: { config: AstroConfig; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:setup'?: (options: { vite: ViteConfigWithSSR; pages: Map; target: 'client' | 'server'; + logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:build:generated'?: (options: { dir: URL }) => void | Promise; - 'astro:build:ssr'?: (options: { manifest: SerializedSSRManifestm, entryPoints: Map }) => void | Promise; - 'astro:build:done'?: (options: { dir: URL; routes: RouteData[] }) => void | Promise; + 'astro:build:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:build:ssr'?: (options: { + manifest: SerializedSSRManifestm; + entryPoints: Map; + logger: AstroIntegrationLogger; + }) => void | Promise; + 'astro:build:done'?: (options: { dir: URL; routes: RouteData[]; logger: AstroIntegrationLogger; }) => void | Promise; }; } ``` @@ -71,6 +77,7 @@ interface AstroIntegration { addWatchFile: (path: URL | string) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: ({ pattern: string, entryPoint: string }) => void; + logger: AstroIntegrationLogger; }) => void; ``` @@ -527,6 +534,69 @@ export default defineConfig({ 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` + +An instance of the Astro logger, useful to write logs. This logger uses the same [log level](/en/reference/cli-reference/#--verbose) +configured via CLI. + +**Methods available** to write to terminal: +- `logger.info("Messsage")`; +- `logger.warn("Messsage")`; +- `logger.error("Messsage")`; +- `logger.debug("Messsage")`; + +All the messages are prepended with a label that has the same value of the integration. + +```ts title="integration.ts" {8} +import type { AstroIntegration } from "astro"; +export function formatIntegration(): AstroIntegration { + return { + name: "astro-format", + hooks: { + "astro:build:done": (options, { logger }) => { + // do something + logger.info("Integration ready."); + } + } + } +} +``` + +The example above will log a message that includes the provided `info` message: + +```shell +[astro-format] Integration ready. +``` + +To log some messages with a different label, use the `.fork` method to specify an alternative to the default `name`: + +```ts title="integration.ts" ".fork" +import type { AstroIntegration } from "astro"; +export function formatIntegration(): AstroIntegration { + return { + name: "astro-format", + hooks: { + "astro:config:done": ({ logger }) => { + // do something + logger.info("Integration ready."); + }, + "astro:build:done": ({ logger }) => { + const buildLogger = logger.fork("astro-format/build"); + // do something + buildLogger.info("Build finished.") + } + } + } +} +``` + +The example above will produce logs with `[astro-format]` by default, and `[astro-format/build]` when specified: + +```shell +[astro-format] Integration ready. +[astro-format/build] Build finished. +``` + ## Integration Ordering All 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`.