{"id":13810509,"url":"https://github.com/nuxt-modules/fontaine","last_synced_at":"2025-05-14T19:07:35.616Z","repository":{"id":58540146,"uuid":"531960305","full_name":"nuxt-modules/fontaine","owner":"nuxt-modules","description":"🔤 Font metric overrides to reduce CLS","archived":false,"fork":false,"pushed_at":"2025-05-13T15:24:30.000Z","size":3414,"stargazers_count":401,"open_issues_count":9,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-13T16:42:09.459Z","etag":null,"topics":["cls","hacktoberfest","nuxt","nuxt-module","performance","web-vitals"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nuxt-modules.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["danielroe"]}},"created_at":"2022-09-02T14:32:55.000Z","updated_at":"2025-05-12T19:37:16.000Z","dependencies_parsed_at":"2023-11-30T00:22:55.418Z","dependency_job_id":"93778781-a325-4583-bbb3-390554d8aac9","html_url":"https://github.com/nuxt-modules/fontaine","commit_stats":{"total_commits":218,"total_committers":6,"mean_commits":"36.333333333333336","dds":0.1330275229357798,"last_synced_commit":"3abf32e9e9e847a9afdb0d2d090a5ceb23ff6fcf"},"previous_names":["danielroe/nuxt-font-metrics"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt-modules%2Ffontaine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt-modules%2Ffontaine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt-modules%2Ffontaine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nuxt-modules%2Ffontaine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nuxt-modules","download_url":"https://codeload.github.com/nuxt-modules/fontaine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cls","hacktoberfest","nuxt","nuxt-module","performance","web-vitals"],"created_at":"2024-08-04T02:00:57.238Z","updated_at":"2025-05-14T19:07:30.506Z","avatar_url":"https://github.com/nuxt-modules.png","language":"TypeScript","funding_links":["https://github.com/sponsors/danielroe"],"categories":["TypeScript"],"sub_categories":[],"readme":"# Nuxt Fontaine\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n[![Github Actions][github-actions-src]][github-actions-href]\n[![Codecov][codecov-src]][codecov-href]\n\n\u003e Font metric fallback implementation for [Nuxt 3](https://v3.nuxtjs.org)\n\n- [✨ \u0026nbsp;Changelog](https://github.com/nuxt-modules/fontaine/blob/main/CHANGELOG.md)\n- [▶️ \u0026nbsp;Online playground](https://stackblitz.com/github/nuxt-modules/fontaine/tree/main/playground)\n\n## Features\n\n**⚠️ `@nuxtjs/fontaine` is under active development. ⚠️**\n\n- 💪 Reduces CLS by using local font fallbacks with crafted font metrics.\n- ✨ Generates font metrics and fallbacks automatically.\n- ⚡️ Pure CSS, zero runtime overhead.\n\nOn the playground project, enabling/disabling this module makes the following differences rendering `/`, with no customisation required:\n\n|             | Before | After   |\n| ----------- | ------ | ------- |\n| CLS         | `0.34` | `0.013` |\n| Performance | `88`   | `98`    |\n\n## What's next\n\nFor best performance, you will need to inline _all_ your CSS, not just the font-face fallback rules (which this module does automatically), or there will still be a layout shift when the stylesheet loads (which is why the number above is not zero).\n\n[This PR](https://github.com/nuxt/framework/pull/7160) aims to bring that ability to Nuxt itself.\n\n## Installation\n\n```bash\nnpx nuxi@latest module add fontaine\n```\n\n## Usage\n\n```js\nexport default defineNuxtConfig({\n  modules: ['@nuxtjs/fontaine'],\n  // If you are using a Google font or you don't have a @font-face declaration\n  // for a font you're using, you can declare them here.\n  //\n  // In most cases this is not necessary.\n  //\n  // fontMetrics: {\n  //   fonts: ['Inter', { family: 'Some Custom Font', src: '/path/to/custom/font.woff2' }],\n  // },\n})\n```\n\nThat's it!\n\n### Tailwind CSS\n\nIf you use Tailwind CSS and use your custom font via the config file, you will need to manually add the fallback font.\n\n```ts\nimport type { Config } from 'tailwindcss'\nimport { fontFamily } from 'tailwindcss/defaultTheme'\n\nexport default \u003cPartial\u003cConfig\u003e\u003e {\n  theme: {\n    extend: {\n      fontFamily: {\n        sans: ['Roboto', 'Roboto fallback', ...fontFamily.sans],\n      },\n    },\n  },\n}\n```\n\n## How it works\n\nNuxt will scan your `@font-face` rules and generate fallback rules with the correct metrics. For example:\n\n```css\n@font-face {\n  font-family: 'Roboto';\n  font-display: swap;\n  src: url('/fonts/Roboto.woff2') format('woff2'), url('/fonts/Roboto.woff') format('woff');\n  font-weight: 700;\n}\n/* This will be generated. */\n@font-face {\n  font-family: 'Roboto fallback';\n  src: local('Segoe UI'), local('Roboto'), local('Helvetica Neue'), local('Arial'), local('Noto Sans');\n  ascent-override: 92.7734375%;\n  descent-override: 24.4140625%;\n  line-gap-override: 0%;\n}\n```\n\nThen, whenever you use `font-family: 'Roboto'`, Nuxt will add the fallback to the font-family:\n\n```css\n:root {\n  font-family: 'Roboto';\n  /* This becomes */\n  font-family: 'Roboto', 'Roboto fallback';\n}\n```\n\n## Using outside of Nuxt\n\nThe core of this module will work outside of Nuxt, and has been separated into a separate library: [`fontaine`](https://github.com/unjs/fontaine). Check it out!\n\n## 💻 Development\n\n- Clone this repository\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`\n- Install dependencies using `pnpm install`\n- Stub module with `pnpm dev:prepare`\n- Run `pnpm dev` to start [playground](./playground) in development mode\n\n## Credits\n\nThis would not have been possible without:\n\n- amazing tooling and generated metrics from [capsizecss](https://seek-oss.github.io/capsize)\n- suggestion and algorithm from [Katie Hempenius](https://katiehempenius.com/) \u0026 [Kara Erickson](https://github.com/kara) on the Google Aurora team - see [notes on calculating font metric overrides](https://docs.google.com/document/d/e/2PACX-1vRsazeNirATC7lIj2aErSHpK26hZ6dA9GsQ069GEbq5fyzXEhXbvByoftSfhG82aJXmrQ_sJCPBqcx_/pub).\n\n## License\n\nMade with ❤️\n\nPublished under the [MIT License](./LICENCE).\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/@nuxtjs/fontaine?style=flat-square\n[npm-version-href]: https://npmjs.com/package/@nuxtjs/fontaine\n[npm-downloads-src]: https://img.shields.io/npm/dm/@nuxtjs/fontaine?style=flat-square\n[npm-downloads-href]: https://npm.chart.dev/@nuxtjs/fontaine\n[github-actions-src]: https://img.shields.io/github/workflow/status/nuxt-modules/fontaine/ci/main?style=flat-square\n[github-actions-href]: https://github.com/nuxt-modules/fontaine/actions/workflows/ci.yml\n[codecov-src]: https://img.shields.io/codecov/c/gh/nuxt-modules/fontaine/main?style=flat-square\n[codecov-href]: https://codecov.io/gh/nuxt-modules/fontaine\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt-modules%2Ffontaine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnuxt-modules%2Ffontaine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnuxt-modules%2Ffontaine/lists"}