Documentation

Migration Guide V5

Fontsource V5 introduces several breaking changes that may require modifications to your existing codebase. This guide will help you migrate from the previous version to the latest version of Fontsource. Please review the following breaking changes and apply the necessary updates.

Breaking Changes

Variable Font Package Names

Variable fonts are now split into separate packages to provide more flexibility and granular control.

Before

import "@fontsource/roboto-flex/variable.css";
import "@fontsource/roboto-flex/variable-italic.css";
import "@fontsource/roboto-flex/variable-full.css";
import "@fontsource/roboto-flex/variable-full-italic.css";

After

import "@fontsource-variable/roboto-flex";
import "@fontsource-variable/roboto-flex/wght-italic.css";
import "@fontsource-variable/roboto-flex/full.css";
import "@fontsource-variable/roboto-flex/full-italic.css";

Note: Please note that if you were previously using the full variant, it may no longer be available. We have introduced a new standard axis that is generated with a smaller subset of variable axes for improved performance and compatibility.

For more information about the new standard axis and its characteristics, you can refer to the Variable Fonts guide. Additionally, on each font’s page in the search directory, you can explore the import generator to see the available variants specific to that font.

Variable Font Family Names

A mistake made the font-family names for variable fonts inconsistent with the rest of the packages. This has been fixed in V5, so you will need to update your CSS stylesheets.

Before

body {
	font-family: "Roboto FlexVariable", sans-serif;
}

After

body {
	font-family: "Roboto Flex Variable", sans-serif;
}

Renamed Variable Font Files

If you relied on the previous file names that used wghtOnly, you will need to update your code to only use wght instead.

Rewritten Sass Integration

The Sass integration in Fontsource has been completely rewritten in V5. Please refer to the new Sass documentation for detailed usage instructions as there are many changes. Here’s a small example to showcase the difference:

Before

@include OpenSans.fontFace(
  $weight: 500,
  $display: fallback,
  $fontDir: "~@fontsource/open-sans/files"
);

After

@include OpenSans.faces(
  $subsets: latin,
  $weights: (300, 400, 500, 800),
  $styles: all,
  $directory: "~@fontsource/open-sans/files"
);

Material Icons

The Material Icons package has been including the .material-icons class by default. This has been removed in V5, so you will need to add it manually to your codebase. You can find it in the documentation for reference.

Additionally, @fontsource/material-icons-rounded has been renamed to @fontsource/material-icons-round to match the official package name.

License Metadata

A small change to the metadata.json file changes the license property from type string to an a new license object. This has the added benefit of LICENSE files in each package due to the new stored details.

Before

{
  ...
  "license": "https://fonts.google.com/attribution",
  ...
}

After

{
  ...
  "license": {
    "type": "OFL-1.1",
    "url": "http://scripts.sil.org/OFL",
    "attribution": "Copyright <attribution>"
  },
  ...
}