구성 가져오기 API 참조

추가된 버전: astro@5.7.0

astro:config 가상 모듈은 Astro 구성의 일부 속성들을 직렬화 가능하고 타입 안전한 버전으로 노출합니다. 구성 값의 서로 다른 하위 집합에 액세스하기 위한 두 가지 하위 모듈인 /client 및 /server가 있습니다.

모든 사용 가능한 구성 값은 astro:config/server에서 액세스할 수 있습니다. 하지만 클라이언트에서 실행되는 코드의 경우 astro:config/client에서 노출된 값만 사용할 수 있습니다. 이는 일부 데이터만 클라이언트에 제공함으로써 정보를 보호합니다.

astro:config/client에서 가져오기

가상 구성 모듈의 client 디렉터리에서 다음 도우미를 가져옵니다.

import {
  i18n,
  trailingSlash,
  base,
  build,
  site,
  compressHTML,
} from "astro:config/client";

클라이언트 측 코드에는 이 하위 모듈을 사용하세요:

src/utils.js

import { trailingSlash } from "astro:config/client";

function addForwardSlash(path) {
  if (trailingSlash === "always") {
    return path.endsWith("/") ? path : path + "/"
  } else {
    return path
  }
}

astro:config/client에서 사용할 수 있는 구성 가져오기에 대해 자세히 알아보세요:

• i18n
• trailingSlash
• base
• build.format
• site
• compressHTML

astro:config/server에서 가져오기

가상 구성 모듈의 server 디렉터리에서 다음 도우미를 가져옵니다.

import {
  i18n,
  trailingSlash,
  base,
  build,
  site,
  srcDir,
  cacheDir,
  outDir,
  publicDir,
  root,
  compressHTML,
} from "astro:config/server";

이러한 가져오기에는 astro:config/client에서 사용할 수 있는 모든 항목뿐만 아니라, 클라이언트에 노출하기에 안전하지 않은 파일 시스템 구성에 대한 민감한 정보도 포함됩니다.

서버 측 코드에는 이 하위 모듈을 사용하세요:

astro.config.mjs

import { integration } from "./integration.mjs";

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

integration.mjs

import { outDir } from "astro:config/server";
import { writeFileSync } from "node:fs";
import { fileURLToPath } from "node:url";

export default function() {
  return {
    name: "internal-integration",
    hooks: {
      "astro:build:done": () => {
        let file = new URL("result.json", outDir);
        // 데이터 생성 작업
        let data = JSON.stringify([]);
        writeFileSync(fileURLToPath(file), data, "utf-8");
      }
    }
  }
}

astro:config/server에서 사용할 수 있는 구성 가져오기에 대해 자세히 알아보세요:

• i18n
• trailingSlash
• base
• build.format
• build.client
• build.server
• site
• srcDir
• cacheDir
• outDir
• publicDir
• root
• compressHTML

astro/config에서 가져오기

일반 구성 모듈에서 다음 도우미를 가져옵니다.

import {
  defineConfig,
  envField,
  fontProviders,
  getViteConfig,
  mergeConfig,
  passthroughImageService,
  sessionDrivers,
  sharpImageService,
  validateConfig,
} from "astro/config";

defineConfig()

타입: (config: AstroUserConfig) => AstroUserConfig

지원되는 Astro 구성 파일에서 타입 안전성을 갖춘 프로젝트를 구성합니다.

envField

타입: object

추가된 버전: astro@5.0.0

환경 변수를 정의할 때 지원되는 데이터 타입을 설명합니다.

각 데이터 타입은 context ("client" 또는 "server") 및 access ("secret" 또는 "public")와 함께 변수 타입을 정의해야 합니다. 또한 default 값을 정의하고, 변수가 optional인지 여부(기본값 false)를 지정할 수 있으며, 일부 데이터 타입은 선택적 유효성 검사 메서드를 제공합니다.

Astro 프로젝트에서 타입 안전한 환경 변수를 사용하는 방법에 대해 자세히 알아보세요.

envField.string()

타입: (options: StringFieldInput) => StringField

문자열 타입의 환경 변수를 정의합니다. max, min, length, url, includes, startsWith, endsWith 속성을 사용하여 Zod로 문자열 유효성 검사를 수행할 수 있습니다.

다음 예시는 API URL을 저장하는 환경 변수의 예상 형태를 정의합니다.

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({
        context: "client",
        access: "public",
        optional: false,
        default: "",
        min: 12,
        url: true,
        includes: "astro",
        startsWith: "https",
      }),
    }
  }
})

envField.number()

타입: (options: NumberFieldInput) => NumberField

숫자 타입의 환경 변수를 정의합니다. gt, lt, min, max, int 속성을 사용하여 Zod로 숫자 유효성 검사를 수행할 수 있습니다.

다음 예시는 API 포트를 저장하는 환경 변수의 예상 형태를 정의합니다.

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_PORT: envField.number({
        context: "server",
        access: "public",
        optional: true,
        default: 4321,
        min: 2,
        int: true,
      }),
    }
  }
})

envField.boolean()

타입: (options: BooleanFieldInput) => BooleanField

불리언 타입의 환경 변수를 정의합니다.

다음 예시는 분석 활성화 여부를 저장하는 환경 변수의 예상 형태를 정의합니다.

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      ANALYTICS_ENABLED: envField.boolean({
        context: "client",
        access: "public",
        optional: true,
        default: true,
      }),
    }
  }
})

envField.enum()

타입: (options: EnumFieldInput<T>) => EnumField

허용된 values를 배열로 제공하여 열거형 타입의 환경 변수를 정의합니다.

다음 예시는 구성된 디버그 모드를 저장하는 환경 변수의 예상 형태를 정의합니다.

astro.config.mjs

import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      DEBUG_MODE: envField.enum({
        context: "server",
        access: "public",
        values: ['info', 'warnings', 'errors'], // 필수
        optional: true,
        default: 'errors',
      }),
    }
  }
})

fontProviders

타입: object

추가된 버전: astro@6.0.0

구성된 폰트를 가져오기 위해 사용되는 내장 제공자를 설명합니다.

getViteConfig()

타입: (userViteConfig: ViteUserConfig, inlineAstroConfig?: AstroInlineConfig) => ViteUserConfigFn

사용자 정의 Vite 구성 객체와 선택적 Astro 구성 객체를 병합하여 사용할 Vite 구성을 가져옵니다. 이는 테스팅을 위해 Vitest를 설정할 때 유용합니다.

mergeConfig()

프로그래밍 방식 API 참조의 mergeConfig()를 확인하세요.

passthroughImageService()

타입: () => ImageServiceConfig

no-op 이미지 서비스를 가져옵니다. 이는 어댑터가 Astro의 내장 Sharp 이미지 최적화를 지원하지 않지만 <Image /> 및 <Picture /> 컴포넌트를 사용하고 싶을 때 유용합니다.

다음 예시는 Sharp 이미지 처리를 피하기 위해 Astro 구성 파일에서 passthroughImageService()를 이미지 서비스로 정의합니다.

astro.config.mjs

import { defineConfig, passthroughImageService } from "astro/config";

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

no-op 패스스루 서비스 구성에 대해 자세히 알아보세요.

sessionDrivers

타입: object

추가된 버전: astro@5.7.0

세션 저장소에 사용되는 내장 드라이버를 설명합니다.

다음 예시는 세션을 활성화하기 위해 Redis 드라이버를 구성합니다.

astro.config.mjs

import { defineConfig, sessionDrivers } from "astro/config";

export default defineConfig({
  session: {
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
  }
})

Astro 프로젝트에서 세션을 사용하는 방법에 대해 자세히 알아보세요.

sharpImageService()

타입: (config?: SharpImageServiceConfig) => ImageServiceConfig

추가된 버전: astro@2.4.1

Astro의 이미지 자산을 처리하는 데 사용되는 Sharp 서비스를 가져옵니다. 이는 Sharp 구성 옵션을 설명하는 선택적 객체를 인자로 받습니다.

validateConfig()

프로그래밍 방식 API 참조의 validateConfig()를 확인하세요.