benchmark

Add the new property to the AstroUserConfig interface. Include JSDoc documentation with @docs annotation following the existing pattern for properties like `prefetch` or `image`.

Pattern: See how the `prefetch` property is defined in AstroUserConfig with its JSDoc @docs block including name, type, default, version, and description fields.

Add Zod validation for the new option in the AstroConfigSchema. Define the type, default value, and any transforms.

Pattern: See how `prefetch` is validated with z.object().optional() and given a default value via .transform() in the same schema file.

If the option requires special resolution logic beyond Zod defaults, add resolution logic here. Most simple options only need the schema change.

Pattern: See how image config or output config is resolved with special handling after Zod parsing.

If the new option can produce user-facing errors, add a new error definition with a unique code, message template, and hint.

Pattern: See how ConfigNotFound or ConfigLegacyKey errors are defined with title, code, message function, and hint.

Add a new case to the command dispatcher switch statement that routes to your new command handler.

Pattern: See how the 'dev', 'build', 'preview', 'sync', 'check', and 'add' commands are dispatched in the switch statement, each calling a dedicated function.

Create the command handler function in the same file or a new dedicated file under packages/astro/src/cli/. The handler should accept parsed flags and the resolved config.

Pattern: See how the 'check' command is implemented: it has its own handler function that receives telemetry, flags, and resolves config before executing.

If the command needs new types (e.g., new flags or options), add them to the appropriate interface in the types file.

Pattern: See how CLIFlags interface is defined with properties for each CLI flag.

Add any command-specific error definitions if the command can fail in user-facing ways.

Pattern: See how existing errors like UnknownCLIError are defined with code, title, and message.

Study the existing main Vite plugin structure to understand how plugins export a function returning a Vite Plugin object with name, transform, resolveId, load, and configureServer hooks.

Pattern: See how packages/astro/src/vite-plugin-astro/index.ts exports a default function that returns a Vite plugin object with hooks like transform(), resolveId(), and handleHotUpdate().

Create a new directory and index.ts file following the naming convention packages/astro/src/vite-plugin-{name}/index.ts. Export a function that accepts AstroSettings and returns a Vite Plugin object.

Pattern: See how packages/astro/src/vite-plugin-astro-server/index.ts exports a function taking (settings, logging) and returns { name: 'astro:server', configureServer() {...} }.

Register your new plugin in the createVite() function by adding it to the plugins array. This is where all Astro Vite plugins are assembled.

Pattern: See how existing plugins like astroScriptsPlugin(), astroPostprocessVitePlugin(), and astroContentVirtualModPlugin() are added to the plugins array in createVite().

If your plugin needs configuration options, add them to AstroUserConfig and any relevant internal types.

Pattern: See how image-related types are defined for the image optimization Vite plugin.

Add a new error definition object to the appropriate section (Astro, CSS, Markdown, Content, etc.). Each error needs a unique numeric code, a title string, a message function that accepts context parameters, and an optional hint.

Pattern: See how UnknownCompilerError is defined: { code: 1000, title: 'Unknown compiler error.', message: 'Unknown compiler error.', hint: 'This is almost always a problem with the Astro compiler...' }. For dynamic messages, see InvalidGetStaticPathParam which uses message: (paramType) => `...${paramType}...`.

If you need a new error class (not just a new error code), extend AstroError or AstroUserError. Most new errors only need a new entry in errors-data.ts and can use the existing AstroError class.

Pattern: See how AstroError extends Error with properties for code, title, hint, and frame. See how CompilerError extends AstroError for compiler-specific errors.

Ensure your new error is exported from the errors barrel file so it can be imported elsewhere.

Pattern: See how this file re-exports from errors-data.ts, errors.ts, and utils.ts.

If the error needs special formatting in the dev overlay (e.g., code frames, custom rendering), add handling here.

Pattern: See how getErrorDataByCode() maps error codes to their data and how errors are formatted for the dev overlay.

Review the AstroIntegration interface to understand the hooks available: 'astro:config:setup', 'astro:config:done', 'astro:server:setup', 'astro:server:start', 'astro:build:start', 'astro:build:setup', 'astro:build:generated', 'astro:build:ssr', 'astro:build:done'.

Pattern: See the AstroIntegration interface definition which specifies the name property and hooks object with typed parameters for each hook.

Create a new package directory under packages/integrations/ (or packages/ for major integrations). Create package.json, tsconfig.json, and src/index.ts. The index.ts should export a default function that returns an AstroIntegration object.

Pattern: See how packages/astro/src/assets/index.ts or any existing integration package exports a function returning { name: 'astro:assets', hooks: { 'astro:config:setup': ({updateConfig}) => {...} } }.

If the integration needs to be a built-in (like assets), register it in the config schema's integrations handling. For external integrations, users add them to their astro.config.mjs.

Pattern: See how built-in integrations are injected in the config resolution pipeline.

Add an example usage of the integration to demonstrate proper configuration.

Pattern: See how examples/framework-react/astro.config.mjs imports and uses the React integration: import react from '@astrojs/react'; export default defineConfig({ integrations: [react()] }).

Study an existing hydration directive to understand the pattern. Each directive exports a default function that receives an element callback and options, and decides WHEN to call the callback to hydrate the component.

Pattern: See how packages/astro/src/runtime/client/idle.ts uses requestIdleCallback to defer hydration, or how packages/astro/src/runtime/client/visible.ts uses IntersectionObserver.

Create a new file that exports a default async function matching the hydration directive signature: (cb: () => Promise<void>, opts: Record<string, string>, el: HTMLElement) => void. The function should call cb() when the hydration condition is met.

Pattern: See packages/astro/src/runtime/client/media.ts which calls cb() when a media query matches: window.matchMedia(opts.value).addEventListener('change', cb, {once: true}).

Register the new directive in the server-side hydration logic so the correct client script is injected when the directive is used on a component.

Pattern: See how existing directives like 'idle', 'load', 'visible', 'media', 'only' are mapped to their client-side script paths in the hydration module.

Add the new directive to the relevant type definitions so TypeScript recognizes client:{your-directive} as valid syntax.

Pattern: See how client:idle, client:load, client:visible, client:media, and client:only are typed in the component props interfaces.

Update the list of known directives in any error messages that enumerate valid directives (e.g., InvalidComponentArgs).

Pattern: See error messages that list valid client: directives to ensure your new one is included.