feat: add defineIntegration utility

packages/astro/package.json

@@ -53,6 +53,7 @@
     "./client/*": "./dist/runtime/client/*",
     "./components": "./components/index.ts",
     "./components/*": "./components/*",
+    "./integration": "./integrations/index.ts",
     "./toolbar": "./dist/toolbar/index.js",
     "./assets": "./dist/assets/index.js",
     "./assets/utils": "./dist/assets/utils/index.js",

packages/astro/src/@types/astro.ts

@@ -19,7 +19,7 @@ import type { AstroTimer } from '../core/config/timer.js';
 import type { TSConfig } from '../core/config/tsconfig.js';
 import type { AstroCookies } from '../core/cookies/index.js';
 import type { AstroIntegrationLogger, Logger, LoggerLevel } from '../core/logger/core.js';
-import type { getToolbarServerCommunicationHelpers } from '../integrations/index.js';
+import type { getToolbarServerCommunicationHelpers } from '../integrations/hooks.js';
 import type { AstroPreferences } from '../preferences/index.js';
 import type {
 	ToolbarAppEventTarget,

packages/astro/src/config/index.ts

@@ -27,7 +27,7 @@ export function getViteConfig(inlineConfig: UserConfig) {
 			import('../core/logger/node.js'),
 			import('../core/config/index.js'),
 			import('../core/create-vite.js'),
-			import('../integrations/index.js'),
+			import('../integrations/hooks.js'),
 			import('./vite-plugin-content-listen.js'),
 		]);
 		const logger = new Logger({

packages/astro/src/content/index.ts

@@ -1,5 +1,4 @@
 export { CONTENT_FLAG, PROPAGATED_ASSET_FLAG } from './consts.js';
-export { errorMap } from './error-map.js';
 export { attachContentServerListeners } from './server-listeners.js';
 export { createContentTypesGenerator } from './types-generator.js';
 export {

packages/astro/src/content/utils.ts

@@ -17,7 +17,7 @@ import { AstroError, AstroErrorData } from '../core/errors/index.js';
 import { MarkdownError } from '../core/errors/index.js';
 import { isYAMLException } from '../core/errors/utils.js';
 import { CONTENT_FLAGS, CONTENT_TYPES_FILE, PROPAGATED_ASSET_FLAG } from './consts.js';
-import { errorMap } from './error-map.js';
+import { errorMap } from '../core/errors/error-map.js';
 import { createImage } from './runtime-assets.js';
 
 /**

packages/astro/src/core/build/generate.ts

@@ -30,7 +30,7 @@ import {
 	removeTrailingForwardSlash,
 } from '../../core/path.js';
 import { toRoutingStrategy } from '../../i18n/utils.js';
-import { runHookBuildGenerated } from '../../integrations/index.js';
+import { runHookBuildGenerated } from '../../integrations/hooks.js';
 import { getOutputDirectory, isServerLikeOutput } from '../../prerender/utils.js';
 import type { SSRManifestI18n } from '../app/types.js';
 import { NoPrerenderedRoutesWithDomains } from '../errors/errors-data.js';

packages/astro/src/core/build/index.ts

@@ -18,7 +18,7 @@ import {
 	runHookBuildStart,
 	runHookConfigDone,
 	runHookConfigSetup,
-} from '../../integrations/index.js';
+} from '../../integrations/hooks.js';
 import { isServerLikeOutput } from '../../prerender/utils.js';
 import { resolveConfig } from '../config/config.js';
 import { createNodeLogger } from '../config/logging.js';

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -5,7 +5,7 @@ import { type Plugin as VitePlugin } from 'vite';
 import { getAssetsPrefix } from '../../../assets/utils/getAssetsPrefix.js';
 import { normalizeTheLocale } from '../../../i18n/index.js';
 import { toRoutingStrategy } from '../../../i18n/utils.js';
-import { runHookBuildSsr } from '../../../integrations/index.js';
+import { runHookBuildSsr } from '../../../integrations/hooks.js';
 import { BEFORE_HYDRATION_SCRIPT_ID, PAGE_SCRIPT_ID } from '../../../vite-plugin-scripts/index.js';
 import type {
 	SSRManifestI18n,

packages/astro/src/core/build/plugins/plugin-ssr.ts

@@ -2,7 +2,7 @@ import { join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { Plugin as VitePlugin } from 'vite';
 import type { AstroAdapter } from '../../../@types/astro.js';
-import { isFunctionPerRouteEnabled } from '../../../integrations/index.js';
+import { isFunctionPerRouteEnabled } from '../../../integrations/hooks.js';
 import { isServerLikeOutput } from '../../../prerender/utils.js';
 import { routeIsRedirect } from '../../redirects/index.js';
 import { addRollupInput } from '../add-rollup-input.js';

packages/astro/src/core/build/static-build.ts

@@ -17,7 +17,7 @@ import {
 import { emptyDir, removeEmptyDirs } from '../../core/fs/index.js';
 import { appendForwardSlash, prependForwardSlash, removeFileExtension } from '../../core/path.js';
 import { isModeServerWithNoAdapter } from '../../core/util.js';
-import { runHookBuildSetup } from '../../integrations/index.js';
+import { runHookBuildSetup } from '../../integrations/hooks.js';
 import { getOutputDirectory, isServerLikeOutput } from '../../prerender/utils.js';
 import { PAGE_SCRIPT_ID } from '../../vite-plugin-scripts/index.js';
 import { AstroError, AstroErrorData } from '../errors/index.js';

packages/astro/src/core/dev/container.ts

@@ -10,7 +10,7 @@ import {
 	runHookConfigSetup,
 	runHookServerDone,
 	runHookServerStart,
-} from '../../integrations/index.js';
+} from '../../integrations/hooks.js';
 import { createVite } from '../create-vite.js';
 import type { Logger } from '../logger/core.js';
 import { apply as applyPolyfill } from '../polyfill.js';

packages/astro/src/core/errors/errors-data.ts

@@ -1156,6 +1156,17 @@ export const i18nNotEnabled = {
 	hint: 'See https://docs.astro.build/en/guides/internationalization for a guide on setting up i18n.',
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @description
+ */
+export const AstroIntegrationInvalidOptions = {
+	name: 'AstroIntegrationInvalidOptions',
+	title: 'Astro Integration Invalid Options',
+	message: (name: string, error: string) =>
+		`Invalid options passed to "${name}" integration\n${error}`,
+} satisfies ErrorData;
+
 /**
  * @docs
  * @kind heading

packages/astro/src/core/errors/index.ts

@@ -11,3 +11,4 @@ export {
 export type { ErrorLocation, ErrorWithMetadata } from './errors.js';
 export { codeFrame } from './printer.js';
 export { createSafeError, positionAt } from './utils.js';
+export { errorMap } from './error-map.js';

packages/astro/src/core/preview/index.ts

@@ -5,7 +5,7 @@ import type { AstroInlineConfig, PreviewModule, PreviewServer } from '../../@typ
 import { AstroIntegrationLogger } from '../../core/logger/core.js';
 import { telemetry } from '../../events/index.js';
 import { eventCliSession } from '../../events/session.js';
-import { runHookConfigDone, runHookConfigSetup } from '../../integrations/index.js';
+import { runHookConfigDone, runHookConfigSetup } from '../../integrations/hooks.js';
 import { resolveConfig } from '../config/config.js';
 import { createNodeLogger } from '../config/logging.js';
 import { createSettings } from '../config/settings.js';

packages/astro/src/core/sync/index.ts

@@ -9,7 +9,7 @@ import { createContentTypesGenerator } from '../../content/index.js';
 import { globalContentConfigObserver } from '../../content/utils.js';
 import { telemetry } from '../../events/index.js';
 import { eventCliSession } from '../../events/session.js';
-import { runHookConfigSetup } from '../../integrations/index.js';
+import { runHookConfigSetup } from '../../integrations/hooks.js';
 import { setUpEnvTs } from '../../vite-plugin-inject-env-ts/index.js';
 import { getTimeStat } from '../build/util.js';
 import { resolveConfig } from '../config/config.js';

packages/astro/src/integrations/define-integration.ts

@@ -0,0 +1,57 @@
+import type { AstroIntegration } from "../@types/astro.js";
+import { AstroError, AstroErrorData, errorMap } from "../core/errors/index.js";
+import { z } from "../../zod.mjs";
+
+type AstroIntegrationSetupFn<Options extends z.ZodTypeAny> = (params: {
+	name: string;
+	options: z.output<Options>;
+}) => Omit<AstroIntegration, "name">;
+
+/** TODO: */
+export const defineIntegration = <
+	TOptionsSchema extends z.ZodTypeAny = z.ZodNever,
+	TSetup extends
+		AstroIntegrationSetupFn<TOptionsSchema> = AstroIntegrationSetupFn<TOptionsSchema>,
+>({
+	name,
+	optionsSchema,
+	setup,
+}: {
+	name: string;
+	optionsSchema?: TOptionsSchema;
+	setup: TSetup;
+}): ((
+	...args: [z.input<TOptionsSchema>] extends [never]
+		? []
+		: undefined extends z.input<TOptionsSchema>
+		  ? [options?: z.input<TOptionsSchema>]
+		  : [options: z.input<TOptionsSchema>]
+) => AstroIntegration & ReturnType<TSetup>) => {
+	return (...args): AstroIntegration & ReturnType<TSetup> => {
+		const parsedOptions = (optionsSchema ?? z.never().optional()).safeParse(
+			args[0],
+			{
+				errorMap,
+			},
+		);
+
+		if (!parsedOptions.success) {
+			throw new AstroError({
+				...AstroErrorData.AstroIntegrationInvalidOptions,
+				message: AstroErrorData.AstroIntegrationInvalidOptions.message(
+					name,
+					parsedOptions.error.issues.map((i) => i.message).join('\n')
+				),
+			});
+		}
+
+		const options = parsedOptions.data as z.output<TOptionsSchema>;
+
+		const integration = setup({ name, options }) as ReturnType<TSetup>;
+
+		return {
+			name,
+			...integration,
+		};
+	};
+};