{"id":13577836,"url":"https://github.com/pixel-point/fontpie","last_synced_at":"2025-04-06T20:08:15.347Z","repository":{"id":62984873,"uuid":"563401967","full_name":"pixel-point/fontpie","owner":"pixel-point","description":"Get your layout shifts optimized with a CLI-generated piece of CSS","archived":false,"fork":false,"pushed_at":"2023-02-02T14:01:59.000Z","size":334,"stargazers_count":401,"open_issues_count":11,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T19:04:50.378Z","etag":null,"topics":["cli","fonts","javascript","npm"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/pixel-point.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-08T14:37:42.000Z","updated_at":"2025-03-30T06:20:39.000Z","dependencies_parsed_at":"2023-02-17T20:45:51.868Z","dependency_job_id":null,"html_url":"https://github.com/pixel-point/fontpie","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixel-point%2Ffontpie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixel-point%2Ffontpie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixel-point%2Ffontpie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pixel-point%2Ffontpie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pixel-point","download_url":"https://codeload.github.com/pixel-point/fontpie/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247543588,"owners_count":20955865,"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":["cli","fonts","javascript","npm"],"created_at":"2024-08-01T15:01:24.743Z","updated_at":"2025-04-06T20:08:15.332Z","avatar_url":"https://github.com/pixel-point.png","language":"JavaScript","readme":"# Fontpie - get your layout shifts optimized with a CLI-generated piece of CSS! \n\n![npm](https://img.shields.io/npm/v/fontpie) ![npm](https://img.shields.io/npm/dm/fontpie)\n\n## Features\n\n🏃‍♂️ Runs from command line\n\n💪 Generates fallback font metrics to match any custom web font\n\n🚀 Framework, language, and bundler-agnostic solution\n\n👀 Multiple fallback font-weight support\n\n## The problem\n\nCustom web font usage is one of the most common causes of cumulative layout shifts on a page. It happens because your custom font metrics differ from the fallback font metrics available in the operating system, and it is the fallback font that is used by the browser to calculate block sizes while the custom font is loading. Thus, the same text with the same `font-size` and `line-height` properties may occupy different amounts of space.\n\n## The solution\n\nAdjust metrics of the fallback font using [ascent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override), [descent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override), [line-gap-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override), [size-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/size-adjust) properties based on the custom font metrics.\n\n## The outcome\n\n### Layout shift without metric adjustments\nLayout shift is visible. Titles, descriptions takes more space with a fallback(Arial) until a custom font(Roboto) being loaded.\n![Layouf shift without metric adjustments](https://user-images.githubusercontent.com/2697570/200821005-f9a0f362-d7ce-4469-bc2d-c201e61d6e94.gif)\n\n### Layout shift with metric adjustments\nLayout shift does not exist. Fallback font(Arial) with adjusted metrics takes the same space as a custom font(Roboto). \n![Layout shift with metric adjustments](https://user-images.githubusercontent.com/2697570/200821351-db4081c0-433b-48c1-8507-17b15fe4bd92.gif)\n\n## Usage\n\n1. Run the following command, make sure the relative path leads to your custom web font file:\n\n    ```\n    npx fontpie ./roboto-regular.woff2 --name Roboto\n    ```\n\n2. Copypaste the output alongside your font-face declarations: \n \n    ```css\n    @font-face {\n      font-family: 'Roboto';\n      font-style: normal;\n      font-weight: 400;\n      font-display: swap;\n      src: url('roboto-regular.woff2') format('woff2');\n    }\n\n    @font-face {\n      font-family: 'Roboto Fallback';\n      font-style: normal;\n      font-weight: 400;\n      src: local('Times New Roman');\n      ascent-override: 84.57%;\n      descent-override: 22.25%;\n      line-gap-override: 0.00%;\n      size-adjust: 109.71%;\n    }\n\n    html {\n      font-family: 'Roboto', 'Roboto Fallback';\n    }\n    ```\n\n## Options\n\n```txt\nUsage: index [options] \u003cfile\u003e\n\nArguments:\n  file                          *.ttf, *.otf, *.woff or *.woff2 font file\n\nOptions:\n  -f, --fallback \u003cfont-family\u003e  fallback font family type: \"serif\", \"sans-serif\" or \"mono\" (default: \"san-serif\")\n  -s, --style \u003cstyle\u003e           font-style value (default: \"normal\")\n  -w, --weight \u003cweight\u003e         font-weight value (default: \"400\")\n  -n, --name \u003cname\u003e             font name what will be used as font-family value, by default font filename\n  -h, --help                    display help for command\n```\n\n**Serif:** Times New Roman\n\n**Sans-Serif:** Arial\n\n**Monospace:** Courier New \n\n## Compatibility\n\nThe properties used for font metric adjusments:\n- [ascent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override)\n- [descent-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override)\n- [line-gap-override](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override)\n- [size-adjust](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/size-adjust) \n\nare not supported by some browsers:\n\n| Browser | Support  |\n|---|---|\n| Chrome  |   ✅ 87 |\n| Edge  |  ✅ 87  |\n| Firefox |  ✅ 89  |\n| Opera |  ✅ 73  |\n| Safari | ❌ |\n\nYou can keep track on the browser's support for these properties [here](https://caniuse.com/?search=ascent-override).\n\n\n## ❤️ Credits\n\nBig thanks to\n\n- [Katie Hempenius](https://katiehempenius.com/) \u0026 [Kara Erickson](https://github.com/kara) on the Google Aurora team for an algorithm and suggestion - see [notes on calculating font metric overrides](https://docs.google.com/document/d/e/2PACX-1vRsazeNirATC7lIj2aErSHpK26hZ6dA9GsQ069GEbq5fyzXEhXbvByoftSfhG82aJXmrQ_sJCPBqcx_/pub)\n- [Next.js](https://nextjs.org/) for an amazing implementation of it inside [next/font](https://nextjs.org/docs/basic-features/font-optimization)\n- [Fontaine](https://github.com/unjs/fontaine) for the initial idea\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixel-point%2Ffontpie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpixel-point%2Ffontpie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpixel-point%2Ffontpie/lists"}