Astro 통합 API

Astro 통합은 단 몇 줄의 코드만으로 프로젝트에 새로운 기능과 동작을 추가합니다.

이 참조 페이지는 자체 통합을 작성하는 모든 사람을 위한 것입니다. 프로젝트에서 통합을 사용하는 방법을 알아보려면 통합 사용 안내서를 확인하세요.

예시

공식 Astro 통합은 여러분이 자신만의 통합을 구축할 때 참조 역할을 할 수 있습니다.

렌더러: svelte, react, preact, vue, solid
라이브러리: tailwind, partytown
기능: sitemap

빠른 API 참조

interface AstroIntegration {
  name: string;
  hooks: {
    'astro:config:setup'?: (options: {
      config: AstroConfig;
      command: 'dev' | 'build' | 'preview' | 'sync';
      isRestart: boolean;
      updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
      addRenderer: (renderer: AstroRenderer) => void;
      addWatchFile: (path: URL | string) => void;
      addClientDirective: (directive: ClientDirectiveConfig) => void;
      addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
      addDevToolbarApp: (pluginEntrypoint: string) => void;
      injectScript: (stage: InjectedScriptStage, content: string) => void;
      injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void;
      createCodegenDir: () => URL;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:routes:resolved'?: (options: {
      routes: IntegrationResolvedRoute[];
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:config:done'?: (options: {
      config: AstroConfig;
      setAdapter: (adapter: AstroAdapter) => void;
      injectTypes: (injectedType: { filename: string; content: string }) => URL;
      logger: AstroIntegrationLogger;
      }) => void | Promise<void>;
    'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:build:setup'?: (options: {
      vite: vite.InlineConfig;
      pages: Map<string, PageBuildData>;
      target: 'client' | 'server';
      updateConfig: (newConfig: vite.InlineConfig) => void;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise<void>;
    'astro:build:ssr'?: (options: {
        manifest: SerializedSSRManifest;
        entryPoints: Map<IntegrationRouteData, URL>;
        logger: AstroIntegrationLogger;
    }) => void | Promise<void>;
    'astro:build:done'?: (options: {
      dir: URL;
      /** @deprecated 새로운 `astro:routes:resolved` 훅과 `assets` 맵을 사용하세요. */
      routes: IntegrationRouteData[];
      assets: Map<string, URL[]>;
      logger: AstroIntegrationLogger;
    }) => void | Promise<void>;

    // ... 통합의 모든 커스텀 훅
  };
}

훅

Astro는 통합이 Astro의 특정 수명 주기 동안 실행할 수 있도록 구현할 수 있는 훅을 제공합니다. Astro 훅는 글로벌 Astro 네임스페이스의 일부인 IntegrationHooks 인터페이스에 정의되어 있습니다.

다음 훅는 Astro에 내장되어 있습니다.

`astro:config:setup`

다음 훅: astro:config:done

동작 시기: 초기화 시, Vite 또는 Astro 구성이 해결되기 전.

사용 목적: 프로젝트 구성을 확장하기 위해 사용. 여기에는 Astro 구성 업데이트, Vite 플러그인 적용, 구성 요소 렌더러 추가, 페이지에 스크립트 삽입이 포함됩니다.

'astro:config:setup'?: (options: {
  config: AstroConfig;
  command: 'dev' | 'build' | 'preview' | 'sync';
  isRestart: boolean;
  updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
  addRenderer: (renderer: AstroRenderer) => void;
  addClientDirective: (directive: ClientDirectiveConfig) => void;
  addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
  addDevToolbarApp: (pluginEntrypoint: string) => void;
  addWatchFile: (path: URL | string) => void;
  injectScript: (stage: InjectedScriptStage, content: string) => void;
  injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void;
  createCodegenDir: () => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`config` 옵션

타입: AstroConfig

사용자가 제공한 Astro 구성의 읽기 전용 복사본입니다. 이는 다른 통합이 실행되기 전에 해결되었습니다. 모든 통합이 구성 업데이트를 완료한 후 구성 복사본이 필요한 경우 astro:config:done 훅을 참조하세요.

`command` 옵션

타입: 'dev' | 'build' | 'preview' | 'sync'

dev - 프로젝트는 astro dev로 실행됩니다.
build - 프로젝트는 astro build로 실행됩니다.
preview - 프로젝트는 astro preview로 실행됩니다.
sync - 프로젝트는 astro sync로 실행됩니다.

`isRestart` 옵션

타입: boolean

개발 서버가 시작되면 false, 다시 로드가 트리거되면 true입니다. 이 함수가 두 번 이상 호출되는 경우를 감지하는 데 유용합니다.

`updateConfig` 옵션

타입: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;

사용자가 제공한 Astro 구성을 업데이트하는 콜백 함수입니다. 여러분이 제공하는 모든 구성은 사용자 구성 + 기타 통합 구성 업데이트와 병합되므로 키를 자유롭게 생략할 수 있습니다!

예를 들어, 사용자 프로젝트에 Vite 플러그인을 제공해야 한다고 가정해 보겠습니다.

import bananaCSS from '@vitejs/official-banana-css-plugin';

export default {
  name: 'banana-css-integration',
  hooks: {
    'astro:config:setup': ({ updateConfig }) => {
      updateConfig({
        vite: {
          plugins: [bananaCSS()],
        },
      });
    },
  },
};

`addRenderer` 옵션

타입: (renderer: AstroRenderer ) => void;

예: svelte, react, preact, vue, solid

컴포넌트 프레임워크 렌더러 (예: React, Vue, Svelte 등)를 추가하는 콜백 함수입니다. 고급 옵션을 보려면 위 예시와 타입 정의를 찾아볼 수 있지만, 알아야 할 두 가지 주요 옵션은 다음과 같습니다.

clientEntrypoint - 컴포넌트가 사용될 때마다 클라이언트에서 실행되는 파일의 경로입니다. 이는 주로 JS를 사용하여 컴포넌트를 렌더링하거나 수화하는 데 사용됩니다.
serverEntrypoint - 컴포넌트가 사용될 때마다, 서버 측 요청 또는 정적 빌드 중에 실행되는 파일의 경로입니다. 이는 해당되는 경우 수화를 위한 훅을 사용하여 컴포넌트를 정적 마크업으로 렌더링해야 합니다. React의 renderToString 콜백이 전형적인 예시입니다.

Added in: astro@5.0.0

clientEntrypoint와 serverEntrypoint 함수는 URL을 매개변수로 받습니다.

`addWatchFile` 옵션

타입: URL | string

통합이 Vite가 감시하지 않거나, 전체 개발 서버를 다시 시작해야 적용되는 일부 구성 파일에 의존하는 경우 addWatchFile을 사용하여 추가하세요. 해당 파일이 변경될 때마다 Astro 개발 서버가 다시 로드됩니다 (isRestart를 사용하여 다시 로드가 발생하는 시기를 확인할 수 있습니다).

사용 예시:

// 절대 경로여야 합니다!
addWatchFile('/home/user/.../my-config.json');
addWatchFile(new URL('./tailwind.config.js', config.root));

`addClientDirective` 옵션

Added in: astro@2.6.0

타입: (directive: ClientDirectiveConfig ) => void;

.astro 파일에 사용할 맞춤 클라이언트 지시어를 추가합니다.

지시어의 엔트리포인트는 esbuild를 통해서만 번들로 제공되며 컴포넌트 수화 속도를 늦추지 않도록 작게 유지해야 합니다.

사용 예:

import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js';

// https://astro.build/config
export default defineConfig({
  integrations: [clickDirective()],
});

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: 'client:click',
  hooks: {
    'astro:config:setup': ({ addClientDirective }) => {
      addClientDirective({
        name: 'click',
        entrypoint: './astro-click-directive/click.js',
      });
    },
  },
});

/**
 * 창을 처음 클릭하면 수화됩니다.
 * @type {import('astro').ClientDirective}
 */
export default (load, opts, el) => {
  window.addEventListener(
    'click',
    async () => {
      const hydrate = await load();
      await hydrate();
    },
    { once: true }
  );
};

라이브러리의 타입 정의 파일에 지시어 타입을 추가할 수도 있습니다.

import 'astro';
declare module 'astro' {
  interface AstroClientDirectives {
    'client:click'?: boolean;
  }
}

`addDevToolbarApp` 옵션

Added in: astro@3.4.0

타입: (pluginEntrypoint: string) => void;

사용자 정의 개발 툴바 앱을 추가합니다.

사용 예:

import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js';

// https://astro.build/config
export default defineConfig({
  integrations: [devToolbarIntegration()],
});

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: 'dev-toolbar-app',
  hooks: {
    'astro:config:setup': ({ addDevToolbarApp }) => {
      addDevToolbarApp('./astro-dev-toolbar-app/plugin.js');
    },
  },
});

/**
 * @type {import('astro').DevToolbarApp}
 */
export default {
  id: 'my-plugin',
  name: 'My Plugin',
  icon: '<svg>...</svg>',
  init() {
    console.log("I'm a dev toolbar app!");
  },
};

`addMiddleware` 옵션

Added in: astro@3.5.0

타입: (middleware: AstroIntegrationMiddleware ) => void;

각 요청에 대해 실행할 미들웨어를 추가합니다. 미들웨어가 포함된 entrypoint 모듈과 다른 미들웨어 이전 (pre) 또는 이후 (post)를 실행해야 하는지 지정하는 order를 사용합니다.

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: 'my-middleware-package',
  hooks: {
    'astro:config:setup': ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: '@my-package/middleware',
        order: 'pre',
      });
    },
  },
});

미들웨어는 사용자 정의 미들웨어와 마찬가지로 onRequest 함수가 포함된 패키지로 정의됩니다.

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  if (context.url.pathname === '/some-test-path') {
    return Response.json({
      ok: true,
    });
  }

  return next();
});

Added in: astro@5.0.0

이 함수는 entrypoint에 대한 URL도 매개변수로 받습니다:

/**
 * @type {() => import('astro').AstroIntegration}
 */
export default () => ({
  name: "my-middleware-package",
  hooks: {
    "astro:config:setup": ({ addMiddleware }) => {
        addMiddleware({
          entrypoint: new URL('./middleware.js', import.meta.url),
          order: 'pre'
        });
    },
  },
});

`injectRoute` 옵션

타입: ({ pattern: string; entrypoint: string; pattern?: boolean }) => void;

Astro 프로젝트에 경로를 삽입하는 콜백 함수입니다. 주입된 경로는 .astro 페이지 또는 .js 및 .ts 경로 처리기일 수 있습니다.

injectRoute는 pattern과 entrypoint가 있는 객체를 사용합니다.

pattern - 경로는 브라우저에 출력되어야 합니다 (예: /foo/bar). pattern은 동적 경로를 표시하기 위해 Astro의 파일 경로 구문을 사용할 수 있습니다 (예: /foo/[bar] 또는 /foo/[...bar]). pattern에는 파일 확장자가 필요하지 않습니다.
entrypoint - .astro 페이지 또는 pattern에 표시된 경로를 처리하는 .js/.ts 경로 처리기를 가리키는 베어 모듈 지정자입니다.
prerender - Astro가 prerender 내보내기를 감지할 수 없을 때 설정할 수 있는 불리언 값입니다.

사용 예

injectRoute({
  // 동적 경로에는 Astro의 패턴 구문을 사용하세요.
  pattern: '/subfolder/[dynamic]',
  // 로컬 경로에는 상대 경로 구문을 사용합니다.
  entrypoint: './src/dynamic-page.astro',
  // Astro가 prerender 내보내기를 감지할 수 없을 때만 사용하세요.
  prerender: false
});

다른 프로젝트에 설치되도록 설계된 통합의 경우 해당 패키지 이름을 사용하여 경로 엔트리포인트을 나타냅니다. 다음 예시에서는 대시보드 경로를 주입하는 @fancy/dashboard로 npm에 게시된 패키지를 보여줍니다.

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: '@fancy/dashboard/dashboard.astro',
});

패키지 (이 경우 @fancy/dashboard)를 npm에 게시할 때 package.json 파일에서 dashboard.astro를 내보내야 합니다.

{
  "name": "@fancy/dashboard",
  // ...
  "exports": { "./dashboard.astro": "./dashboard.astro" }
}

Added in: astro@5.0.0

이 함수는 entrypoint에 대한 URL도 매개변수로 받습니다:

injectRoute({
  pattern: '/fancy-dashboard',
  entrypoint: new URL('./dashboard.astro', import.meta.url)
});

`injectScript` 옵션

타입: (stage: InjectedScriptStage, content: string) => void;

모든 페이지에 JavaScript 콘텐츠 문자열을 삽입하는 콜백 함수입니다.

stage 는 이 스크립트 (content)를 삽입하는 방법을 나타냅니다. 일부 단계에서는 수정 없이 스크립트를 삽입할 수 있지만 다른 단계에서는 Vite의 번들링 단계 중에 최적화가 허용됩니다.

"head-inline": 모든 페이지의 <head>에 있는 스크립트 태그에 삽입됩니다. Vite에 의해 최적화되거나 해결되지 않습니다.
"before-hydration": 수화시키는 스크립트가 실행되기 전에 클라이언트 측에서 가져옵니다. Vite에 의해 최적화되고 해결됩니다.
"page": 삽입된 조각이 Vite에 의해 처리되고 페이지의 Astro 컴포넌트 내부에 정의된 다른 <script> 태그와 함께 번들로 묶인다는 점을 제외하면 head-inline과 유사합니다. 스크립트는 최종 페이지 출력에 <script type="module">과 함께 로드되고 Vite에 의해 최적화되고 해결됩니다.
"page-ssr": 모든 Astro 페이지 컴포넌트의 프런트매터에 별도의 모듈로 가져옵니다. 이 단계에서는 스크립트를 가져오기 때문에 Astro global을 사용할 수 없으며 스크립트는 import가 처음 평가될 때 한 번만 실행됩니다.

page-ssr 단계의 주요 용도는 Vite가 최적화하고 해결할 모든 페이지에 CSS import를 삽입하는 것입니다.
```
injectScript('page-ssr', 'import "global-styles.css";');
```

`createCodegenDir`

타입: () => URL;

Added in: astro@5.0.0

<root>/.astro/integrations/<normalized_integration_name> 폴더를 생성하고 해당 경로를 반환하는 함수입니다.

이 함수를 사용하면 다른 통합이나 Astro와의 충돌을 피하면서 전용 폴더를 가질 수 있습니다. 이 디렉터리는 이 함수를 호출하여 생성되므로 직접 파일을 쓰는 것이 안전합니다:

import { writeFileSync } from 'node:fs'

const integration = {
    name: 'my-integration',
    hooks: {
        'astro:config:setup': ({ createCodegenDir }) => {
            const codegenDir = createCodegenDir()
            writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8')
        }
    }
}

`astro:routes:resolved`

Added in: astro@5.0.0

이전 훅: astro:config:setup

다음 훅: astro:config:done

동작 시기: astro dev 명령 실행 시. 파일 기반 라우트가 변경될 때도(추가/제거/업데이트) 실행됩니다.

사용 목적: 라우트와 해당 메타데이터에 접근하기 위해

'astro:routes:resolved'?: (options: {
  routes: IntegrationResolvedRoute[];
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`routes` 옵션

타입: IntegrationResolvedRoute[]

모든 라우트와 관련 메타데이터의 목록입니다.

사용 예시:

const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': ({ routes }) => {
                const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern)

                console.log(projectRoutes)
            },
        }
    }
}

`IntegrationResolvedRoute` 타입 참조

interface IntegrationResolvedRoute {
  /**
   * 현재 라우트의 **패턴**입니다. 예시:
   * - `src/pages/index.astro`는 `/`의 패턴을 가집니다.
   * - `src/pages/blog/[...slug].astro`는 `/blog/[...slug]`의 패턴을 가집니다.
   * - `src/pages/site/[blog]/[...slug].astro`는 `/site/[blog]/[...slug]`의 패턴을 가집니다.
   */
  pattern: RouteData['route'];

  /**
   *
   * URL을 요청된 라우트와 대조하기 위해 사용되는 정규표현식입니다.
   * 예: "[fruit]/about.astro"는 다음 패턴을 생성합니다: /^\/([^/]+?)\/about\/?$/
   * pattern.test("banana/about")는 "true" 입니다.
   *
   * ## 예시
   *
   * ```js
   * if (route.pattern.test('/blog')) {
   *  // 작업 수행
   * }
   * ```
   */
  patternRegex: RouteData['pattern'];

  /**
   *  소스 컴포넌트 URL
   */
  entrypoint: RouteData['component'];

  /**
   * 해당 라우트의 사전 렌더링 여부
   */
  isPrerendered: RouteData['prerender'];

  /**
   * 리디렉션할 {@link IntegrationResolvedRoute}입니다. `IntegrationResolvedRoute.type`이 `redirect`일 때 존재합니다.
   */
  redirectRoute?: IntegrationResolvedRoute;

  /**
   * @param {any} data 라우트의 선택적 매개변수입니다
   *
   * @description
   * 매개변수 목록을 받아서 라우트 패턴과 보간한 다음, 해당 라우트의 경로명을 반환하는 함수입니다.
   *
   * ## 예시
   *
   * `/blog/[...id].astro`와 같은 라우트의 경우, `generate` 함수는 다음과 같은 것을 반환합니다:
   *
   * ```js
   * console.log(generate({ id: 'presentation' })) // `/blog/presentation`가 기록됩니다.
   * ```
   */
  generate: (data?: any) => string;

  /**
   * 동적 및 스프레드 라우트 매개변수
   * 예시: "/pages/[lang]/[...slug].astro"는 ['lang', '...slug'] 매개변수를 출력합니다.
   */
  params: string[];

  /**
   * 이 라우트가 제공될 출력 URL 경로명
   * 참고: [dynamic] 및 [...spread] 라우트의 경우 undefined가 됩니다
   */
  pathname?: string;

  /**
   * "params" 필드와 유사하지만 더 많은 관련 메타데이터를 포함합니다. 예를 들어, `/site/[blog]/[...slug].astro`의 세그먼트들은 다음과 같습니다:
   *
   * 1. `{ content: 'site', dynamic: false, spread: false }`
   * 2. `{ content: 'blog', dynamic: true, spread: false }`
   * 3. `{ content: '...slug', dynamic: true, spread: true }`
   */
  segments: RoutePart[][];

  /**
   *
   * 라우트의 타입입니다. 다음 중 하나일 수 있습니다:
   * - `page`: 파일 시스템에 존재하는 라우트로, 일반적으로 Astro 컴포넌트입니다
   * - `endpoint`: 파일 시스템에 존재하는 라우트로, 일반적으로 엔드포인트 메서드를 노출하는 JS 파일입니다
   * - `redirect`: 파일 시스템에 존재하는 다른 라우트를 가리키는 라우트입니다
   * - `fallback`: 미들웨어 또는 다른 방식으로 처리되어야 하는, 파일 시스템에 존재하지 않는 라우트입니다
   */
  type: RouteType;

  /**
   * 리디렉션할 라우트입니다. 상태 코드와 목적지에 대한 정보를 포함합니다.
   */
  redirect?: RedirectConfig;

  /**
   * 해당 라우트가 Astro 코어, 통합 또는 사용자의 프로젝트 중 어디에서 왔는지를 나타냅니다.
   */
  origin: 'internal' | 'external' | 'project';
}

`astro:config:done`

이전 훅: astro:config:setup

다음 훅: “dev” 모드에서 실행 중인 경우 astro:server:setup 또는 프로덕션 빌드 중 astro:build:start

동작 시기: Astro 구성이 해결되고 다른 통합이 astro:config:setup 훅을 실행한 후.

사용 목적: 다른 훅에서 사용하기 위한 최종 구성을 검색하기 위해.

'astro:config:done'?: (options: {
  config: AstroConfig;
  setAdapter: (adapter: AstroAdapter) => void;
  injectTypes: (injectedType: { filename: string; content: string }) => URL;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`config` 옵션

타입: AstroConfig

사용자 제공 Astro 구성의 읽기 전용 복사본입니다. 이 문제는 다른 통합이 실행된 후 해결됩니다.

`setAdapter` 옵션

타입: (adapter: AstroAdapter) => void;

통합을 어댑터로 만듭니다. 자세한 내용은 어댑터 API에서 확인하세요.

`injectTypes` 옵션

Added in: astro@4.14.0

타입: (injectedType: { filename: string; content: string }) => URL

새 *.d.ts 파일을 추가하여 사용자 프로젝트에 타입을 삽입할 수 있습니다.

filename 속성은 /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts에 파일을 생성하는 데 사용되며, ".d.ts"로 끝나야 합니다.

content 속성은 파일 본문을 생성하며 유효한 TypeScript여야 합니다.

또한 injectTypes()는 정규화된 경로에 대한 URL을 반환하므로 나중에 해당 내용을 덮어쓰거나 원하는 방식으로 조작할 수 있습니다.

const path = injectTypes({
  filename: "types.d.ts",
  content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL

`astro:server:setup`

이전 훅: astro:config:done

다음 훅: astro:server:start

동작 시기: Vite 서버가 “dev” 모드에서 생성된 직후, listen() 이벤트가 시작되기 전입니다. 자세한 내용은 Vite의 createServer API를 참조하세요.

사용 목적: Vite 서버 옵션과 미들웨어를 업데이트하거나, 콘텐츠 레이어 새로고침 지원을 활성화하기 위해

'astro:server:setup'?: (options: {
  server: vite.ViteDevServer;
  refreshContent: (options: {
    loaders?: Array<string>;
    context?: Record<string, any>;
  }) => Promise<void>;
}) => void | Promise<void>;

`server` 옵션

타입: ViteDevServer

”dev” 모드에서 사용되는 Vite 서버의 변경 가능한 인스턴스입니다. 예를 들어, 이는 Partytown 서버를 미들웨어로 주입하기 위해 Partytown 통합에서 사용됩니다.

export default {
  name: 'partytown',
  hooks: {
    'astro:server:setup': ({ server }) => {
      server.middlewares.use(function middleware(req, res, next) {
        // 요청 처리
      });
    },
  },
};

`refreshContent` 옵션

타입: (options: { loaders?: Array<string>; context?: Record<string, any>; }) => Promise<void>

Added in: astro@5.0.0

통합이 astro dev 동안 콘텐츠 레이어 업데이트를 트리거하기 위한 함수입니다. 예를 들어, 개발 중에 웹훅 엔드포인트를 등록하거나 변경 사항을 수신하기 위해 CMS에 소켓을 열 때 사용할 수 있습니다.

기본적으로 refreshContent는 모든 컬렉션을 새로고침합니다. 선택적으로 로더 이름의 배열인 loaders 속성을 전달할 수 있습니다. 이 속성이 제공되면 해당 로더들을 사용하는 컬렉션만 새로고침됩니다. 예를 들어, CMS 통합은 이 속성을 사용하여 자체 컬렉션만 새로고침할 수 있습니다.

로더에 context 객체도 전달할 수 있습니다. 이는 웹훅 본문이나 웹소켓의 이벤트와 같은 임의의 데이터를 전달하는 데 사용할 수 있습니다.

 {
    name: 'my-integration',
    hooks: {
        'astro:server:setup': async ({ server, refreshContent }) => {
            // 개발 서버 웹훅 엔드포인트 등록
            server.middlewares.use('/_refresh', async (req, res) => {
                if(req.method !== 'POST') {
                  res.statusCode = 405
                  res.end('Method Not Allowed');
                  return
                }
                let body = '';
                req.on('data', chunk => {
                    body += chunk.toString();
                });
                req.on('end', async () => {
                    try {
                        const webhookBody = JSON.parse(body);
                        await refreshContent({
                          context: { webhookBody },
                          loaders: ['my-loader']
                        });
                        res.writeHead(200, { 'Content-Type': 'application/json' });
                        res.end(JSON.stringify({ message: 'Content refreshed successfully' }));
                    } catch (error) {
                        res.writeHead(500, { 'Content-Type': 'application/json' });
                        res.end(JSON.stringify({ error: 'Failed to refresh content: ' + error.message }));
                    }
                });
            });
        }
    }
}

그런 다음 로더는 refreshContextData 속성을 사용하여 웹훅 본문에 접근할 수 있습니다. 자세한 내용은 refreshContextData 속성을 참조하세요.

`astro:server:start`

이전 훅: astro:server:setup

다음 훅: astro:server:done

동작 시기: 서버의 listen() 이벤트가 발생한 직후입니다.

사용 목적: 지정된 주소에서 네트워크 요청을 가로채기 위해. 미들웨어에 이 주소를 사용하려는 경우 대신 astro:server:setup 사용을 고려하세요.

'astro:server:start'?: (options: { address: AddressInfo }) => void | Promise<void>;

`address` 옵션

타입: AddressInfo

Node.js Net 모듈에서 제공하는 주소, 제품군, 포트 번호입니다.

`astro:server:done`

이전 훅: astro:server:start

동작 시기: 개발서버가 종료된 직후입니다.

사용 목적: astro:server:setup 또는 astro:server:start 훅 중에 트리거할 수 있는 클린업 이벤트를 실행하기 위해.

'astro:server:done'?: () => void | Promise<void>;

`astro:build:start`

이전 훅: astro:config:done

다음 훅: astro:build:setup

동작 시기: astro:config:done 이벤트 이후, 프로덕션 빌드가 시작되기 전.

사용 목적: 프로덕션 빌드 중에 필요한 전역 객체 또는 클라이언트를 설정하기 위해. 이는 어댑터 API에서 빌드 구성 옵션을 확장할 수도 있습니다.

'astro:build:start'?: () => void | Promise<void>;

`astro:build:setup`

이전 훅: astro:build:start

다음 훅: astro:build:ssr

동작 시기: astro:build:start 훅 뒤, 빌드 직전에 실행됩니다.

사용 목적: 이 시점에서 빌드를 위한 Vite 구성이 완전히 구성되었으므로 이를 수정할 수 있는 마지막 기회입니다. 예를 들어 일부 기본값을 덮어쓰는 데 유용할 수 있습니다. 이 훅을 사용해야 할지 astro:build:start를 사용해야 할지 확실하지 않은 경우 대신 astro:build:start를 사용하세요.

'astro:build:setup'?: (options: {
  vite: vite.InlineConfig;
  pages: Map<string, PageBuildData>;
  target: 'client' | 'server';
  updateConfig: (newConfig: vite.InlineConfig) => void;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`astro:build:generated`

이전 훅: astro:build:setup

동작 시기: 정적 프로덕션 빌드가 경로 및 자산 생성을 완료한 후.

사용 목적: 빌드 아티팩트가 정리되기 전 생성된 경로 및 자산에 액세스하기 위해. 이는 매우 드문 사용 사례입니다. 정리하기 전에 생성된 파일에 실제로 액세스해야 하는 경우가 아니면 astro:build:done을 사용하는 것이 좋습니다.

'astro:build:generated'?: (options: { dir: URL }) => void | Promise<void>;

`astro:build:ssr`

이전 훅: astro:build:setup

동작 시기: 프로덕션 SSR 빌드가 완료된 후.

사용 목적: SSR 매니페스트 및 방출된 엔트리포인트 맵에 액세스합니다. 이는 플러그인이나 통합에서 사용자 정의 SSR 빌드를 생성할 때 유용합니다.

entryPoints는 페이지 경로를 빌드 후 방출된 실제 파일에 매핑합니다.
middlewareEntryPoint는 미들웨어 파일의 파일 시스템 경로입니다.

'astro:build:ssr'?: (options: {
    manifest: SerializedSSRManifest,
    entryPoints: Map<IntegrationRouteData, URL>,
    middlewareEntryPoint: URL
}) => void | Promise<void>;

`astro:build:done`

이전 훅: astro:build:ssr

동작 시기: 프로덕션 빌드(SSG 또는 SSR)가 완료된 후.

사용 목적: 확장을 위해 생성된 경로 및 자산에 액세스하기 위해 (예: 생성된 /assets 디렉터리에 콘텐츠 복사). 생성된 자산을 변환하려는 경우 대신 Vite 플러그인 API를 탐색하고 astro:config:setup을 통해 구성하는 것이 좋습니다.

'astro:build:done'?: (options: {
  dir: URL;
  /** @deprecated 새로운 `astro:routes:resolved` 훅과 `assets` 맵을 사용하세요. */
  routes: IntegrationRouteData[];
  assets: Map<string, URL[]>;
  logger: AstroIntegrationLogger;
}) => void | Promise<void>;

`dir` 옵션

타입: URL

빌드 출력 디렉터리의 URL 경로입니다. 유효한 절대 경로 문자열이 필요한 경우 Node에 내장된 fileURLToPath 유틸리티를 사용해야 합니다.

import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

export default function myIntegration() {
  return {
    hooks: {
      'astro:build:done': async ({ dir }) => {
        const metadata = await getIntegrationMetadata();
        // 유효한 크로스 플랫폼 절대 경로 문자열을 얻으려면 fileURLToPath를 사용하십시오.
        const outFile = fileURLToPath(new URL('./my-integration.json', dir));
        await writeFile(outFile, JSON.stringify(metadata));
      },
    },
  };
}

`routes` 옵션

타입: IntegrationRouteData[]

연관된 메타데이터와 함께 생성된 모든 경로의 목록입니다.

아래에서 전체 IntegrationRouteData 타입을 참조할 수 있지만 가장 일반적인 속성은 다음과 같습니다.

component - 프로젝트 루트를 기준으로 한 입력 파일 경로
pathname - 출력 파일 URL ([dynamic] 및 [...spread] 매개변수를 사용하는 경로에 대해서는 undefined)

`IntegrationRouteData` 타입 참조

interface IntegrationRouteData {
  /**
   * 라우트의 타입입니다. 다음 중 하나일 수 있습니다:
   *
   * - `page`: 파일 시스템에 존재하는 라우트로, 일반적으로 Astro 컴포넌트입니다
   * - `endpoint`: 파일 시스템에 존재하는 라우트로, 일반적으로 엔드포인트 메서드를 노출하는 JS 파일입니다
   * - `redirect`: 파일 시스템에 존재하는 다른 라우트를 가리키는 라우트입니다
   * - `fallback`: 파일 시스템에 존재하지 않고 미들웨어나 다른 방식으로 처리되어야 하는 라우트입니다
   */
  type: 'page' | 'endpoint' | 'redirect' | 'fallback';
  /** 소스 컴포넌트 URL */
  component: string;
  /**
   * 이 경로가 제공될 출력 URL 경로 이름
   * 참고: [dynamic] 및 [...spread] 경로에 대해서는 undefined.
   */
  pathname?: string;
  /**
   * 요청된 경로와 입력 URL을 일치시키는 데 사용되는 정규식
   * 예시: "[fruit]/about.astro"는 /^\/([^/]+?)\/about\/?$/ 패턴을 생성합니다.
   * 여기서 pattern.test("banana/about")은 "true"입니다.
   */
  pattern: RegExp;
  /**
   * 동적 및 스프레드 경로 매개변수
   * 예시: "/pages/[lang]/[..slug].astro"는 매개변수 ['lang', '...slug']를 출력합니다.
   */
  params: string[];
  /**
   * "params" 필드와 유사하지만 더 많은 관련 메타데이터가 있음
   * 예시: "/pages/[lang]/index.astro"는 다음 세그먼트를 출력합니다.
   * [[ { content: 'lang', dynamic: true, spread: false } ]]
   */
  segments: { content: string; dynamic: boolean; spread: boolean }[][];
  /**
   * A function that accepts a list of params, interpolates them with the route pattern, and returns the path name of the route.
   *
   * ## Example
   *
   * `/blog/[...id].astro`와 같은 라우트의 경우, `generate` 함수는 다음과 같이 반환합니다:
   *
   * ```js
   * console.log(generate({ id: 'presentation' })) // will log `/blog/presentation`
   * ```
   * 이는 일반적으로 내부용이므로 주의해서 호출하세요!
   */
  generate: (data?: any) => string;
  /**
   * 해당 라우트의 사전 렌더링 여부입니다.
   */
  prerender: boolean;
  /**
   * 이 라우트에 의해 생성된 실제 파일들의 경로입니다. 라우트가 미리 렌더링 **되지 않은** 경우, 값은 `undefined` 또는 빈 배열입니다.
   */
  distURL?: URL[];
  /**
   * 리디렉션할 라우트입니다. 상태 코드와 목적지에 대한 정보를 포함합니다.
   */
  redirect?: RedirectConfig;
  /**
   * `RouteData.type`이 `redirect`일 때 존재하는 리디렉션할 `IntegrationRouteData`입니다.
   */
  redirectRoute?: IntegrationRouteData;
}

`assets` 옵션

Added in: astro@5.0.0

타입: Map<string, URL[]>

출력 파일 경로의 URL들을 IntegrationResolvedRoute의 pattern 속성으로 그룹화하여 포함합니다.

`pages` 옵션

타입: { pathname: string }[]

생성된 모든 페이지의 목록입니다. 하나의 속성을 갖는 객체입니다.

pathname - 페이지의 최종 경로.

`astro:route:setup`

Added in: astro@4.14.0

동작 시기: astro dev에서 경로가 요청될 때마다. astro build에서 경로 파일을 번들링하고 변환하는 동안.

사용 목적: 빌드 시 또는 요청 시 경로에 대한 옵션을 설정하기 위해. 예: 요청 시 서버 렌더링 활성화

'astro:route:setup'?: (options: { route: RouteOptions }) => void | Promise<void>;

`route` 옵션

타입: RouteOptions

경로를 식별하는 component 속성과 생성된 경로를 구성할 수 있는 추가 값인 prerender가 있는 객체입니다.

component 속성은 프로젝트 루트를 기준으로 한 읽기 전용 문자열 경로입니다. 예: "src/pages/blog/[slug].astro".

`route.prerender`

타입: boolean
기본값: undefined

Added in: astro@4.14.0

prerender 속성은 경로에 대한 요청 시 서버 렌더링을 구성하는 데 사용됩니다. 경로 파일에 명시적인 export const prerender 값이 포함되어 있으면 undefined 대신 해당 값이 기본값으로 사용됩니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  integrations: [setPrerender()],
});

function setPrerender() {
  return {
    name: 'set-prerender',
    hooks: {
      'astro:route:setup': ({ route }) => {
        if (route.component.endsWith('/blog/[slug].astro')) {
          route.prerender = true;
        }
      },
    },
  };
}

모든 훅을 실행한 후 최종 값이 undefined인 경우, 경로는 output 옵션에 따라 프리렌더의 기본값으로 돌아갑니다: static 모드에서는 사전 렌더링되며, server 모드에서는 요청 시 렌더링됩니다.

커스텀 훅

global augmentation을 통해 IntegrationHooks 인터페이스를 확장하여 커스텀 훅을 통합에 추가할 수 있습니다.

declare global {
  namespace Astro {
    export interface IntegrationHook {
      'your:hook': (params: YourHookParameters) => Promise<void>
    }
  }
}

향후 내장 훅에 astro: 접두사를 사용할 수 있습니다. 커스텀 훅의 이름을 지정할 때는 다른 접두사를 선택하세요.

`HookParameters`

훅의 이름을 HookParameters 유틸리티 타입에 전달하여 훅 인수의 타입을 가져올 수 있습니다. 다음 예시에서는 함수의 options 인수의 타입이 astro:config:setup 훅의 매개변수와 일치하도록 설정되었습니다:

import type { HookParameters } from 'astro';

function mySetup(options: HookParameters<'astro:config:setup'>) {
  options.updateConfig({ /* ... */ });
}

`astro add`로 설치 허용

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

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

npm에 통합을 게시한 후 astro add example을 실행하면 package.json 파일에 지정된 피어 종속성과 함께 패키지가 설치됩니다. 그러면 다음과 같이 사용자의 astro.config에 통합이 적용됩니다.

import { defineConfig } from 'astro/config';
 import example from 'example';

export default defineConfig({
  integrations: [example()],
})

`AstroIntegrationLogger`

로그를 작성하는 데 유용한 Astro 로거의 인스턴스입니다. 이 로거는 CLI를 통해 구성된 것과 동일한 로그 수준을 사용합니다.

터미널에서 쓸 수 있는 메서드는 다음과 같습니다.

logger.info("Message");
logger.warn("Message");
logger.error("Message");
logger.debug("Message");

모든 메시지 앞에는 동일한 통합 값을 갖는 라벨이 추가됩니다.

import type { AstroIntegration } from 'astro';
export function formatIntegration(): AstroIntegration {
  return {
    name: 'astro-format',
    hooks: {
      'astro:build:done': ({ logger }) => {
        // 작업을 수행합니다.
        logger.info('Integration ready.');
      },
    },
  };
}

위 예시에서는 제공된 info 메시지를 포함하는 메시지를 기록합니다.

[astro-format] Integration ready.

다른 라벨을 사용하여 일부 메시지를 기록하려면 .fork 메서드를 사용하여 기본 name에 대한 대안을 지정하세요.

import type { AstroIntegration } from 'astro';
export function formatIntegration(): AstroIntegration {
  return {
    name: 'astro-format',
    hooks: {
      'astro:config:done': ({ logger }) => {
        // 작업을 수행합니다.
        logger.info('Integration ready.');
      },
      'astro:build:done': ({ logger }) => {
        const buildLogger = logger.fork('astro-format/build');
        // 작업을 수행합니다.
        buildLogger.info('Build finished.');
      },
    },
  };
}

위 예시에서는 기본적으로 [astro-format]을 사용하고 지정된 경우 [astro-format/build]를 사용하여 로그를 생성합니다.

[astro-format] Integration ready.
[astro-format/build] Build finished.

통합 순서

모든 통합은 구성된 순서대로 실행됩니다. 예를 들어, 사용자의 astro.config.* 파일에 있는 [react(), svelte()] 배열의 경우 react는 svelte보다 먼저 실행됩니다.

통합은 어떤 순서로든 이상적으로 실행되어야 합니다. 이것이 가능하지 않은 경우 통합이 사용자의 integrations 구성 배열에서 첫 번째 또는 마지막에 와야 한다는 점을 문서화하는 것이 좋습니다.

통합을 프리셋으로 결합

통합은 여러 개의 소규모 통합 모음으로 작성될 수도 있습니다. 이러한 컬렉션을 프리셋이라고 부릅니다. 단일 통합 객체를 반환하는 팩토리 함수를 만드는 대신, 프리셋은 통합 개체의 배열 을 반환합니다. 이는 여러 통합에서 복잡한 기능을 구축하는 데 유용합니다.

integrations: [
  // 예: examplePreset()이 [integrationOne, IntegrationTwo, ...etc]를 반환
  examplePreset(),
];

커뮤니티 리소스

나만의 Astro 통합 구축 - FreeCodeCamp의 Emmanuel Ohans
Astro 통합 템플릿 - Florian Lefebvre의 GitHub

기여하기

커뮤니티

Astro 통합 API

예시

빠른 API 참조

훅

astro:config:setup

config 옵션

command 옵션

isRestart 옵션

updateConfig 옵션

addRenderer 옵션

addWatchFile 옵션

addClientDirective 옵션

addDevToolbarApp 옵션

addMiddleware 옵션

injectRoute 옵션

사용 예

injectScript 옵션

createCodegenDir

astro:routes:resolved

routes 옵션

IntegrationResolvedRoute 타입 참조

astro:config:done

config 옵션

setAdapter 옵션

injectTypes 옵션

astro:server:setup

server 옵션

refreshContent 옵션

astro:server:start

address 옵션

astro:server:done

astro:build:start

astro:build:setup

astro:build:generated

astro:build:ssr

astro:build:done

dir 옵션

routes 옵션

IntegrationRouteData 타입 참조

assets 옵션

pages 옵션

astro:route:setup

route 옵션

route.prerender

커스텀 훅

HookParameters

astro add로 설치 허용

AstroIntegrationLogger

통합 순서

통합을 프리셋으로 결합

커뮤니티 리소스

`astro:config:setup`

`config` 옵션

`command` 옵션

`isRestart` 옵션

`updateConfig` 옵션

`addRenderer` 옵션

`addWatchFile` 옵션

`addClientDirective` 옵션

`addDevToolbarApp` 옵션

`addMiddleware` 옵션

`injectRoute` 옵션

`injectScript` 옵션

`createCodegenDir`

`astro:routes:resolved`

`routes` 옵션

`IntegrationResolvedRoute` 타입 참조

`astro:config:done`

`config` 옵션

`setAdapter` 옵션

`injectTypes` 옵션

`astro:server:setup`

`server` 옵션

`refreshContent` 옵션

`astro:server:start`

`address` 옵션

`astro:server:done`

`astro:build:start`

`astro:build:setup`

`astro:build:generated`

`astro:build:ssr`

`astro:build:done`

`dir` 옵션

`routes` 옵션

`IntegrationRouteData` 타입 참조

`assets` 옵션

`pages` 옵션

`astro:route:setup`

`route` 옵션

`route.prerender`

`HookParameters`

`astro add`로 설치 허용

`AstroIntegrationLogger`