---
title: "Migrating from @nuxtjs/google-fonts"
description: "Move a Nuxt app from the deprecated @nuxtjs/google-fonts module to @nuxt/fonts."
canonical_url: "https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/migrating-from-google-fonts"
---
# Migrating from @nuxtjs/google-fonts

> Move a Nuxt app from the deprecated @nuxtjs/google-fonts module to @nuxt/fonts.

::warning
`@nuxtjs/google-fonts` is deprecated and no longer maintained. Use `@nuxt/fonts` instead: it self-hosts fonts from Google Fonts and other providers, and generates fallback metrics to reduce layout shift.
::

## Replace the module

Remove `@nuxtjs/google-fonts` and add `@nuxt/fonts`:

::code-group
```bash [pnpm]
pnpm remove @nuxtjs/google-fonts
pnpm add @nuxt/fonts
```

```bash [yarn]
yarn remove @nuxtjs/google-fonts
yarn add @nuxt/fonts
```

```bash [npm]
npm uninstall @nuxtjs/google-fonts
npm install @nuxt/fonts
```
::

Then replace the module in your `nuxt.config`, and move your options from `googleFonts` to `fonts`:

```diff [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
-   '@nuxtjs/google-fonts',
+   '@nuxt/fonts',
  ],
- googleFonts: {
-   families: {
-     Roboto: true,
-   },
- },
})
```

If your app already names its fonts in CSS, such as `font-family: Roboto, sans-serif`, that's all you need: Nuxt Fonts finds each family in your stylesheets, resolves it from Google Fonts, and serves it from your own origin. If you also added `<link>` tags to `fonts.googleapis.com` in `app.head`, remove them, as Nuxt Fonts doesn't read them and they would load the fonts from Google at runtime.

## Fonts are only loaded where they're used

`@nuxtjs/google-fonts` loaded every family in `families` on every page. Nuxt Fonts only emits `@font-face` rules for the families it finds in your CSS, including the CSS that Tailwind CSS or UnoCSS generates for a utility such as `font-Roboto`.

A family that is only used in an inline `style` attribute, an SVG, or a family chosen at runtime is not found. Declare it with `global: true` to load it on every page, as before:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Roboto', provider: 'google', global: true },
    ],
  },
})
```

See [when a font isn't picked up](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/usage#when-a-font-isnt-picked-up) for the full list.

## Converting `families`

`families` is an array in Nuxt Fonts, with one entry per family. Weights are listed in `weights` and italics are enabled with `styles`, and a variable weight range uses the CSS syntax `'200 900'` rather than `'200..900'`. Set `provider: 'google'` to keep resolving each family from Google Fonts rather than from the first [provider](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/providers) that has it.

::code-group
```ts [Before]
export default defineNuxtConfig({
  modules: ['@nuxtjs/google-fonts'],
  googleFonts: {
    families: {
      'Roboto': true,
      'Josefin+Sans': true,
      'Lato': [100, 300],
      'Raleway': {
        wght: [100, 400],
        ital: [100],
      },
      'Crimson Pro': {
        wght: '200..900',
        ital: '200..700',
      },
    },
  },
})
```

```ts [After]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    families: [
      { name: 'Roboto', provider: 'google' },
      { name: 'Josefin Sans', provider: 'google' },
      { name: 'Lato', provider: 'google', weights: [100, 300] },
      { name: 'Raleway', provider: 'google', weights: [100, 400], styles: ['normal', 'italic'] },
      { name: 'Crimson Pro', provider: 'google', weights: ['200 900'], styles: ['normal', 'italic'] },
    ],
  },
})
```
::

Family names are written as they appear in CSS, so `Josefin+Sans` becomes `Josefin Sans`. Every weight in `weights` is loaded in every style in `styles`, so the Raleway entry above also loads italic at weight 400.

The defaults are also different. `Roboto: true` loaded weight 400 in the normal style only, while Nuxt Fonts loads the [`400 700` weight range](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#weights) in both normal and italic styles. To load a single weight and style, set them on the family or for every family with [`defaults`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#defaults):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    defaults: {
      weights: [400],
      styles: ['normal'],
    },
  },
})
```

## Converting other options

| `@nuxtjs/google-fonts`                    | `@nuxt/fonts`                                                                                                                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `families`                                | [`families`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#families), as shown [above](#converting-families). Only needed for families you want to configure.               |
| `display`                                 | [`display`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#display) on each family. It defaults to `swap`, as before.                                                        |
| `subsets`                                 | [`subsets`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#subsets) in `defaults` or on each family.                                                                         |
| `text`                                    | [`glyphs`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#glyphs) in `defaults` or on each family. It is passed to Google Fonts, so only the glyphs you need are downloaded. |
| `preload`                                 | [`preload`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#preload) in `defaults` or on each family, which preloads font files rather than the Google Fonts stylesheet.      |
| `download`                                | No equivalent. Fonts are always downloaded at build time and served from your own origin.                                                                                                                     |
| `prefetch`, `preconnect`, `useStylesheet` | Not needed, as no request is made to Google Fonts from the browser.                                                                                                                                           |
| `inject`                                  | Not needed, as `@font-face` rules are injected into the stylesheets that use them.                                                                                                                            |
| `base64`                                  | No equivalent. Font files are served with long-lived cache headers instead.                                                                                                                                   |
| `outputDir`, `overwriting`                | [`cache`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#cache). Downloaded fonts are cached between builds by default.                                                      |
| `stylePath`, `fontsDir`, `fontsPath`      | [`assets.prefix`](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/configuration#assets) sets the directory fonts are served from. No separate stylesheet is generated.                      |

For example, these options:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/google-fonts'],
  googleFonts: {
    families: {
      Rowdies: true,
    },
    display: 'optional',
    subsets: ['latin'],
    text: 'Nuxt Fonts',
  },
})
```

become:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
  fonts: {
    defaults: {
      subsets: ['latin'],
    },
    families: [
      { name: 'Rowdies', provider: 'google', display: 'optional', glyphs: 'Nuxt Fonts' },
    ],
  },
})
```

## Tailwind CSS

No change is needed for a Tailwind CSS `fontFamily` theme entry such as `Roboto: 'Roboto'`: the `font-Roboto` utility generates a `font-family` declaration, which Nuxt Fonts finds in the generated CSS. With Tailwind CSS v4, see [Tailwind CSS](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/modules/fonts/usage#tailwind-css) for how theme variables are picked up.


## Sitemap

See the full [sitemap](https://nuxt-git-feat-fonts-docs-nuxt-js.vercel.app/sitemap.md) for all pages.