실험적 글꼴 API

타입: FontFamily[]

추가된 버전: astro@5.7.0

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

웹 글꼴은 로드 시간과 렌더링 시간 모두에서 페이지 성능에 영향을 줄 수 있습니다. 이 API는 링크 프리로드, 최적화된 폴백, 권장 기본값을 포함한 자동 웹 글꼴 최적화를 통해 사이트 성능을 유지하도록 도와줍니다. 일반적인 사용 예시를 참고하세요.

글꼴 API는 성능과 개인정보 보호에 중점을 둡니다. 글꼴을 다운로드하고 캐싱하여 사이트에서 직접 제공함으로써 사용자 데이터를 제3자 사이트로 전송하는 것을 방지하고, 모든 방문자에게 일관된 글꼴 세트를 제공할 수 있도록 합니다.

이 기능을 활성화하려면 하나 이상의 글꼴이 포함된 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, subsets, formats 지정과 같은 더 많은 구성 옵션을 사용할 수 있으며, 일부는 선택한 제공자에 따라 달라집니다.

자세한 내용은 전체 구성 참조를 확인하세요.
<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는 일반적인 서비스를 위한 내장 제공자를 내보냅니다. 또한 사용자 정의 Astro 글꼴 제공자를 만들 수도 있습니다.

내장 글꼴 제공자를 사용하려면 fontProviders를 가져와 선택한 글꼴 제공자에 적합한 값으로 provider를 구성하세요.

import { fontProviders } from "astro/config";

Adobe
Bunny
Fontshare
Fontsource
Google
Google Icons
Local

Adobe

Adobe에서 글꼴을 가져옵니다.

provider: fontProviders.adobe({ id: "your-id" })

Adobe 글꼴 제공자에게 Astro 구성 파일의 환경 변수로 로드된 ID를 전달하세요.

Bunny

Bunny에서 글꼴을 가져옵니다.

provider: fontProviders.bunny()

Fontshare

Fontshare에서 글꼴을 가져옵니다.

provider: fontProviders.fontshare()

Fontsource

Fontsource에서 글꼴을 가져옵니다.

provider: fontProviders.fontsource()

Google

Google에서 글꼴을 가져옵니다.

provider: fontProviders.google()

이 제공자는 패밀리별 옵션을 함께 제공합니다.

experimental.glyphs

타입: string[]

각 글꼴 패밀리에 대해 글꼴에 포함할 글리프 목록을 지정할 수 있습니다. 이는 글꼴 파일의 크기를 줄이는 데 도움이 됩니다.

{
  // ...
  provider: fontProviders.google(),
  options: {
    experimental: {
      glyphs: ["a"]
    }
  }
}

experimental.variableAxis

타입: Partial<Record<VariableAxis, ([string, string] | string)[]>>

가변 축에 대한 구성을 설정할 수 있습니다.

{
  // ...
  provider: fontProviders.google(),
  options: {
    experimental: {
      variableAxis: {
        slnt: [["-15", "0"]],
        CASL: [["0", "1"]],
        CRSV: ["1"],
        MONO: [["0", "1"]],
      }
    }
  }
}

Google Icons

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

Google Icons에서 글꼴을 가져옵니다.

provider: fontProviders.googleicons()

이 제공자는 패밀리별 옵션을 함께 제공합니다.

experimental.glyphs

타입: string[]

새로운 Material Symbols 아이콘을 해석할 때 각 글꼴 패밀리의 글꼴에 포함할 글리프 목록을 지정할 수 있습니다. 이는 글꼴 파일의 크기를 줄이는 데 도움이 됩니다.

{
  // ...
  provider: fontProviders.googleicons(),
  options: {
    experimental: {
      glyphs: ["a"]
    }
  }
}

Local

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

디스크에서 글꼴을 가져옵니다.

provider: fontProviders.local()

이 제공자는 필수 패밀리별 옵션을 함께 제공합니다.

variants

타입: LocalFontFamily["variants"]

options.variants 속성은 필수입니다. 각 variant는 하나의 @font-face 선언을 나타내며 src가 필요합니다.

또한 각 variant에 다른 속성들을 지정할 수 있습니다.

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

export default defineConfig({
    experimental: {
        fonts: [{
            provider: fontProviders.local(),
            name: "Custom",
            cssVariable: "--font-custom",
            options: {
                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
기본값: undefined

글꼴의 두께입니다.

weight: 200

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

weight: "100 900"

값이 설정되지 않은 경우, 기본적으로 Astro는 첫 번째 source를 기반으로 값을 유추하려고 시도합니다.

style

타입: "normal" | "italic" | "oblique"
기본값: undefined

글꼴의 스타일입니다.

style: "normal"

값이 설정되지 않은 경우, 기본적으로 Astro는 첫 번째 source를 기반으로 값을 유추하려고 시도합니다.

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, fontProviders } from "astro/config";

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

사용 예시

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

export default defineConfig({
  experimental: {
    fonts: [
      {
        name: "Roboto",
        cssVariable: "--font-roboto",
        provider: fontProviders.google(),
        // 기본 포함 사항:
        // weights: [400] ,
        // styles: ["normal", "italics"],
        // subsets: ["latin"],
        // fallbacks: ["sans-serif"],
        // formats: ["woff2"],
      },
      {
        name: "Inter",
        cssVariable: "--font-inter",
        provider: fontProviders.fontsource(),
        // 실제로 사용되는 두께 지정
        weights: [400, 500, 600, 700],
        // 실제로 사용되는 스타일 지정
        styles: ["normal"],
        // 페이지에서 사용되는 문자에 대한 글꼴 파일만 다운로드
        subsets: ["latin", "cyrillic"],
        // 더 많은 글꼴 형식 다운로드
        formats: ["woff2", "woff"],
      },
      {
        name: "JetBrains Mono",
        cssVariable: "--font-jetbrains-mono",
        provider: fontProviders.fontsource(),
        // 페이지에서 사용되는 문자에 대한 글꼴 파일만 다운로드
        subsets: ["latin", "latin-ext"],
        // 의도한 모양과 일치하는 폴백 글꼴 패밀리 사용
        fallbacks: ["monospace"],
      },
      {
        name: "Poppins",
        cssVariable: "--font-poppins",
        provider: fontProviders.local(),
        options: {
          // 두께와 스타일이 지정되지 않았으므로
          // Astro가 각 variant에 대해 이를 유추하려고 시도합니다.
          variants: [
            {
              src: [
                "./src/assets/fonts/Poppins-regular.woff2",
                "./src/assets/fonts/Poppins-regular.woff",
              ]
            },
            {
              src: [
                "./src/assets/fonts/Poppins-bold.woff2",
                "./src/assets/fonts/Poppins-bold.woff",
              ]
            },
          ]
        }
      }
    ],
  }
});

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

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

이 컴포넌트를 가져와 페이지 <head>에 추가해야 합니다. 이는 전역 사용을 위해, 공통 사이트 레이아웃에서 사용되는 Head.astro와 같은 컴포넌트에서 주로 수행되지만, 필요한 경우 개별 페이지에 추가할 수도 있습니다.

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

cssVariable

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

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

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

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

preload

타입: boolean | { weight?: string | number; style?: string; subset?: string }[]
기본값: false

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

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

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

preload 지시어를 사용하면 브라우저가 페이지 로드 중에 가능한 모든 글꼴 링크를 즉시 다운로드하기 시작합니다.

세밀한 프리로드

추가된 버전: astro@5.15.0

모든 글꼴 링크를 프리로드하고 싶지 않을 수 있습니다. 이는 다른 중요한 리소스 로드를 방해하거나 현재 페이지에 필요하지 않은 글꼴을 다운로드할 수 있기 때문입니다.

어떤 글꼴 파일을 프리로드할지 선택적으로 제어하기 위해, 프리로드할 글꼴의 weight, style subset의 조합을 설명하는 객체 배열을 제공할 수 있습니다.

다음 예시는 두께가 400이거나 latin 서브셋에서 normal 스타일인 글꼴 파일만 프리로드합니다.

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

<Font
  cssVariable="--font-roboto"
  preload={[
    { subset: "latin", style: "normal" },
    { weight: "400" },
  ]}
/>

가변 두께 글꼴 파일의 경우 범위 내의 두께가 요청되면 프리로드됩니다. 예를 들어, 두께 100 900에 대한 글꼴 파일은 preload 객체에 400이 지정되었을 때 포함됩니다.

프로그래밍 방식으로 글꼴 데이터에 접근하기

fontData 객체를 사용하면 하위 수준의 글꼴 패밀리 데이터를 프로그래밍 방식으로 가져올 수 있습니다. 예를 들어 API 라우트에서 사용하거나 나만의 메타 태그를 생성하기 위해 사용할 수 있습니다.

그러면 getFontBuffer() 함수를 사용하여, 가져온 URL로부터 글꼴 버퍼를 얻을 수 있습니다. 예를 들어, API 라우트에서 satori를 사용해 OpenGraph 이미지를 생성할 때, 적절한 형식 구성과 결합하여 사용할 수 있습니다.

import type{ APIRoute } from "astro"
import { fontData, getFontBuffer } from "astro:assets"
import satori from "satori"

export const GET: APIRoute = (context) => {
  const data = fontData["--font-roboto"]

  const svg = await satori(
    <div style={{ color: "black" }}>hello, world</div>,
    {
      width: 600,
      height: 400,
      fonts: [
        {
          name: "Roboto",
          data: await getFontBuffer(data[0].src[0].url),
          weight: 400,
          style: "normal",
        },
      ],
    },
  )

  // ...
}

`fontData`

타입: Record<CssVariable, Array<FontData>>

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

각 키가 cssVariable이고 값이 관련 글꼴을 설명하는 배열인 객체입니다. 각 글꼴은 해당 글꼴에 사용 가능한 src 배열과 weight, style 등의 선택적 속성을 포함하는 객체입니다.

`getFontBuffer()`

타입: (url: string) => Promise<Buffer>

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

fontData에서 얻은 소스 URL로부터 글꼴 파일의 버퍼를 반환합니다.

글꼴 구성 참조

글꼴의 모든 속성은 Astro 구성에서 설정해야 합니다. 글꼴 제공자로부터 로드되는 데이터를 사용자 정의하려면 이를 설정하세요. 예를 들어 특정 글꼴 두께나 스타일만 다운로드 할 수 있습니다. 더 자세한 제어를 위해 세부 글꼴 구성을 사용할 수 있습니다.

각 제공자는 이러한 옵션을 처리할 책임이 있으므로, 다음 속성들의 가용성 및 지원 여부는 다를 수 있습니다.

provider, name, cssVariable은 필수입니다.

provider

타입: FontProvider

글꼴 파일의 소스입니다. 내장 제공자를 사용하거나 직접 사용자 정의 제공자를 작성할 수 있습니다.

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: []

의도한 글꼴의 모양과 일치하는 일반 패밀리 이름을 적어도 하나는 지정하세요. 그러면 Astro는 글꼴 메트릭을 사용하여 최적화된 폴백 생성을 시도합니다. 이 최적화를 비활성화하려면 optimizedFallbacks를 false로 설정하세요.

optimizedFallbacks

타입: boolean
기본값: true

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

optimizedFallbacks: false

weights

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

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

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

관련 글꼴이 가변 글꼴인 경우 두께 범위를 지정할 수 있습니다.

weights: ["100 900"]

styles

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

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

styles: ["normal", "oblique"]

subsets

타입: string[]
기본값: ["latin"]

프리로드할 글꼴 서브셋의 목록을 정의합니다.

subsets: ["latin"]

formats

타입: ("woff2" | "woff" | "otf" | "ttf" | "eot")[]
기본값: ["woff2"]

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

글꼴 형식의 배열입니다.

formats: ["woff2", "woff"]

options

타입: Record<string, any>

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

제공자별 옵션을 전달하기 위한 객체입니다. 글꼴 패밀리 제공자를 기반으로 자동으로 타입이 지정됩니다.

options: {
  experimental: {
    glyphs: ["a"]
  }
}

display

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

글꼴이 다운로드되어 사용할 준비가 된 시점에 따라 글꼴이 표시되는 방식을 정의합니다.

display: "block"

unicodeRange

타입: string[]
기본값: undefined

특정 유니코드 문자 범위에 따라 글꼴을 다운로드하고 사용해야 하는 시점을 결정합니다. 페이지의 문자가 구성된 범위와 일치하면 브라우저가 글꼴을 다운로드하고 모든 문자를 페이지에서 사용할 수 있게 됩니다. 단일 글꼴에 대해 프리로드할 문자의 서브셋을 구성하려면 대신 subsets 속성을 확인하세요.

이는 웹사이트의 특정 부분이 다른 알파벳을 사용하고 별도의 글꼴로 표시될 때, 불필요한 글꼴 다운로드를 방지하기 위한 현지화에 유용할 수 있습니다. 예를 들어 영문판과 일어판을 모두 제공하는 웹사이트에서 unicodeRange에 제공된 일본어 문자가 포함되지 않은 영문판 페이지에서는 브라우저가 일본어 글꼴을 다운로드하지 않도록 방지할 수 있습니다.

unicodeRange: ["U+26"]

stretch

타입: string
기본값: undefined

글꼴의 장평입니다.

stretch: "condensed"

featureSettings

타입: string
기본값: undefined

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

featureSettings: "'smcp' 2"

variationSettings

타입: string
기본값: undefined

글꼴의 가변 설정입니다.

variationSettings: "'xhgt' 0.7"

세부 글꼴 구성

추가된 버전: astro@5.15.6

글꼴 패밀리는 두께와 스타일과 같은 속성의 조합(예: weights: [500, 600] 및 styles: ["normal", "bold"])으로 정의되지만, 이러한 조합 중 일부만 다운로드하고 싶을 수 있습니다.

어떤 글꼴 파일을 다운로드할지 더 세밀하게 제어하려면 동일한 글꼴(즉, 동일한 cssVariable, name, provider 속성 사용)을 서로 다른 조합으로 여러 번 지정할 수 있습니다. Astro는 결과를 병합하여 필요한 파일만 다운로드합니다. 예를 들어 일반 스타일 500과 600을 다운로드하면서 이탤릭체는 500만 다운로드하는 것이 가능합니다.

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

export default defineConfig({
  experimental: {
    fonts: [
      {
        name: "Roboto",
        cssVariable: "--roboto",
        provider: fontProviders.google(),
        weights: [500, 600],
        styles: ["normal"]
      },
      {
        name: "Roboto",
        cssVariable: "--roboto",
        provider: fontProviders.google(),
        weights: [500],
        styles: ["italic"]
      }
    ]
  }
})

나만의 글꼴 제공자 만들기

내장 제공자 중 하나를 사용하고 싶지 않은 경우(예: 제3자 unifont 제공자를 사용하거나 비공개 레지스트리용 구축을 원하는 경우) 직접 만들 수 있습니다.

사용자 정의 글꼴 제공자를 구현하는 권장 방법은 FontProvider 객체를 반환하고 구성을 매개변수로 받는 함수를 내보내는 것입니다.

글꼴 제공자 객체

실험적인 글꼴 API를 사용하면 통합된 방식으로 글꼴에 접근할 수 있습니다. 각 패밀리는 글꼴 페이스를 가져오기 위해 Astro 글꼴 제공자를 사용해야 합니다.

FontProvider는 필수 속성인 name 및 resolveFont()를 포함하는 객체입니다. 또한 선택적 속성인 config, init(), listFonts()를 사용할 수 있습니다.

FontProvider 타입은 패밀리 옵션을 위해 제네릭을 허용합니다.

`name`

타입: string

로그 및 식별에 사용되는 제공자의 고유 이름입니다.

`resolveFont()`

타입: (options: ResolveFontOptions) => Awaitable<{ fonts: FontFaceData[] } | undefined>

주어진 옵션에 따라 글꼴 페이스 데이터를 조회하고 반환하는 데 사용됩니다.

`config`

타입: Record<string, any>
기본값: undefined

식별에 사용되는 직렬화 가능한 객체입니다.

`init()`

타입: (context: FontProviderInitContext) => Awaitable<void>
기본값: undefined

초기화 로직을 수행하는 데 사용되는 선택적 콜백입니다.

`context.storage`

타입: Storage

캐싱에 유용합니다.

`context.root`

타입: URL

로컬 파일 경로를 해석하는 데 유용한 프로젝트 루트입니다.

`listFonts()`

타입: () => Awaitable<string[] | undefined>
기본값: undefined

사용 가능한 글꼴 이름 목록을 반환하는 데 사용되는 선택적 콜백입니다.

비공개 레지스트리 지원하기

다음 예시는 비공개 레지스트리를 위한 글꼴 제공자를 정의합니다.

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

export function registryFontProvider(): FontProvider {
  let data: Fonts = {}

  return {
    name: "registry",
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

interface Config {
  token: string;
}

export function registryFontProvider(config: Config): FontProvider {
  let data: Fonts = {}

  return {
    name: "registry",
    config,
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

interface FamilyOptions {
  minimal?: boolean;
}

export function registryFontProvider(): FontProvider<FamilyOptions | undefined> {
  let data: Fonts = {}

  return {
    name: "registry",
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    // options의 타입은 FamilyOptions | undefined입니다.
    resolveFont: ({ familyName, options, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

그런 다음 Astro 구성에서 이 글꼴 제공자를 등록할 수 있습니다.

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: registryFontProvider(),
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: registryFontProvider({
              token: "..."
            }),
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: registryFontProvider(),
            options: {
              minimal: true
            },
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

제3자 unifont 제공자 지원하기

내부적으로 unifont 제공자를 사용하여 Astro 글꼴 제공자를 정의할 수 있습니다.

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider } from "@acme/unifont-provider"

export function acmeFontProvider(): FontProvider {
  const provider = acmeProvider();
  let initializedProvider: InitializedProvider | undefined;
  return {
    name: provider._name,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider, type AcmeOptions } from "@acme/unifont-provider"

export function acmeFontProvider(config?: AcmeOptions): FontProvider {
  const provider = acmeProvider(config);
  let initializedProvider: InitializedProvider | undefined;
  return {
    name: provider._name,
    config,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider, type AcmeFamilyOptions } from "@acme/unifont-provider"

export function acmeFontProvider(): FontProvider<AcmeFamilyOptions | undefined> {
  const provider = acmeProvider();
  let initializedProvider: InitializedProvider<AcmeFamilyOptions> | undefined;
  return {
    name: provider._name,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

그런 다음 Astro 구성에서 이 글꼴 제공자를 등록할 수 있습니다.

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: acmeFontProvider(),
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: acmeFontProvider({
              token: "..."
            }),
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: acmeFontProvider(),
            options: {
              minimal: true
            },
            name: "Custom",
            cssVariable: "--font-custom"
        }]
    }
});

캐싱

글꼴 API 캐싱 구현은 개발 중에는 실용적이고 프로덕션 환경에서는 효율적이도록 설계되었습니다. 빌드 시 글꼴 파일은 _astro/fonts 출력 디렉터리에 복사되어 정적 자산의 HTTP 캐싱(보통 1년) 혜택을 받을 수 있습니다.

개발 중에 캐시를 삭제하려면 .astro/fonts 디렉터리를 제거하세요. 빌드 캐시를 삭제하려면 node_modules/.astro/fonts 디렉터리를 제거하세요.

더 읽어보기

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

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

실험적 글꼴 API

사용법

사용 가능한 글꼴 제공자

Adobe

Bunny

Fontshare

Fontsource

Google

experimental.glyphs

experimental.variableAxis

Google Icons

experimental.glyphs

Local

variants

weight

style

src

기타 속성들

사용 예시

<Font /> 컴포넌트 참조

cssVariable

preload

세밀한 프리로드

프로그래밍 방식으로 글꼴 데이터에 접근하기

fontData

getFontBuffer()

글꼴 구성 참조

provider

name

cssVariable

fallbacks

optimizedFallbacks

weights

styles

subsets

formats

options

display

unicodeRange

stretch

featureSettings

variationSettings

세부 글꼴 구성

나만의 글꼴 제공자 만들기

글꼴 제공자 객체

name

resolveFont()

config

init()

context.storage

context.root

listFonts()

비공개 레지스트리 지원하기

제3자 unifont 제공자 지원하기

캐싱

더 읽어보기

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

`fontData`

`getFontBuffer()`

`name`

`resolveFont()`

`config`

`init()`

`context.storage`

`context.root`

`listFonts()`