Uso de fuentes personalizadas

Esta guía te mostrará cómo agregar fuentes web a tu proyecto y usarlas en tus componentes.

Astro proporciona una forma de usar fuentes de tu sistema de archivos y varios proveedores de fuentes (p. ej., Fontsource, Google) a través de una API unificada, completamente personalizable y con seguridad de tipos.

Las fuentes web pueden afectar al rendimiento de la página tanto en el tiempo de carga como en el de renderizado. Esta API te ayuda a mantener tu sitio con un buen rendimiento con optimizaciones automáticas de fuentes web, incluyendo enlaces de precarga, fuentes alternativas optimizadas y valores predeterminados de opinión. Consulta ejemplos de uso comunes.

La API de fuentes se centra en el rendimiento y la privacidad al descargar y almacenar en caché las fuentes para que se sirvan desde tu sitio. Esto puede evitar el envío de datos de usuario a sitios de terceros, y también garantiza que un conjunto consistente de fuentes esté disponible para todos tus visitantes.

Configuración de fuentes personalizadas

El registro de fuentes personalizadas para tu proyecto de Astro se realiza a través de la opción fonts en tu configuración de Astro.

Para cada fuente que quieras usar, debes especificar su nombre, una variable CSS y un proveedor de fuentes de Astro.

Astro proporciona soporte integrado para los proveedores de fuentes más populares: Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons y NPM, así como para usar tus propios archivos de fuentes locales. Además, puedes personalizar aún más tu configuración de fuentes para optimizar el rendimiento y la experiencia del visitante.

Uso de un archivo de fuente local

Este ejemplo demostrará cómo agregar una fuente personalizada usando el archivo de fuente DistantGalaxy.woff2.

Agrega tu archivo de fuente dentro del directorio src/, por ejemplo, src/assets/fonts/.

Crea una nueva familia de fuentes en tu archivo de configuración de Astro utilizando el proveedor de fuentes local y especifica las variantes que se incluirán:

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

export default defineConfig({
  fonts: [{
    provider: fontProviders.local(),
    name: "DistantGalaxy",
    cssVariable: "--font-distant-galaxy",
    options: {
      variants: [{
        src: ['./src/assets/fonts/DistantGalaxy.woff2'],
        weight: 'normal',
        style: 'normal'
      }]
    }
  }]
});

Tu fuente ahora está configurada y lista para ser agregada al head de tu página para que pueda usarse en tu proyecto.

Uso de Fontsource

Astro admite varios proveedores de fuentes de forma nativa, incluido el soporte para Fontsource que simplifica el uso de Google Fonts y otras fuentes de código abierto.

El siguiente ejemplo utilizará Fontsource para agregar soporte de fuentes personalizadas, pero el proceso es similar para cualquiera de los proveedores de fuentes integrados de Astro (p. ej., Adobe, Bunny).

Busca la fuente que quieres usar en el catálogo de Fontsource. Este ejemplo utilizará Roboto.

Crea una nueva familia de fuentes en tu archivo de configuración de Astro utilizando el proveedor Fontsource:

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

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

Tu fuente ahora está configurada y lista para ser agregada al head de tu página para que pueda usarse en tu proyecto.

Aplicación de fuentes personalizadas

Después de configurar una fuente, se debe agregar al head de tu página con una variable CSS de identificación. Luego, puedes usar esta variable al definir los estilos de tu página.

Importa e incluye el componente <Font /> con la propiedad cssVariable requerida en el head de tu página, generalmente en un componente Head.astro dedicado o directamente en un componente de diseño (layout):
src/layouts/Layout.astro
```
---
import { Font } from "astro:assets";
---

<html>
  <head>
    <Font cssVariable="--font-distant-galaxy" />
  </head>
  <body>
    <slot />
  </body>
</html>
```
En cualquier página renderizada con ese diseño, incluyendo el propio componente de diseño, ahora puedes definir estilos con la variable cssVariable de tu fuente para aplicar tu fuente personalizada.

En el siguiente ejemplo, el encabezado <h1> tendrá aplicada la fuente personalizada, mientras que el párrafo <p> no.
src/pages/example.astro
```
---
import Layout from "../layouts/Layout.astro";
---
<Layout>
  <h1>In a galaxy far, far away...</h1>

  <p>Custom fonts make my headings much cooler!</p>

  <style>
  h1 {
    font-family: var(--font-distant-galaxy);
  }
  </style>
</Layout>
```

Precarga de fuentes

La precarga de fuentes debe hacerse con moderación, ya que puede bloquear la carga de otros recursos importantes o descargar fuentes que no son necesarias para la página actual. Considera precargar solo las fuentes más esenciales, necesarias para mostrar el contenido visible en la parte superior de la página.

Para precargar una fuente, pasa la propiedad preload al componente <Font /> correspondiente. Si varios archivos corresponden a una fuente, también puedes especificar cuál precargar pasando un array.

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

<html>
  <head>
    <Font cssVariable="--font-distant-galaxy" preload />
  </head>
  <body>
    <slot />
  </body>
</html>

Registrar fuentes en Tailwind

Si estás utilizando Tailwind para dar estilos, no aplicarás tus estilos con la propiedad CSS font-face.

En su lugar, después de configurar tu fuente personalizada y agregarla al head de tu página, necesitarás actualizar tu configuración de Tailwind para registrar tu fuente:

Tailwind CSS 4.0
Tailwind CSS 3.0

@import "tailwindcss";

@theme inline {
  --font-sans: var(--font-roboto);
}

/** @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: []
};

Consulta la documentación de Tailwind sobre cómo agregar familias de fuentes personalizadas para obtener más información.

Uso de fuentes variables

Para usar fuentes variables en tu proyecto, especifica el rango de peso disponible en lugar de pesos individuales en la configuración de tu proveedor.

Proveedor local
Otros proveedores

Al usar un archivo de fuente local, puedes especificar que la fuente es variable estableciendo la propiedad weight de la variante a una cadena que corresponda al rango de peso exacto disponible para la fuente.

El siguiente ejemplo configura Inter como una fuente variable local con el rango de peso disponible:

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

export default defineConfig({
  fonts: [{
    provider: fontProviders.local(),
    name: "Inter",
    cssVariable: "--font-inter",
    options: {
      variants: [
        {
          weight: "100 900",
          style: "normal",
          src: ["./src/assets/fonts/InterVariable.woff2"],
        },
      ],
    },
  }]
});

Al usar otros proveedores (p. ej., Fontsource) que admiten fuentes variables, puedes solicitar la versión variable de una fuente estableciendo la propiedad weights con un array que contenga el rango exacto de pesos disponibles para la fuente.

El siguiente ejemplo descarga Fira Code desde Fontsource como una fuente variable con el rango de peso disponible:

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

export default defineConfig({
  fonts: [{
    cssVariable: "--font-fira-code",
    name: "Fira Code",
    provider: fontProviders.fontsource(),
    styles: ["normal"],
    weights: ["300 700"],
  }]
});

Personalización de fuentes alternativas

Las fuentes alternativas (fallback) se utilizan cuando la fuente principal aún no se ha cargado, contiene caracteres faltantes o no se puede cargar por cualquier motivo. Cuando la fuente alternativa difiere significativamente de la fuente principal, pueden producirse cambios de diseño (layout shifts) durante la carga de la página.

Para evitar esto, Astro intenta generar automáticamente fuentes alternativas optimizadas a partir de la última fuente alternativa definida si es una familia de fuentes genérica. Utiliza sans-serif de forma predeterminada, pero es posible que no coincida con la apariencia deseada de tu fuente principal. Puedes ajustarlo en tu configuración de fuentes:

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

export default defineConfig({
  fonts: [{
    provider: fontProviders.fontsource(),
    name: "Cousine",
    cssVariable: "--font-cousine",
    fallbacks: ["monospace"]
  }]
});

También puedes desactivar la optimización predeterminada estableciendo font.optimizedFallbacks en false en tu configuración de fuentes. Astro utilizará entonces las fuentes alternativas especificadas en tu configuración sin ningún procesamiento automático adicional.

Acceder a los datos de las fuentes programáticamente

Astro expone APIs de bajo nivel para acceder a los datos programáticamente:

Datos de la familia de fuentes a través del objeto fontData
URLs de archivos de fuentes con la función experimental_getFontFileURL().

Esto puede ser útil para casos de uso avanzados en los que necesitas acceso directo a los archivos de fuentes, como generar imágenes OpenGraph con Satori en una Ruta de la API.

El objeto fontData te da acceso a todos los archivos de fuentes descargados por Astro para tu proyecto, junto con sus metadatos. Esto significa que eres responsable de filtrar los archivos de fuentes para encontrar el archivo específico que necesitas, y de obtener los datos después de resolver las URLs.

El siguiente ejemplo genera una imagen OpenGraph en un endpoint de archivo estático, asumiendo que solo se ha configurado una fuente y su formato con un formato compatible con Satori:

import type { APIRoute } from "astro";
import { fontData, experimental_getFontFileURL } from "astro:assets";
import satori from "satori";
import { html } from "satori-html";
import sharp from "sharp";

export const GET: APIRoute = async (context) => {
  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;

  if (fontPath === undefined) {
    throw new Error("Cannot find the font path.");
  }

  const url = experimental_getFontFileURL(fontPath, context.url);
  const data = await fetch(url).then((res) => res.arrayBuffer());

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

  const pngBuffer = await sharp(Buffer.from(svg)) // requires `@types/node` in your dependencies for type safety
    .resize(600, 400)
    .png()
    .toBuffer();

  return new Response(new Uint8Array(pngBuffer), {
    headers: {
      "Content-Type": "image/png",
    },
  });
};

Configuración detallada de fuentes

Una familia de fuentes se define por una combinación de propiedades como pesos y estilos (p. ej., weights: [500, 600] y styles: ["normal", "bold"]), pero es posible que desees descargar solo ciertas combinaciones de estos.

Para tener un mayor control sobre qué archivos de fuentes se descargan, puedes especificar la misma fuente (es decir, con las mismas propiedades cssVariable, name y provider) varias veces con diferentes combinaciones. Astro fusionará los resultados y descargará solo los archivos requeridos. Por ejemplo, es posible descargar normal 500 y 600 mientras descargas solo italic 500:

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

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

Almacenamiento en caché

La implementación del almacenamiento en caché de la API de fuentes se diseñó para ser práctica en desarrollo y eficiente en producción. Durante las compilaciones, los archivos de fuentes se copian en el directorio de salida _astro/fonts, por lo que pueden beneficiarse del almacenamiento en caché HTTP de activos estáticos (normalmente un año).

Para borrar la caché en desarrollo, elimina el directorio .astro/fonts. Para borrar la caché de compilación, elimina el directorio node_modules/.astro/fonts.

Ejemplos

La función de fuentes de Astro se basa en opciones de configuración flexibles. La configuración de fuentes de tu propio proyecto puede tener un aspecto diferente al de los ejemplos simplificados, por lo que los siguientes se proporcionan para mostrar cómo podrían verse varias configuraciones de fuentes cuando se usan en producción.

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

export default defineConfig({
  fonts: [
    {
      name: "Roboto",
      cssVariable: "--font-roboto",
      provider: fontProviders.google(),
      // Default included:
      // weights: [400] ,
      // styles: ["normal", "italic"],
      // subsets: ["latin"],
      // fallbacks: ["sans-serif"],
      // formats: ["woff2"],
    },
    {
      name: "Inter",
      cssVariable: "--font-inter",
      provider: fontProviders.fontsource(),
      // Specify weights that are actually used
      weights: [400, 500, 600, 700],
      // Specify styles that are actually used
      styles: ["normal"],
      // Download only font files for characters used on the page
      subsets: ["latin", "cyrillic"],
      // Download more font formats
      formats: ["woff2", "woff"],
    },
    {
      name: "JetBrains Mono",
      cssVariable: "--font-jetbrains-mono",
      provider: fontProviders.fontsource(),
      // Download only font files for characters used on the page
      subsets: ["latin", "latin-ext"],
      // Use a fallback font family matching the intended appearance
      fallbacks: ["monospace"],
    },
    {
      name: "Poppins",
      cssVariable: "--font-poppins",
      provider: fontProviders.local(),
      options: {
        // Weight and style are not specified so Astro
        // will try to infer them for each 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",
            ]
          },
        ]
      }
    }
  ],
});

Contribuir Comunidad Patrocinar