프로그래밍 방식의 Astro API (실험적)

Astro를 실행할 때 더 많은 제어가 필요한 경우, "astro" 패키지는 CLI 명령어를 프로그래밍 방식으로 실행할 수 있는 API를 제공합니다.

이러한 API는 실험적이며 API 시그니처가 변경될 수 있습니다. 모든 업데이트는 Astro 변경 로그에 언급될 것이며, 아래의 정보는 항상 현재의 최신 정보를 보여줄 것입니다.

`AstroInlineConfig`

AstroInlineConfig 타입은 아래의 모든 명령어 API에서 사용되며, 사용자 Astro 구성 타입을 확장합니다:

interface AstroInlineConfig extends AstroUserConfig {
  configFile?: string | false;
  mode?: string;
  logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

`configFile`

타입: string | false
기본값: undefined

Astro 구성 파일의 사용자 지정 경로입니다.

이 값이 undefined(기본값) 또는 설정되지 않은 경우, Astro는 root를 기준으로 astro.config.(js,mjs,ts,mts) 파일을 검색하여 발견되면 해당 구성 파일을 로드합니다.

상대 경로가 설정된 경우, root 옵션을 기준으로 경로를 찾습니다.

구성 파일 로드를 비활성화하려면 false로 설정하세요.

이 객체에 전달된 인라인 구성은 로드된 사용자 구성과 병합할 때 가장 높은 우선순위를 갖습니다.

`mode`

타입: string
기본값: astro dev를 실행할 때는 "development", astro build를 실행할 때는 "production"

추가된 버전: astro@5.0.0

사이트를 개발하거나 빌드할 때 사용되는 모드입니다(예: "production", "testing").

이 값은 astro build 또는 astro dev 명령어가 실행될 때 --mode 플래그를 통해 Vite에 전달되어 import.meta.env.MODE 값을 결정합니다. 또한 어떤 .env 파일이 로드될지와 그에 따른 astro:env 값을 결정합니다. 자세한 내용은 환경 변수 페이지를 참조하세요.

개발용 빌드를 출력하려면 --devOutput 플래그와 함께 astro build를 실행할 수 있습니다.

`logLevel`

타입: "debug" | "info" | "warn" | "error" | "silent"
기본값: "info"

Astro가 기록하는 메시지를 필터링하는 로깅 레벨입니다.

"debug": 상세한 디버깅 진단을 포함한 모든 것을 기록합니다.
"info": 정보성 메시지, 경고 및 오류를 기록합니다.
"warn": 경고와 오류를 기록합니다.
"error": 오류만 기록합니다.
"silent": 로깅하지 않습니다.

`dev()`

타입: (inlineConfig: AstroInlineConfig) => Promise<DevServer>

astro dev와 유사하게, Astro의 개발 서버를 실행합니다.

import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await devServer.stop();

`DevServer`

export interface DevServer {
  address: AddressInfo;
  handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
  watcher: vite.FSWatcher;
  stop(): Promise<void>;
}

`address`

타입: AddressInfo

개발 서버가 수신 대기 중인 주소입니다.

이 속성은 Node의 net.Server#address() 메서드가 반환하는 값을 포함합니다.

`handle()`

타입: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void

원시 Node HTTP 요청을 위한 핸들러입니다. 네트워크를 통해 요청을 전송하는 대신 http.IncomingMessage와 http.ServerResponse를 사용하여 handle()을 호출할 수 있습니다.

`watcher`

타입: vite.FSWatcher

Vite의 개발 서버가 노출하는 Chokidar 파일 감시자입니다.

`stop()`

타입: Promise<void>

개발 서버를 중지합니다. 이는 모든 유휴 연결을 종료하고 새로운 연결에 대한 수신을 중단합니다.

모든 대기 중인 요청이 처리되고 모든 유휴 연결이 종료되면 해결되는 Promise를 반환합니다.

`build()`

타입: (inlineConfig: AstroInlineConfig, options?: BuildOptions) => Promise<void>

astro build와 유사하게, 배포를 위해 사이트를 빌드합니다.

import { build } from "astro";

await build({
  root: "./my-project",
});

`BuildOptions`

export interface BuildOptions {
  devOutput?: boolean;
  teardownCompiler?: boolean;
}

`devOutput`

타입: boolean
기본값: false

추가된 버전: astro@5.4.0 New

astro dev에서 변환된 코드와 유사한 개발 기반 빌드를 출력합니다. 추가 디버깅 정보가 포함된 빌드 전용 문제를 테스트하는 데 유용할 수 있습니다.

`teardownCompiler`

타입: boolean
기본값: true

추가된 버전: astro@5.4.0 New

빌드 후 컴파일러 WASM 인스턴스를 해체합니다. 이렇게 하면 한 번 빌드할 때 성능을 향상시킬 수 있지만, 연속으로 여러 번 빌드할 경우 성능 저하가 발생할 수 있습니다.

동일한 실행에서 여러 프로젝트를 빌드할 때 (예: 테스트 중), 이 옵션을 비활성화하면 지속적인 메모리 사용량이 증가하는 대신 성능이 크게 향상되고 최대 메모리 사용량이 줄어들 수 있습니다.

`preview()`

타입: (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

astro preview와 유사하게, 빌드 결과물을 제공하기 위한 로컬 서버를 시작합니다.

구성에 어댑터가 설정되어 있지 않은 경우, 미리보기 서버는 빌드된 정적 파일만 제공합니다. 구성에 어댑터가 설정되어 있는 경우, 미리보기 서버는 어댑터에 의해 제공됩니다. 어댑터는 미리보기 서버를 제공할 필요가 없으므로, 선택한 어댑터에 따라 이 기능을 사용하지 못할 수 있습니다.

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await previewServer.stop();

`PreviewServer`

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

`host`

타입: string

서버가 연결을 수신 대기하는 호스트입니다.

어댑터는 이 필드를 설정하지 않을 수 있습니다. host의 값은 구현에 따라 다릅니다.

`port`

타입: number

서버가 연결을 수신 대기하는 포트입니다.

`stop()`

타입: Promise<void>

미리보기 서버를 닫고, 요청 수락을 중지하며, 유휴 연결을 끊도록 요청합니다.

반환된 Promise는 종료 요청이 전송되었을 때 해결됩니다. 이는 서버가 아직 완전히 종료되지 않았음을 의미할 수 있습니다. 서버가 완전히 종료되었는지 확인해야 하는 경우 closed() 메서드를 사용하세요.

`closed()`

타입: Promise<void>

서버가 종료되면 해결되고 서버에서 오류가 발생하면 거부되는 Promise를 반환합니다.

`sync()`

타입: (inlineConfig: AstroInlineConfig) => Promise<void>

astro sync와 유사하게, 모든 Astro 모듈에 대한 TypeScript 타입을 생성합니다.

import { sync } from "astro";

await sync({
  root: "./my-project",
});

`mergeConfig()`

타입: <T extends AstroConfig | AstroInlineConfig>(config: T, overrides: DeepPartial<T>) => T

추가된 버전: astro@5.4.0 New

astro/config에서 가져오며, 기존의 유효한 Astro 구성 위에 부분적인 Astro 구성을 병합합니다.

mergeConfig()는 Astro 구성 객체와 부분 구성 (유효한 Astro 구성 옵션의 모든 집합)을 받아 두 값을 결합한 유효한 Astro 구성을 반환하며, 이때 다음을 만족합니다.

배열은 연결됩니다. (통합 및 remark 플러그인 포함)
객체는 재귀적으로 병합됩니다.
Vite 옵션은 기본 isRoot 플래그와 함께 Vite의 mergeConfig 함수를 사용하여 병합됩니다.
함수로 제공될 수 있는 옵션은 이러한 동일한 규칙으로 두 구성의 반환 값을 재귀적으로 병합하는 새 함수로 래핑됩니다.
다른 모든 옵션은 기존 구성을 재정의합니다.

import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: 'static',
    site: 'https://example.com',
    integrations: [tailwind()],
    server: ({command}) => ({
      port: command === 'dev' ? 4321 : 1234,
    }),
    build: {
      client: './custom-client',
    },
  },
  {
    output: 'server',
    base: '/astro',
    integrations: [mdx()],
    server: ({command}) => ({
      host: command === 'dev' ? 'localhost' : 'site.localhost',
    }),
    build: {
      server: './custom-server',
    },
  }
);

// 결과는 다음과 같습니다.
{
  output: 'server',
  site: 'https://example.com',
  base: '/astro',
  integrations: [tailwind(), mdx()],
  server: ({command}) => ({
    port: command === 'dev' ? 4321 : 1234,
    host: command === 'dev' ? 'localhost' : 'site.localhost',
  }),
  build: {
    client: './custom-client',
    server: './custom-server',
  },
}

`validateConfig()`

타입: (userConfig: any, root: string, cmd: string): Promise<AstroConfig>

추가된 버전: astro@5.4.0 New

astro/config에서 가져오며, 객체가 astro.config.mjs에서 내보내져 Astro에 의해 가져온 것처럼 유효성을 검사합니다.

다음 인수를 사용합니다.

유효성을 검사할 구성
프로젝트의 루트 디렉터리
실행 중인 Astro 명령어 (build, dev, sync 등)

반환된 Promise는 제공된 Astro 명령어에 적합한 모든 기본값으로 채워진 유효성이 검사된 구성으로 확인됩니다.

import { validateConfig } from "astro/config";

const config = await validateConfig({
  integrations: [tailwind()],
}, "./my-project", "build");

// 기본값이 적용됩니다.
await rm(config.outDir, { recursive: true, force: true });

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