Astro 어댑터 API

Astro는 서버 측 렌더링(SSR)으로 알려진 요청 시 렌더링을 위해 모든 클라우드 제공업체에 쉽게 배포할 수 있도록 설계되었습니다. 이 기능은 통합으로 제공되는 어댑터 를 통해 사용할 수 있습니다. 기존 어댑터를 사용하는 방법을 알아보려면 요청 시 렌더링 가이드를 참조하세요.

어댑터란 무엇입니까?

어댑터는 요청 시 서버 렌더링을 위한 엔트리포인트 제공하는 특별한 종류의 통합입니다. 어댑터는 전체 통합 API에 접근할 수 있으며, 다음 두 가지 작업을 수행합니다.

요청 처리를 위한 호스트별 API를 구현합니다.
호스트 규칙에 따라 빌드를 구성합니다.

어댑터 만들기

통합을 만들고 astro:config:done 훅에서 setAdapter() 함수를 호출하세요. 이를 통해 서버 엔트리포인트를 정의할 수 있으며 어댑터에서 지원하는 기능도 정의할 수 있습니다.

다음은 Astro 정적 출력을 안정적으로 지원하며 서버 엔트리포인트를 포함하는 어댑터를 생성하는 예시입니다.

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'
          }
        });
      },
    },
  };
}

setAdapter() 함수는 다음 속성을 포함하는 객체를 받습니다.

`name`

타입: string

어댑터의 고유한 이름을 정의합니다. 이 이름은 로깅에 사용됩니다.

`entrypointResolution`

타입: "explicit" | "auto"
기본값: "explicit"

추가된 버전: astro@6.0.0 새로운 기능

Astro가 서버 엔트리포인트를 확인하는 방법을 지정합니다: "auto" (권장) 또는 "explicit" (기본값이지만 더 이상 사용되지 않음):

"auto" (권장): serverEntrypoint를 사용하거나, 추가 사용자 정의가 필요한 경우 Vite 수준에서 vite.build.rollupOptions.input를 사용하여 유효한 모듈을 엔트리포인트로 제공해야 합니다.
"explicit" (더 이상 사용되지 않음): 호스트가 요구하는 내보내기를 createExports() 함수를 사용하여 서버 엔트리포인트에 제공한 다음, 이를 exports 목록으로 setAdapter()에 전달해야 합니다. 이는 Astro 5 버전의 어댑터 API를 사용하여 빌드된 어댑터를 지원합니다. 기본적으로 모든 어댑터는 하위 호환성을 위해 이 값을 받게 됩니다. 그러나 이 값을 사용하여 새로운 어댑터를 만들어서는 안 됩니다. 기존 어댑터는 새 v6 API로 마이그레이션할 수 있는 즉시 이 기본값을 "auto"로 재정의해야 합니다.

다음 예시는 entrypointResolution과 serverEntrypoint를 정의하여 Astro에 사용자 정의 엔트리포인트가 제공되었음을 알립니다.

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',
        });
      },
    },
  };
}

다음 예시는 entrypointResolution과 Rollup 옵션을 정의하여 Astro에 사용자 정의 엔트리포인트가 제공되었음을 알립니다.

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',
        });
      },
    },
  };
}

서버 엔트리포인트를 만드는 방법에 대해 자세히 알아보세요.

`serverEntrypoint`

타입: string | URL

요청 시 렌더링을 위한 엔트리포인트를 정의합니다.

`supportedAstroFeatures`

타입: AstroAdapterFeatureMap

추가된 버전: astro@3.0.0

어댑터가 지원하는 Astro 내장 기능에 대한 맵입니다. 이를 통해 Astro는 어댑터가 어떤 기능을 지원하는지 파악하여 적절한 오류 메시지를 제공할 수 있습니다.

어댑터가 구성할 수 있는 사용 가능한 Astro의 기능을 알아보세요.

`adapterFeatures`

타입: AstroAdapterFeatures

추가된 버전: astro@3.0.0

빌드 출력을 변경하는 어댑터의 기능 중 어댑터가 지원하는 기능을 지정하는 객체입니다.

`client`

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

추가된 버전: astro@5.15.0

Astro의 클라이언트 측 코드를 위한 구성 객체입니다.

`client.internalFetchHeaders`

타입: Record<string, string> | () => Record<string, string>

Astro의 내부 fetch 호출(예: 액션, 뷰 전환, 서버 아일랜드, 프리페치)에 주입할 헤더를 정의합니다. 헤더 객체 또는 헤더를 반환하는 함수일 수 있습니다.

다음은 환경 변수에서 DEPLOY_ID를 검색하여 헤더 이름을 키로, 배포 ID를 값으로 하는 객체를 반환하는 예시입니다.

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`

타입: URLSearchParams

모든 자산 URL(예: 이미지, 스타일시트, 스크립트 등)에 추가할 쿼리 매개변수를 정의합니다. 이는 배포 버전 또는 기타 메타데이터를 추적해야 하는 어댑터에 유용합니다.

다음은 환경 변수에서 DEPLOY_ID를 검색하여 사용자 정의 검색 매개변수 이름을 키로, 배포 ID를 값으로 하는 객체를 반환하는 예시입니다.

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`

타입: string | URL

추가된 버전: astro@1.5.0

어댑터 패키지 내 모듈의 경로 또는 ID를 정의하며, astro preview가 실행될 때 빌드된 서버를 시작하는 역할을 합니다.

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',
        });
      },
    },
  };
}

`args`

타입: any

런타임에 어댑터의 서버 엔트리포인트로 전달될 JSON 직렬화 가능한 값입니다. 이는 빌드 타임 구성(예: 경로, 비밀)이 포함된 객체를 서버 런타임 코드로 전달하는 데 유용합니다.

다음 예시는 Astro에서 생성된 자산이 어디에 위치하는지 식별하는 속성을 가진 args 객체를 정의합니다.

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`

타입: string[]

서버 엔트리포인트의 createExports() 함수와 함께 사용할 명명된 내보내기 배열을 정의합니다.

다음 예시는 createExports()가 handler라는 내보내기를 제공한다고 가정합니다:

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'
        });
      },
    },
  };
}

사용자 정의 사전 렌더러

추가된 버전: astro@6.0.0 새로운 기능

어댑터는 astro:build:start 훅에서 setPrerenderer() 함수를 사용하여 페이지가 사전 렌더링되는 방식을 제어하는 사용자 정의 사전 렌더러를 제공할 수 있습니다.

다음 예시는 어댑터가 사용자 정의 사전 렌더러를 설정하는 방법을 보여줍니다.

export default function createIntegration() {
  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:build:start': ({ setPrerenderer }) => {
        setPrerenderer((defaultPrerenderer) => ({
          name: 'my-prerenderer',
          async setup() {
            // 미리보기 서버 시작
          },
          async getStaticPaths() {
            // { pathname: string, route: RouteData }의 배열 반환
            return defaultPrerenderer.getStaticPaths();
          },
          async render(request, { routeData }) {
            // request: Request, options: { routeData: RouteData }
            // 사용자 정의 렌더링 로직 (예: 미리보기 서버에 HTTP 요청 보내기)
            const response = await fetch(`http://localhost:4321${new URL(request.url).pathname}`);
            return response;
          },
          async teardown() {
            // 미리보기 서버 중단
          }
        }));
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
        });
      },
    },
  };
}

팩토리 함수는 기본 사전 렌더러를 받으므로, 해당 동작을 래핑하거나 확장할 수 있습니다. 이는 사전 렌더링의 특정 측면만 사용자 정의해야 할 때 유용합니다.

서버 엔트리포인트 만들기

특정 호스트에서 요청 시 렌더링을 활성화하려면 서버 측 요청 중에 실행되는 파일을 생성해야 합니다. Astro의 어댑터 API는 모든 유형의 호스트와 작동하도록 시도하며, 호스트 API에 맞게 유연하게 구성할 수 있는 방법을 제공합니다.

createApp() (EN)을 가져와 사용하여 표준 Request 및 Response 객체와 함께 작동할 수 있는 메서드에 접근할 수 있습니다.

이 파일은 호스트가 기대하는 바에 따라야 합니다. 예를 들어, 일부 서버리스 호스트는 handler() 함수를 내보내도록 기대합니다.

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

const app = createApp();

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

어댑터 서버 엔트리포인트 API 참조 (EN)에서 사용 가능한 메서드 및 유틸리티에 대해 자세히 알아보세요.

빌드 타임 구성 전달

서버 엔트리포인트에서 빌드 타임 구성에 접근해야 하는 경우, 가상 모듈을 통해 전달할 수 있습니다. 예를 들어, 서버가 Astro에 의해 생성된 자산이 어디에 위치하는지 식별해야 할 수 있습니다.

먼저, 데이터를 직렬화하기 위한 Vite 플러그인을 생성하고 등록하세요:

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',
        });
      },
    },
  };
}

필요한 경우 내부 타입을 생성할 수 있습니다:

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

그런 다음 가상 모듈을 가져올 수 있습니다:

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

const app = createApp();

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

Astro 기능

Astro 기능은 어댑터가 특정 기능을 지원할 수 있는지 여부와 지원 수준을 Astro에 알리는 방법입니다.

이러한 속성을 사용할 때 Astro는 다음을 수행합니다.

특정 유효성 검사를 실행합니다.
로그에 컨텍스트 정보를 내보냅니다.

이러한 작업은 지원되거나 지원되지 않는 기능, 지원 수준, 원하는 로깅 양, 사용자의 자체 구성을 기반으로 실행됩니다.

다음 구성은 이 어댑터가 Sharp 기반 내장 이미지 서비스에 대한 실험적 지원을 제공한다고 Astro에 알립니다.

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'
          }
        });
      },
    },
  };
}

Sharp 이미지 서비스를 사용하는 경우, Astro는 어댑터의 지원에 따라 터미널에 경고 및 오류 메시지를 기록합니다.

[@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.

사용자에게 추가적인 컨텍스트를 제공하기 위해 메시지를 추가할 수 있습니다.

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.'
            }
          }
        });
      },
    },
  };
}

이 객체에는 다음과 같은 구성 가능한 기능이 포함되어 있습니다.

`staticOutput`

타입: AdapterSupport

어댑터가 정적 페이지를 제공할 수 있는지 정의합니다.

`hybridOutput`

타입: AdapterSupport

정적 페이지와 요청 시 렌더링되는 페이지가 혼합된 사이트를 어댑터가 제공할 수 있는지 정의합니다.

`serverOutput`

타입: AdapterSupport

어댑터가 요청 시 렌더링되는 페이지를 제공할 수 있는지 정의합니다.

`i18nDomains`

타입: AdapterSupport

추가된 버전: astro@4.3.0

어댑터가 다국어 도메인을 지원할 수 있는지 정의합니다.

`envGetSecret`

타입: AdapterSupport

추가된 버전: astro@4.10.0

어댑터가 astro:env/server에서 내보낸 getSecret()을 지원할 수 있는지 정의합니다. 이 기능이 활성화되면 어댑터에서 env.schema에 구성한 비밀을 검색할 수 있습니다.

다음 예시는 유효한 AdapterSupportsKind 값을 어댑터에 전달하여 해당 기능을 활성화합니다.

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'
          }
        });
      },
    },
  };
}

astro/env/setup 모듈을 사용하면 getSecret()에 대한 구현을 제공할 수 있습니다. 서버 엔트리포인트에서 가능한 한 빨리 setGetEnv()를 호출하세요.

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) {
  // ...
}

어댑터가 비밀을 지원하며 요청과 연결된 환경 변수가 있을 때는 getSecret()을 호출하기 전에 setGetEnv()를 먼저 호출해야 합니다.

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`

타입: AdapterSupport

추가된 버전: astro@5.0.0

어댑터가 내장 Sharp 이미지 서비스를 사용하여 이미지 변환을 지원하는지 정의합니다.

어댑터 기능

생성된 파일의 출력을 변경하는 기능들의 집합입니다. 어댑터가 이러한 기능을 채택하면 특정 훅에서 추가 정보를 얻게 되며, 다양한 출력을 처리하기 위한 적절한 로직을 구현해야 합니다.

`middlewareMode`

타입: MiddlewareMode
기본값: "classic"

추가된 버전: astro@6.0.0 새로운 기능

미들웨어가 페이지 라이프사이클의 어느 단계에서 실행되는지, 그리고 미들웨어 코드가 빌드 출력에서 어떻게 방출되는지 결정합니다.

classic 모드는 Astro의 기본 동작과 일치합니다. 사전 렌더링된 페이지에서는 빌드 시점에 미들웨어가 실행되며, 페이지가 요청될 때는 미들웨어가 다시 실행되지 않습니다. 동적 페이지에서는 요청 시점에만 미들웨어가 실행됩니다. 미들웨어 코드는 서버 번들의 일부입니다.

edge 모드에서는 미들웨어 코드를 서버 번들과 독립적으로 배포할 수 있습니다(예: 엣지 함수).

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'
          }
        });
      },
    },
  };
}

그런 다음 middlewareEntryPoint와 파일 시스템 상의 물리적 파일에 대한 URL을 제공하는 astro:build:ssr 훅을 사용합니다.

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 }) => {
        // 이 속성이 존재하는지 확인하세요. 어댑터가 해당 기능을 채택하지 않은 경우 `undefined`가 됩니다.
        if (middlewareEntryPoint) {
          createEdgeMiddleware(middlewareEntryPoint)
        }
      }
    },
  };
}

function createEdgeMiddleware(middlewareEntryPoint) {
  // 번들러를 사용하여 새 물리적 파일을 생성합니다.
}

`buildOutput`

타입: "static" | "server"
기본값: "server"

추가된 버전: astro@5.0.0

빌드에 대한 특정 출력 형태를 강제할 수 있습니다. 이는 특정 출력 유형으로만 작동하는 어댑터에 유용할 수 있습니다. 예를 들어, 어댑터가 정적 웹사이트를 예상하여 호스트별 파일을 생성할 수 있도록 할 수 있습니다. 지정되지 않은 경우 기본값은 server입니다.

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`

타입: boolean
기본값: false

추가된 버전: astro@6.0.0 새로운 기능

어댑터가 정적 페이지에 대한 응답 헤더 설정을 지원하는지 여부입니다. 이 기능이 활성화되면 Astro는 정적 페이지에서 발생한 Headers의 맵을 반환합니다. 이 맵은 astro:build:generated 훅에서 routeToHeaders로 제공되며, HTTP 헤더를 제어하는 플랫폼별 출력을 생성하는 데 사용될 수 있습니다. 예를 들어, 지원되는 플랫폼을 위한 _headers 파일을 생성할 수 있습니다.

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 }) => {
        // `routeToHeaders`를 사용하여 원하는 가상 호스트의 구성 파일을 생성하세요.
      },
    },
  };
}

헤더의 값은 애플리케이션에서 활성화 및 사용되는 기능에 따라 변경될 수 있습니다. 예를 들어, CSP가 활성화된 경우, <meta http-equiv="content-security-policy"> 요소가 정적 페이지에 추가되지 않습니다. 대신, 해당 content는 routeToHeaders 맵에서 사용할 수 있습니다.

`preserveBuildClientDir`

타입: boolean
기본값: false

추가된 버전: astro@6.0.0 새로운 기능

true일 때, 정적 빌드는 outDir에 직접 출력하는 대신 client/server 디렉토리 구조를 보존합니다. 이는 정적 빌드가 자산에 build.client를 사용하도록 보장하여 서버 빌드와의 일관성을 유지합니다.

이는 빌드 출력 유형에 관계없이 특정 디렉토리 구조를 요구하는 어댑터(예: 특정 파일 구성 요구 사항이 있는 플랫폼에 배포)에 유용합니다.

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,
          },
        });
      },
    },
  };
}

어댑터 타입 참조

`AdapterSupport`

타입: AdapterSupportsKind | AdapterSupportWithMessage

추가된 버전: astro@5.0.0

기능에 대한 지원 수준을 설명하는 유효한 형식들의 합집합입니다.

`AdapterSupportsKind`

타입: "deprecated" | "experimental" | "limited" | "stable" | "unsupported"

어댑터에서 기능에 대한 지원 수준을 정의합니다.

"deprecated": 향후 버전에 완전히 제거하기 전에 기능 지원을 더 이상 사용하지 않기로 결정한 경우 사용합니다.
"experimental": 기능 지원을 추가하지만, 문제가 발생하거나 호환성이 깨지는 변경이 예상되는 경우 사용합니다.
"limited": 전체 기능의 일부만 지원하는 경우 사용합니다.
"stable": 기능이 완전히 지원되는 경우 사용합니다.
"unsupported": 어댑터에서 이 기능이 지원되지 않으므로 사용자가 프로젝트 빌드 시 문제가 발생할 수 있음을 사용자에게 경고합니다.

`AdapterSupportWithMessage`

추가된 버전: astro@5.0.0

기능에 대한 지원 수준과 사용자 콘솔에 기록될 메시지를 정의할 수 있는 객체입니다. 이 객체에는 다음 속성이 포함됩니다.

`AdapterSupportWithMessage.support`

타입: Exclude<AdapterSupportsKind, “stable”>

어댑터에서 기능에 대한 지원 수준을 정의합니다.

`AdapterSupportWithMessage.message`

타입: string

어댑터가 기능을 지원하는 것에 대해 기록할 사용자 정의 메시지를 정의합니다.

`AdapterSupportWithMessage.suppress`

타입: "default" | "all"

추가된 버전: astro@5.9.0

어댑터가 기능 지원에 대한 일부 또는 모든 로깅 메시지를 표시하지 않도록 하는 옵션입니다.

Astro의 기본 로깅 메시지가 필요하지 않거나 사용자 정의 message와 함께 사용할 때 유저에게 혼란을 줄 수 있는 경우, suppress: "default"를 사용하여 기본 메시지를 제거하고 사용자 정의 메시지만 로깅할 수 있습니다.

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' // 사용자 정의 메시지가 기본 메시지보다 자세합니다.
            }
          }
        });
      },
    },
  };
}

suppress: "all"을 사용하여 기능 지원에 관한 모든 메시지를 표시하지 않을 수도 있습니다. 이는 특정 컨텍스트에서 사용자에게 이러한 메시지가 도움이 되지 않는 경우(예: 해당 기능을 사용하지 않는 구성 설정이 있는 경우)에 유용합니다. 예를 들어, 어댑터에서 Sharp 지원에 관한 모든 메시지 로깅을 방지할 수 있습니다.

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`

타입: "classic" | "edge"

추가된 버전: astro@6.0.0 새로운 기능

미들웨어가 실행되는 모드를 설명하는 유효한 형식들의 유니온입니다.

`astro add`를 통한 설치 허용

astro add 명령을 사용하면 사용자가 프로젝트에 통합 및 어댑터를 쉽게 추가할 수 있습니다. 이 명령어로 어댑터를 설치할 수 있도록 하려면 package.json의 keywords 필드에 astro-adapter를 추가하세요.

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

어댑터를 npm에 게시하면 astro add example을 실행할 때 package.json에 지정된 피어 종속성과 함께 패키지를 설치하고 사용자에게 프로젝트 구성을 수동으로 업데이트하도록 안내합니다.

기여하기 커뮤니티 후원하기

Astro 어댑터 API

어댑터란 무엇입니까?

어댑터 만들기

name

entrypointResolution

serverEntrypoint

supportedAstroFeatures

adapterFeatures

client

client.internalFetchHeaders

client.assetQueryParams

previewEntrypoint

args

exports

사용자 정의 사전 렌더러

서버 엔트리포인트 만들기

빌드 타임 구성 전달

Astro 기능

staticOutput

hybridOutput

serverOutput

i18nDomains

envGetSecret

sharpImageService

어댑터 기능

middlewareMode

buildOutput

staticHeaders

preserveBuildClientDir

어댑터 타입 참조

AdapterSupport

AdapterSupportsKind

AdapterSupportWithMessage

AdapterSupportWithMessage.support

AdapterSupportWithMessage.message

AdapterSupportWithMessage.suppress

MiddlewareMode

astro add를 통한 설치 허용

`name`

`entrypointResolution`

`serverEntrypoint`

`supportedAstroFeatures`

`adapterFeatures`

`client`

`client.internalFetchHeaders`

`client.assetQueryParams`

`previewEntrypoint`

`args`

`exports`

`staticOutput`

`hybridOutput`

`serverOutput`

`i18nDomains`

`envGetSecret`

`sharpImageService`

`middlewareMode`

`buildOutput`

`staticHeaders`

`preserveBuildClientDir`

`AdapterSupport`

`AdapterSupportsKind`

`AdapterSupportWithMessage`

`AdapterSupportWithMessage.support`

`AdapterSupportWithMessage.message`

`AdapterSupportWithMessage.suppress`

`MiddlewareMode`

`astro add`를 통한 설치 허용