Astro Adapter API

Astro está diseñado para facilitar el despliegue en cualquier proveedor de nube para renderizado on-demand, también conocido como server-side rendering (SSR). Esta capacidad la proporcionan los adapters, que son integraciones. Consulta la guía de renderizado on-demand para aprender cómo usar un adapter existente.

¿Qué es un adapter?

Un adapter es un tipo especial de integración que proporciona un entrypoint para el renderizado del servidor en tiempo de petición. Un adapter tiene acceso a la Integration API completa y hace dos cosas:

• Implementa APIs específicas del host para manejar peticiones.
• Configura el build según las convenciones del host.

Construir un adapter

Crea una integración y llama a la función setAdapter() en el hook astro:config:done. Esto te permite definir un server entrypoint y las funcionalidades soportadas por tu adapter.

El siguiente ejemplo crea un adapter con un server entrypoint y soporte estable para el output estático de Astro:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            staticOutput: 'stable'
          }
        });
      },
    },
  };
}

La función setAdapter() acepta un objeto que contiene las siguientes propiedades:

name

Type: string

Define un nombre único para tu adapter. Se usará para logging.

entrypointResolution

Type: "explicit" | "auto"
Default: "explicit"

Añadido en: astro@6.0.0

Deprecado

entrypointResolution: "explicit" está deprecado. entrypointResolution: "auto" se convertirá en el comportamiento por defecto, y único, en una futura versión major.

Consulta cómo migrar.

Especifica el método que Astro usará para resolver el server entrypoint: "auto" (recomendado) o "explicit" (por defecto, pero deprecado):

• "auto" (recomendado): Eres responsable de proporcionar un módulo válido como entrypoint usando serverEntrypoint o, si necesitas mayor personalización a nivel de Vite, usando vite.build.rollupOptions.input.
• "explicit" (deprecado): Debes proporcionar los exports requeridos por el host en el server entrypoint usando una función createExports() antes de pasarlos a setAdapter() como una lista de exports. Esto soporta adapters construidos con la versión 5 de Astro del Adapter API. Por defecto, todos los adapters recibirán este valor para permitir compatibilidad con versiones anteriores. Sin embargo, no se deben crear nuevos adapters con este valor. Los adapters existentes deberían sobrescribir este valor por defecto con "auto" tan pronto como puedan migrar a la nueva API v6.

El siguiente ejemplo define entrypointResolution y serverEntrypoint para indicar a Astro que se proporciona un entrypoint personalizado:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/custom-entrypoint.js',
        });
      },
    },
  };
}

El siguiente ejemplo define entrypointResolution y opciones de Rollup para indicar a Astro que se proporciona un entrypoint personalizado:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:setup': ({ updateConfig }) => {
        updateConfig({
          vite: {
            build: {
              rollupOptions: {
                input: '@example/my-adapter/custom-entrypoint.js'
              }
            }
          }
        })
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
        });
      },
    },
  };
}

Aprende más sobre cómo construir un server entrypoint.

serverEntrypoint

Type: string | URL

Define el entrypoint para el renderizado on-demand.

supportedAstroFeatures

Type: AstroAdapterFeatureMap

Añadido en: astro@3.0.0

Un mapa de las funcionalidades integradas de Astro soportadas por el adapter. Esto permite a Astro determinar qué funcionalidades soporta un adapter, para que se puedan proporcionar mensajes de error apropiados.

Descubre las funcionalidades de Astro disponibles que un adapter puede configurar.

adapterFeatures

Type: AstroAdapterFeatures

Añadido en: astro@3.0.0

Un objeto que especifica qué funcionalidades del adapter que cambian el output del build son soportadas por el adapter.

client

Type: { internalFetchHeaders?: Record<string, string> | () => Record<string, string>; assetQueryParams?: URLSearchParams; }

Añadido en: astro@5.15.0

Un objeto de configuración para el código del lado del cliente de Astro.

client.internalFetchHeaders

Type: Record<string, string> | () => Record<string, string>

Define los headers a inyectar en las llamadas fetch internas de Astro (ej. Actions, View Transitions, Server Islands, Prefetch). Puede ser un objeto de headers o una función que devuelva headers.

El siguiente ejemplo recupera un DEPLOY_ID de las variables de entorno y, si se proporciona, devuelve un objeto con el nombre del header como clave y el deploy id como valor:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          client: {
            internalFetchHeaders: () => {
              const deployId = process.env.DEPLOY_ID;
              return deployId ? { 'Your-Header-ID': deployId } : {};
            },
          },
        });
      },
    },
  };
}

client.assetQueryParams

Type: URLSearchParams

Define los parámetros de búsqueda a añadir a todas las URLs de assets (ej. imágenes, hojas de estilo, scripts). Esto es útil para adapters que necesitan rastrear versiones de despliegue u otros metadatos.

El siguiente ejemplo recupera un DEPLOY_ID de las variables de entorno y, si se proporciona, devuelve un objeto con un nombre de parámetro de búsqueda personalizado como clave y el deploy id como valor:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          client: {
            assetQueryParams: process.env.DEPLOY_ID
              ? new URLSearchParams({ yourParam: process.env.DEPLOY_ID })
              : undefined,
          },
        });
      },
    },
  };
}

previewEntrypoint

Type: string | URL

Añadido en: astro@1.5.0

Define la ruta o ID de un módulo en el paquete del adapter que es responsable de iniciar el servidor construido cuando se ejecuta astro preview.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          previewEntrypoint: '@example/my-adapter/preview.js',
        });
      },
    },
  };
}

Aprende más sobre cómo construir un preview entrypoint.

args

Type: any

Deprecado

Esta propiedad está deprecada y será removida en una futura versión major. Aprende cómo actualizar tu adapter con entrypointResolution: "auto".

Un valor serializable con JSON que se pasará al server entrypoint del adapter en tiempo de ejecución. Esto es útil para pasar un objeto que contenga configuración en tiempo de build (ej. rutas, secrets) a tu código del servidor en runtime.

El siguiente ejemplo define un objeto args con una propiedad que identifica dónde están ubicados los assets generados por Astro:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'explicit',
          args: {
            assets: config.build.assets
          },
          serverEntrypoint: '@example/my-adapter/server.js'
        });
      },
    },
  };
}

exports

Type: string[]

Deprecado

Esta propiedad está deprecada y será removida en una futura versión major. Aprende cómo actualizar tu adapter con entrypointResolution: "auto".

Define un array de exports nombrados para usar en conjunto con la función createExports() de tu server entrypoint.

El siguiente ejemplo asume que createExports() proporciona un export llamado handler:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ config, setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'explicit',
          exports: ['handler'],
          serverEntrypoint: '@example/my-adapter/server.js'
        });
      },
    },
  };
}

Prerenderer personalizado

Añadido en: astro@6.0.0

Los adapters pueden proporcionar un prerenderer personalizado para controlar cómo las páginas son prerenderizadas usando la función setPrerenderer() en el hook astro:build:start.

El siguiente ejemplo muestra cómo un adapter puede configurar un prerenderer personalizado:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:build:start': ({ setPrerenderer }) => {
        setPrerenderer((defaultPrerenderer) => ({
          name: 'my-prerenderer',
          async setup() {
            // Start a preview server
          },
          async getStaticPaths() {
            // Returns array of { pathname: string, route: RouteData }
            return defaultPrerenderer.getStaticPaths();
          },
          async render(request, { routeData }) {
            // request: Request, options: { routeData: RouteData }
            // Custom rendering logic, e.g. make HTTP requests to a preview server
            const response = await fetch(`http://localhost:4321${new URL(request.url).pathname}`);
            return response;
          },
          async teardown() {
            // Stop the preview server
          }
        }));
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
        });
      },
    },
  };
}

La función factory recibe el prerenderer por defecto, permitiéndote envolver o extender su comportamiento. Esto es útil cuando solo necesitas personalizar aspectos específicos del prerendering.

Construir un server entrypoint

Necesitarás crear un archivo que se ejecute durante las peticiones del lado del servidor para habilitar el renderizado on-demand con tu host particular. La adapter API de Astro intenta funcionar con cualquier tipo de host y proporciona una forma flexible de ajustarse a las APIs del host.

Puedes importar y usar createApp() para acceder a métodos que te permiten trabajar con objetos Request y Response estándar.

Este archivo debería ajustarse a lo que el host espera. Por ejemplo, algunos hosts serverless esperan que exportes una función handler():

my-adapter/server.js

import { createApp } from 'astro/app/entrypoint';

const app = createApp();

export async function handler(event, context) {
  // ...
}

Aprende más sobre los métodos y utilidades disponibles en la Referencia de la API del Server Entrypoint del Adapter.

Pasar configuración en tiempo de build

Si necesitas acceder a la configuración en tiempo de build en tu server entrypoint, puedes pasarla vía un módulo virtual. Por ejemplo, tu servidor podría necesitar identificar dónde están ubicados los assets generados por Astro.

Primero, crea y registra un Vite plugin para serializar los datos:

my-adapter.mjs

const VIRTUAL_MODULE_ID = 'virtual:@example/my-adapter:config';
const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;

function createConfigPlugin(config) {
  return {
    name: VIRTUAL_MODULE_ID,
    resolveId: {
      filter: {
        id: new RegExp(`^${VIRTUAL_MODULE_ID}$`),
      },
      handler() {
        return RESOLVED_VIRTUAL_MODULE_ID;
      },
    },
    load: {
      filter: {
        id: new RegExp(`^${RESOLVED_VIRTUAL_MODULE_ID}$`),
      },
      handler() {
        return `
          export const assets = ${JSON.stringify(config.build.assets)};
        `;
      },
    },
  };
}

export default function createIntegration() {
  let _config;
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:setup': ({ config, updateConfig }) => {
        _config = config;

        updateConfig({
          vite: {
            plugins: [createConfigPlugin(_config)]
          }
        })
      },
      'astro:config:done': ({ config, setAdapter }) => {
        _config = config;
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
        });
      },
    },
  };
}

Puedes crear tipos internos si es necesario:

virtual.d.ts

declare module 'virtual:@example/my-adapter:config' {
  export const assets: string;
}

Luego puedes importar el módulo virtual:

my-adapter/server.js

import { createApp } from 'astro/app/entrypoint';
import { assets } from 'virtual:@example/my-adapter:config';

const app = createApp();

export async function handler(event, context) {
  // ...
}

Construir un preview entrypoint

Cuando tu adapter soporta hybrid o server output, puedes proporcionar un preview entrypoint para habilitar el soporte de astro preview. El output estático no requiere un preview entrypoint.

Para registrar un preview entrypoint, haz que el export por defecto del módulo sea una función que tome los parámetros del servidor como argumento y devuelva un PreviewServer. Luego, especifica la ruta del módulo como valor para previewEntrypoint en tu adapter.

El siguiente ejemplo implementa un entrypoint que crea un preview server usando una función createServer() personalizada antes de devolverlo:

my-adapter/preview.ts

import type { CreatePreviewServer } from 'astro';
import { createServer } from './utils/server';

const createPreviewServer: CreatePreviewServer = async (config) => {
  const host = config.host ?? '0.0.0.0';
  const port = config.port ?? 4321;
  const server = createServer(host, port);

  return server;
};

export default createPreviewServer;

Funcionalidades de Astro

Las funcionalidades de Astro son una forma de que un adapter le diga a Astro si es capaz de soportar una funcionalidad, y también el nivel de soporte del adapter.

Al usar estas propiedades, Astro:

• ejecutará validación específica;
• emitirá información contextual a los logs;

Estas operaciones se ejecutan basándose en las funcionalidades soportadas o no soportadas, su nivel de soporte, la cantidad de logging deseada, y la propia configuración del usuario.

La siguiente configuración le indica a Astro que este adapter tiene soporte experimental para el servicio de imágenes integrado impulsado por Sharp:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            sharpImageService: 'experimental'
          }
        });
      },
    },
  };
}

Si se usa el servicio de imágenes Sharp, Astro registrará una advertencia y error en la terminal basándose en el soporte de tu adapter:

[@example/my-adapter] The feature is experimental and subject to issues or changes.

[@example/my-adapter] The currently selected adapter `@example/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build.

Se puede proporcionar adicionalmente un mensaje para dar más contexto al usuario:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: 'This adapter has limited support for Sharp. Certain features may not work as expected.'
            }
          }
        });
      },
    },
  };
}

Este objeto contiene las siguientes funcionalidades configurables:

staticOutput

Type: AdapterSupport

Define si el adapter es capaz de servir páginas estáticas.

hybridOutput

Type: AdapterSupport

Define si el adapter es capaz de servir sitios que incluyen una mezcla de páginas estáticas y renderizadas on-demand.

serverOutput

Type: AdapterSupport

Define si el adapter es capaz de servir páginas renderizadas on-demand.

i18nDomains

Type: AdapterSupport

Añadido en: astro@4.3.0

Define si el adapter es capaz de soportar dominios i18n.

envGetSecret

Type: AdapterSupport

Añadido en: astro@4.10.0

Define si el adapter es capaz de soportar getSecret() exportado desde astro:env/server. Cuando se habilita, esta funcionalidad permite a tu adapter recuperar secrets configurados por los usuarios en env.schema.

El siguiente ejemplo habilita la funcionalidad pasando un valor válido de AdapterSupportsKind al adapter:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            envGetSecret: 'stable'
          }
        });
      },
    },
  };
}

El módulo astro/env/setup te permite proporcionar una implementación para getSecret(). En tu server entrypoint, llama a setGetEnv() lo antes posible:

import { createApp } from 'astro/app/entrypoint';
import { setGetEnv } from "astro/env/setup"

setGetEnv((key) => process.env[key])

const app = createApp();

export async function handler(event, context) {
  // ...
}

Si el adapter soporta secrets, asegúrate de llamar a setGetEnv() antes de getSecret() cuando las variables de entorno estén vinculadas a la petición:

import { createApp } from 'astro/app/entrypoint';
import { setGetEnv } from 'astro/env/setup';

const app = createApp();

export default {
  async fetch(request: Request, env: Record<string, unknown>) {
    setGetEnv((key) => env[key]);

    return await app.render(request);
  }
}

sharpImageService

Type: AdapterSupport

Añadido en: astro@5.0.0

Define si el adapter soporta transformación de imágenes usando el servicio de imágenes Sharp integrado.

Funcionalidades del adapter

Un conjunto de funcionalidades que cambian el output de los archivos emitidos. Cuando un adapter opta por estas funcionalidades, recibirá información adicional dentro de hooks específicos y debe implementar la lógica adecuada para manejar el output diferente.

middlewareMode

Type: MiddlewareMode
Default: "classic"

Añadido en: astro@6.0.0

Determina en qué etapa del ciclo de vida de la página se ejecuta el middleware, y cómo se emite el código del middleware en el output del build.

El modo classic coincide con el comportamiento por defecto de Astro. En las páginas prerenderizadas, el middleware se ejecuta en tiempo de build, y cuando se solicita la página, el middleware no se ejecuta de nuevo. En las páginas dinámicas, el middleware se ejecuta solo en tiempo de petición. El código del middleware es parte de tu server bundle.

En modo edge, el código del middleware puede desplegarse de forma independiente al server bundle, por ejemplo, como una edge function.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            middlewareMode: 'edge'
          }
        });
      },
    },
  };
}

Luego, consume el hook astro:build:ssr, que te dará un middlewareEntryPoint, una URL al archivo físico en el sistema de archivos.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            middlewareMode: 'edge'
          }
        });
      },

      'astro:build:ssr': ({ middlewareEntryPoint }) => {
        // remember to check if this property exits, it will be `undefined` if the adapter doesn't opt in to the feature
        if (middlewareEntryPoint) {
          createEdgeMiddleware(middlewareEntryPoint)
        }
      }
    },
  };
}

function createEdgeMiddleware(middlewareEntryPoint) {
  // emit a new physical file using your bundler
}

buildOutput

Type: "static" | "server"
Default: "server"

Añadido en: astro@5.0.0

Te permite forzar una forma de output específica para el build. Esto puede ser útil para adapters que solo funcionan con un tipo de output específico. Por ejemplo, tu adapter podría esperar un sitio web estático para poder crear archivos específicos del host. Por defecto es server si no se especifica.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            buildOutput: 'static'
          }
        });
      },
    },
  };
}

staticHeaders

Type: boolean
Default: false

Añadido en: astro@6.0.0

Si el adapter proporciona o no soporte para establecer response headers para páginas estáticas. Cuando esta funcionalidad está habilitada, Astro devolverá un mapa de los Headers emitidos por las páginas estáticas. Este mapa está disponible como routeToHeaders en el hook astro:build:generated y puede usarse para generar output específico de la plataforma que controle los HTTP headers, por ejemplo, para crear un archivo _headers para plataformas que lo soportan.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            staticHeaders: true,
          },
        });
      },
      'astro:build:generated': ({ routeToHeaders }) => {
        // use `routeToHeaders` to generate a configuration file
        // for your virtual host of choice
      },
    },
  };
}

El valor de los headers puede cambiar según las funcionalidades habilitadas/usadas por la aplicación. Por ejemplo, si CSP está habilitado, el elemento <meta http-equiv="content-security-policy"> no se añade a la página estática. En su lugar, su content está disponible en el mapa routeToHeaders.

preserveBuildClientDir

Type: boolean
Default: false

Añadido en: astro@6.0.0

Cuando es true, los builds estáticos preservarán la estructura de directorios client/server en lugar de outputar directamente a outDir. Esto asegura que los builds estáticos usen build.client para assets, manteniendo consistencia con los builds de servidor.

Esto es útil para adapters que requieren una estructura de directorios específica sin importar el tipo de output del build, como al desplegar en plataformas con requisitos específicos de organización de archivos.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            preserveBuildClientDir: true,
          },
        });
      },
    },
  };
}

preserveBuildServerDir

Type: boolean
Default: false

Añadido en: astro@6.4.0

Cuando es true, los builds estáticos preservarán la estructura de directorios client/server para el output del servidor en lugar de outputar directamente a outDir. Esto asegura que los builds estáticos usen build.server para archivos del servidor, manteniendo consistencia con los builds de servidor.

Esto es útil para adapters que requieren una estructura consistente de dist/client/ y dist/server/ sin importar el tipo de output del build, como cuando un sitio estático puede contener aún server islands o image endpoints que necesitan un server entry.

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          adapterFeatures: {
            preserveBuildServerDir: true,
          },
        });
      },
    },
  };
}

Referencia de tipos del adapter

Los siguientes tipos pueden importarse desde el módulo astro:

import type {
  AdapterSupport,
  AdapterSupportsKind,
  AdapterSupportWithMessage,
  MiddlewareMode,
  CreatePreviewServer,
  PreviewServer,
  PreviewServerParams,
} from "astro";

AdapterSupport

Type: AdapterSupportsKind | AdapterSupportWithMessage

Añadido en: astro@5.0.0

Una unión de formatos válidos para describir el nivel de soporte de una funcionalidad.

AdapterSupportsKind

Type: "deprecated" | "experimental" | "limited" | "stable" | "unsupported"

Define el nivel de soporte para una funcionalidad por tu adapter:

• Usa "deprecated" cuando tu adapter depreca el soporte para una funcionalidad antes de removerla completamente en una futura versión.
• Usa "experimental" cuando tu adapter añade soporte para una funcionalidad, pero se esperan problemas o breaking changes.
• Usa "limited" cuando tu adapter solo soporta un subconjunto de la funcionalidad completa.
• Usa "stable" cuando la funcionalidad es totalmente soportada por tu adapter.
• Usa "unsupported" para advertir a los usuarios que pueden encontrar problemas de build en su proyecto, ya que esta funcionalidad no es soportada por tu adapter.

AdapterSupportWithMessage

Añadido en: astro@5.0.0

Un objeto que te permite definir un nivel de soporte para una funcionalidad y un mensaje para loguear en la consola del usuario. Este objeto contiene las siguientes propiedades:

AdapterSupportWithMessage.support

Type: Exclude<AdapterSupportsKind, “stable”>

Define el nivel de soporte para una funcionalidad por tu adapter.

AdapterSupportWithMessage.message

Type: string

Define un mensaje personalizado para loguear respecto al soporte de una funcionalidad por tu adapter.

AdapterSupportWithMessage.suppress

Type: "default" | "all"

Añadido en: astro@5.9.0

Una opción para evitar mostrar algunos o todos los mensajes logueados sobre el soporte de una funcionalidad por el adapter.

Si el mensaje de log por defecto de Astro es redundante, o confuso para el usuario en combinación con tu message personalizado message, puedes usar suppress: "default" para suprimir el mensaje por defecto y solo loguear tu mensaje:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: 'The adapter has limited support for Sharp. It will be used for images during build time, but will not work at runtime.',
              suppress: 'default' // custom message is more detailed than the default
            }
          }
        });
      },
    },
  };
}

También puedes usar suppress: "all" para suprimir todos los mensajes sobre el soporte de la funcionalidad. Esto es útil cuando estos mensajes no son útiles para los usuarios en un contexto específico, como cuando tienen un ajuste de configuración que significa que no están usando esa funcionalidad. Por ejemplo, puedes elegir evitar loguear cualquier mensaje sobre el soporte de Sharp desde tu adapter:

my-adapter.mjs

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
          supportedAstroFeatures: {
            sharpImageService: {
              support: 'limited',
              message: 'This adapter has limited support for Sharp. Certain features may not work as expected.',
              suppress: 'all'
            }
          }
        });
      },
    },
  };
}

MiddlewareMode

Type: "classic" | "edge"

Añadido en: astro@6.0.0

Una unión de formatos válidos para describir el modo en que se ejecuta el middleware.

CreatePreviewServer

Type: (params: PreviewServerParams) => PreviewServer | Promise<PreviewServer>

Describe la función que un adapter debería exportar para iniciar un preview server cuando se ejecuta astro preview.

PreviewServer

Type: { host?: string; port: number; closed(): Promise<void>; stop(): Promise<void>; }

Describe una instancia de un preview server para el adapter.

PreviewServer.host

Type: string | undefined

Define el host en el que el preview server está escuchando.

PreviewServer.port

Type: number

Define el puerto en el que el preview server está escuchando.

PreviewServer.closed()

Type: () => Promise<void>

Define una función que se resuelve cuando el preview server se ha cerrado.

PreviewServer.stop()

Type: () => Promise<void>

Define una función para detener el preview server y realizar cualquier limpieza necesaria.

PreviewServerParams

Type: object

Describe la configuración para el preview server.

PreviewServerParams.outDir

Type: URL

El directorio de output configurado para el build.

PreviewServerParams.client

Type: URL

El directorio de assets del cliente configurado para el build.

PreviewServerParams.server

Type: URL

Añadido en: astro@6.0.0

El directorio configurado para JavaScript del servidor al compilar para SSR.

PreviewServerParams.serverEntrypoint

Type: URL

El módulo de server entry compilado generado por Astro.

PreviewServerParams.host

Type: string | undefined

Especifica el host configurado en el que el server preview debería escuchar.

PreviewServerParams.port

Type: number

Define el puerto configurado en el que el server preview debería escuchar.

PreviewServerParams.base

Type: string

Especifica la ruta base configurada para desplegar.

PreviewServerParams.logger

Type: AstroIntegrationLogger

Define una instancia del logger de Astro que puede usarse para escribir logs cuando el preview server está en ejecución.

PreviewServerParams.headers

Type: OutgoingHttpHeaders | undefined

Describe los HTTP response headers configurados.

PreviewServerParams.allowedHosts

Type: string[] | true | undefined

Añadido en: astro@6.2.0

Describe los hosts permitidos configurados a los que el preview server debería responder.

PreviewServerParams.root

Type: URL

Especifica el directorio raíz configurado del proyecto.

Permitir instalación vía astro add

El comando astro add permite a los usuarios añadir fácilmente integraciones y adapters a su proyecto. Para permitir que tu adapter sea instalado con este comando, añade astro-adapter al campo keywords en tu package.json:

{
  "name": "example",
  "keywords": ["astro-adapter"],
}

Una vez que publiques tu adapter en npm, ejecutar astro add example instalará tu paquete con cualquier peer dependency especificada en tu package.json e instruirá a los usuarios para actualizar su configuración del proyecto manualmente.