실험적 글꼴 API

타입: FontFamily[]

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

이 실험적인 기능을 사용하면 통합되고 완전히 사용자 정의 가능하며 타입 안전한 API를 통해 파일 시스템 및 다양한 글꼴 제공업체 (예: Google, Fontsource, Bunny)의 글꼴을 사용할 수 있습니다.

웹 글꼴은 페이지 로드 시간과 렌더링 시간 모두에서 페이지 성능에 영향을 미칠 수 있습니다. 이 API는 불필요한 글꼴 파일 다운로드와 같은 일반적인 문제를 방지하기 위한 프리로드 링크, 최적화된 대체 글꼴, 의견이 있는 기본값을 포함한 자동 웹 글꼴 최적화를 통해 사이트 성능을 유지하는 데 도움이 됩니다.

이 기능을 활성화하려면 하나 이상의 글꼴로 experimental.fonts 객체를 구성하세요.

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

export default defineConfig({
    experimental: {
        fonts: [{
            provider: fontProviders.google(),
            name: "Roboto",
            cssVariable: "--font-roboto"
        }]
    }
});

그런 다음 <head>에 <Font /> 컴포넌트와 사이트 전체 스타일링을 추가하세요.

---
import { Font } from 'astro:assets';
---

<Font cssVariable='--font-roboto' preload />

<style>
body {
    font-family: var(--font-roboto);
}
</style>

사용법

experimental.fonts는 글꼴 객체의 배열을 허용합니다. 각 글꼴에 대해 provider, 패밀리 name을 지정하고 글꼴을 참조할 cssVariable을 정의해야 합니다.
- provider: 내장된 원격 제공자 목록에서 선택하거나, 사용자 정의 글꼴 제공자를 직접 만들거나, 로컬 제공자를 사용하여 로컬 글꼴 파일을 등록할 수 있습니다.
- name: 제공자가 지원하는 글꼴 패밀리를 선택합니다.
- cssVariable: CSS 변수 형식의 유효한 ident여야 합니다.
다음 예시는 Google Fonts에서 “Roboto” 글꼴 패밀리를 구성합니다.
astro.config.mjs
```
import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  experimental: {
    fonts: [{
      provider: fontProviders.google(),
      name: "Roboto",
      cssVariable: "--font-roboto"
    }]
  }
});
```
대체 글꼴 패밀리 정의, 다운로드할 weights 및 styles와 같은 더 많은 구성 옵션을 사용할 수 있으며, 일부는 선택한 제공자에 따라 다릅니다.

자세한 내용은 전체 구성 참조를 확인하세요.
<Font /> 컴포넌트를 사용하여 스타일을 적용합니다. 이 컴포넌트를 가져와 페이지의 <head>에 추가해야 합니다. 글꼴의 cssVariable을 제공하는 것은 필수이며, 선택적으로 프리로드 링크를 출력할 수 있습니다.
src/components/Head.astro
```
---
import { Font } from 'astro:assets';
---

<Font cssVariable="--font-roboto" preload />
```
이는 일반적으로 공통 사이트 레이아웃에서 사용되는 Head.astro와 같은 컴포넌트에서 수행됩니다.

자세한 내용은 전체 <Font> 컴포넌트 참조를 확인하세요.

<Font /> 컴포넌트는 글꼴 선언을 포함한 CSS를 생성하므로, cssVariable을 사용하여 글꼴 패밀리를 참조할 수 있습니다.
<style> body { font-family: var(--font-roboto); } </style>
src/styles/global.css
@import 'tailwindcss'; @theme inline { --font-sans: var(--font-roboto); }
tailwind.config.mjs
/** @type {import("tailwindcss").Config} */ export default { content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"], theme: { extend: {}, fontFamily: { sans: ["var(--font-roboto)"] } }, plugins: [] };

사용 가능한 원격 글꼴 제공자

Astro는 대부분의 unifont 제공자를 다시 내보냅니다. 다음은 기본적으로 지원되는 제공자입니다.

내장된 원격 제공자를 사용하려면 provider를 선택한 글꼴 제공자에 해당하는 값으로 구성하세요.

provider: fontProviders.adobe({ id: process.env.ADOBE_ID })

provider: fontProviders.bunny()

provider: fontProviders.fontshare()

provider: fontProviders.fontsource()

provider: fontProviders.google()

또한, google() 글꼴 제공자는 unifont Google ProviderOption에서 사용 가능한 모든 옵션들을 허용합니다.

provider: fontProviders.google({
  glyphs: {
    Roboto: ["a"]
  }
})

어떤 unifont 제공자에 대해서든 사용자 정의 Astro 글꼴 제공자를 만들 수도 있습니다.

`<Font />` 컴포넌트 참조

이 컴포넌트는 스타일 태그를 출력하며, 선택적으로 주어진 글꼴 패밀리에 대한 프리로드 링크를 출력할 수 있습니다.

반드시 페이지에서 가져와 <head>에 추가해야 합니다. 이는 일반적으로 전역적으로 사용하기 위해 공통 사이트 레이아웃에 사용되는 Head.astro와 같은 컴포넌트에서 수행되지만, 필요에 따라 개별 페이지에 추가할 수도 있습니다.

이 컴포넌트를 사용하면 어떤 페이지에 어떤 글꼴 패밀리를 사용할지, 그리고 어떤 글꼴을 미리 로드할지 제어할 수 있습니다.

cssVariable

예시 타입: "--font-roboto" | "--font-comic-sans" | ...

Astro 구성에 등록된 cssVariable입니다.

---
import { Font } from 'astro:assets';
---

<Font cssVariable="--font-roboto" />

preload

타입: boolean
기본값: false

프리로드 링크를 출력할지 여부를 결정합니다.

---
import { Font } from 'astro:assets';
---

<Font cssVariable="--font-roboto" preload />

글꼴 구성 참조

글꼴의 모든 속성은 Astro 구성에서 설정해야 합니다. 일부 속성은 원격 및 로컬 글꼴 모두에 공통적이며, 다른 속성은 선택한 글꼴 제공자에 따라 사용할 수 있습니다.

공통 속성

다음 속성은 원격 및 로컬 글꼴 모두에 사용할 수 있습니다. provider, name, cssVariable은 필수 속성입니다.

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

export default defineConfig({
  experimental: {
    fonts: [{
      provider: fontProviders.google(),
      name: "Roboto",
      cssVariable: "--font-roboto"
    }]
  }
});

provider

타입: AstroFontProvider | "local"

글꼴 파일의 출처입니다. 내장된 제공자를 사용하거나, 사용자 정의 제공자를 직접 작성하거나, 로컬 글꼴 파일을 사용하기 위해 "local"로 설정할 수 있습니다.

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

export default defineConfig({
  experimental: {
    fonts: [{
      provider: fontProviders.google(),
      name: "Roboto",
      cssVariable: "--font-roboto"
    }]
  }
});

name

타입: string

글꼴 제공자가 식별하는 글꼴 패밀리 이름입니다.

name: "Roboto"

cssVariable

타입: string

CSS 변수 형식 (즉, --로 시작)으로 사용자가 선택한 유효한 ident입니다.

cssVariable: "--font-roboto"

fallbacks

타입: string[]
기본값: ["sans-serif"]

선택한 글꼴을 사용할 수 없거나 로드 중일 때 사용할 글꼴의 배열입니다. 대체 글꼴은 나열된 순서대로 선택됩니다. 사용 가능한 첫 번째 글꼴이 사용됩니다.

fallbacks: ["CustomFont", "serif"]

대체 글꼴을 완전히 비활성화하려면 빈 배열을 구성하세요.

fallbacks: []

fallbacks 배열의 마지막 글꼴이 일반적인 글꼴 패밀리 이름인 경우, Astro는 글꼴 메트릭을 사용하여 최적화된 대체 글꼴 생성을 시도합니다. 이 최적화를 비활성화하려면 optimizedFallbacks를 false로 설정하세요.

optimizedFallbacks

타입: boolean
기본값: true

대체 글꼴을 생성할 때 Astro의 기본 최적화를 활성화할지 여부입니다. fallbacks가 생성되는 방식을 완전히 제어하기 위해 이 기본 최적화를 비활성화할 수 있습니다.

optimizedFallbacks: false

원격 글꼴 속성

원격 글꼴에 대한 추가 구성 옵션을 사용할 수 있습니다. 예를 들어 특정 글꼴 두께나 스타일만 다운로드하는 등, 글꼴 제공자로부터 로드되는 데이터를 사용자 정의하려면 이러한 옵션을 설정하세요.

내부적으로 이러한 옵션은 unifont에 의해 처리됩니다. 일부 속성은 일부 제공업체에서 지원되지 않을 수 있으며, 각 제공업체에서 다르게 처리될 수 있습니다.

weights

타입: (number | string)[]
기본값: [400]

글꼴 두께의 배열입니다. 구성에 값이 지정되지 않은 경우 불필요한 다운로드를 방지하기 위해 기본적으로 두께 400만 포함됩니다. 다른 글꼴 두께를 사용하려면 이 속성을 포함해야 합니다.

weights: [200, "400", "bold"]

연결된 글꼴이 가변 글꼴인 경우, 두께의 범위를 지정할 수 있습니다.

weights: ["100 900"]

styles

타입: ("normal" | "italic" | "oblique")[]
기본값: ["normal", "italic"]

글꼴 스타일의 배열입니다.

styles: ["normal", "oblique"]

subsets

타입: string[]
기본값: ["cyrillic-ext", "cyrillic", "greek-ext", "greek", "vietnamese", "latin-ext", "latin"]

미리 로드할 글꼴 하위 집합 목록을 정의합니다.

subsets: ["latin"]

display

타입: "auto" | "block" | "swap" | "fallback" | "optional"
기본값: "swap"

글꼴이 다운로드되어 사용할 준비가 되었을 때 표시되는 방식을 정의합니다.

display: "block"

unicodeRange

타입: string[]
기본값: undefined

글꼴에서 사용할 유니코드 문자의 범위를 결정합니다.

unicodeRange: ["U+26"]

stretch

타입: string
기본값: undefined

글꼴의 폭을 설정합니다.

stretch: "condensed"

featureSettings

타입: string
기본값: undefined

타이포그래피 글꼴 기능 (예: 합자, 작은 대문자, 스와시 등)을 제어합니다.

featureSettings: "'smcp' 2"

variationSettings

타입: string
기본값: undefined

글꼴의 변형을 설정합니다.

variationSettings: "'xhgt' 0.7"

로컬 글꼴의 `variants`

타입: LocalFontFamily["variants"]

로컬 글꼴 파일을 사용하는 경우 variants 속성은 필수입니다. 각 variant는 @font-face 선언을 나타내며 weight, style, src 값을 필요로 합니다.

그리고 원격 글꼴의 일부 다른 속성들은 각 variant에서 지정될 수 있습니다.

import { defineConfig } from "astro/config";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: "local",
            name: "Custom",
            cssVariable: "--font-custom",
            variants: [
                {
                    weight: 400,
                    style: "normal",
                    src: ["./src/assets/fonts/custom-400.woff2"]
                },
                {
                    weight: 700,
                    style: "normal",
                    src: ["./src/assets/fonts/custom-700.woff2"]
                }
                // ...
            ]
        }]
    }
});

weight

타입: number | string

글꼴의 두께를 설정합니다.

weight: 200

연결된 글꼴이 가변 글꼴인 경우, 두께의 범위를 지정할 수 있습니다.

weight: "100 900"

style

타입: "normal" | "italic" | "oblique"

글꼴 스타일을 설정합니다.

style: "normal"

src

타입: (string | URL | { url: string | URL; tech?: string })[]

글꼴의 소스입니다. 루트를 기준으로 하는 상대 경로, 패키지 가져오기 또는 URL이 될 수 있습니다. 특히 URL은 통합을 통해 로컬 글꼴을 삽입하는 경우에 유용합니다.

src: ["./src/assets/fonts/MyFont.woff2", "./src/assets/fonts/MyFont.woff"]

src: [new URL("./custom.ttf", import.meta.url)]

src: ["my-package/SomeFont.ttf"]

객체를 제공하여 tech를 지정할 수도 있습니다.

src: [{ url:"./src/assets/fonts/MyFont.woff2", tech: "color-COLRv1" }]

기타 속성

원격 글꼴 패밀리의 다음 옵션들은 variant의 로컬 글꼴 패밀리에도 사용할 수 있습니다.

display
unicodeRange
stretch
featureSettings
variationSettings

import { defineConfig } from "astro/config";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: "local",
            name: "Custom",
            cssVariable: "--font-custom",
            variants: [
                {
                    weight: 400,
                    style: "normal",
                    src: ["./src/assets/fonts/custom-400.woff2"],
                    display: "block"
                }
            ]
        }]
    }
});

나만의 글꼴 제공자 구축하기

내장된 제공자 중 하나를 사용하고 싶지 않다면 (예: 타사 unifont 제공자를 사용하거나 개인 레지스트리를 위해 무언가를 구축하려는 경우) 직접 구축할 수 있습니다.

Astro 글꼴 제공자는 구성 객체와 실제 구현의 두 부분으로 구성됩니다.

defineAstroFontProvider() 타입 헬퍼를 사용하여, 다음을 포함하는 글꼴 제공자 구성 객체를 반환하는 함수를 만듭니다.

entrypoint: URL, 루트를 기준으로 하는 상대 경로 또는 패키지 가져오기입니다.
config: unifont 제공자에게 전달되는 선택적인 직렬화 가능한 객체입니다.

config 없이 사용
config와 함께 사용

import { defineAstroFontProvider } from 'astro/config';

export function myProvider() {
    return defineAstroFontProvider({
        entrypoint: new URL('./implementation.js', import.meta.url)
    });
};

import { defineAstroFontProvider } from 'astro/config';

interface Config {
    // ...
};

export function myProvider(config: Config) {
    return defineAstroFontProvider({
        entrypoint: new URL('./implementation.js', import.meta.url),
        config
    });
};

두 번째 파일을 만들어 unifont provider 구현을 내보냅니다.

import { defineFontProvider } from "unifont";

export const provider = defineFontProvider("my-provider", async (options, ctx) => {
    // 사용자 정의 글꼴을 가져오거나 정의합니다.
    // ...
});

글꼴 구성에 사용자 정의 제공자를 추가합니다.

fonts: [{
  provider: fontProviders.myProvider(),
  name: "Custom Font",
  cssVariable: "--font-custom"
 }]

캐싱

글꼴 API 캐싱 구현은 개발 환경에서는 실용적이고, 프로덕션 환경에서는 효율적이도록 설계되었습니다. 빌드 과정에서 글꼴 파일은 _astro/fonts 출력 디렉터리로 복사되므로, 정적 자산의 HTTP 캐싱 (일반적으로 1년)의 이점을 누릴 수 있습니다.

개발 환경에서 캐시를 지우려면 .astro/fonts 디렉터리를 삭제하세요. 빌드 캐시를 지우려면 node_modules/.astro/fonts 디렉터리를 삭제하세요.

더 읽을거리

이 실험적인 API에 대한 자세한 내용과 피드백을 제공하려면 글꼴 RFC를 참조하세요.

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

실험적 글꼴 API

사용법

사용 가능한 원격 글꼴 제공자

<Font /> 컴포넌트 참조

cssVariable

preload

글꼴 구성 참조

공통 속성

provider

name

cssVariable

fallbacks

optimizedFallbacks

원격 글꼴 속성

weights

styles

subsets

display

unicodeRange

stretch

featureSettings

variationSettings

로컬 글꼴의 variants

weight

style

src

기타 속성

나만의 글꼴 제공자 구축하기

캐싱

더 읽을거리

`<Font />` 컴포넌트 참조

로컬 글꼴의 `variants`