{"id":18500029,"url":"https://github.com/vicgutt/tailwindcss-font-face","last_synced_at":"2026-05-07T02:37:26.009Z","repository":{"id":143815456,"uuid":"378645701","full_name":"VicGUTT/tailwindcss-font-face","owner":"VicGUTT","description":"An easy way to configure your project's font faces within TailwindCSS","archived":false,"fork":false,"pushed_at":"2021-06-20T13:29:43.000Z","size":208,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T05:08:19.207Z","etag":null,"topics":["font","font-face","tailwind-plugin","tailwindcss","typography"],"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/VicGUTT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-20T12:57:27.000Z","updated_at":"2021-11-04T01:46:51.000Z","dependencies_parsed_at":"2023-07-11T08:33:44.183Z","dependency_job_id":null,"html_url":"https://github.com/VicGUTT/tailwindcss-font-face","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VicGUTT%2Ftailwindcss-font-face","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VicGUTT%2Ftailwindcss-font-face/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VicGUTT%2Ftailwindcss-font-face/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VicGUTT%2Ftailwindcss-font-face/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VicGUTT","download_url":"https://codeload.github.com/VicGUTT/tailwindcss-font-face/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254084899,"owners_count":22011965,"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":["font","font-face","tailwind-plugin","tailwindcss","typography"],"created_at":"2024-11-06T13:48:13.703Z","updated_at":"2026-05-07T02:37:25.959Z","avatar_url":"https://github.com/VicGUTT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# An easy way to configure your project's font faces within [TailwindCSS](https://tailwindcss.com)\n\nThis plugin provides you with a `fontFace` configuration theme that allows you to setup your project's `@font-face` rules either by defining the rules manually or by pointing to an external CSS file.\nHere's a quick example:\n\n```js\n// tailwind.config.js\n\nmodule.exports = {\n    theme: {\n        // Using a font provider (external CSS file)\n        fontFace: [\n            'https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,200;1,200\u0026display=swap',\n            'https://fonts-provider.com/Montserrat'\n        ],\n        // Manually defining the rules\n        fontFace: [\n            {\n                fontFamily: 'Mulish',\n                fontStyle: 'normal',\n                fontWeight: 900,\n                src: '/fonts/Mulish/Mulish-Black.ttf',\n                // ...\n            },\n            // ...\n        ],\n    },\n    plugins: [\n        require('@vicgutt/tailwindcss-font-face')({\n            fontDir: './public/fonts/Mulish',\n            fontPath: '/fonts/Mulish',\n        }),\n    ],\n};\n```\n\n## How it works\n\nWhen passing in font face rules manually the plugin will mostly just pass it down to Tailwind so the CSS styles can be generated.\nIf an external CSS file is provided, the plugin will extract that file's font faces, fetch and store the font files, set the correct font path for all font faces, convert the font faces to an object and finally pass it down to Tailwind.\n\nYou might be interested in taking a look at the [Handler.ts](https://github.com/VicGUTT/tailwindcss-font-face/blob/main/src/Handler.ts) and [AbstractFontsProvider.ts](https://github.com/VicGUTT/tailwindcss-font-face/blob/main/src/FontFaceProviders/AbstractFontsProvider.ts) files.\n\nThe generated CSS will be added to Tailwind's **base** layer.\n\n## Installation\n\nInstall the plugin via NPM _(or yarn)_:\n\n``` bash\n# Using npm\nnpm i @vicgutt/tailwindcss-font-face\n\n# Using Yarn\nyarn add @vicgutt/tailwindcss-font-face\n```\n\nThen add the plugin to your tailwind.config.js file:\n\n``` js\n// tailwind.config.js\n\nmodule.exports = {\n    theme: {\n        // ...\n    },\n    plugins: [\n        require('@vicgutt/tailwindcss-font-face'),\n        // ...\n    ],\n};\n```\n\n## Options\n\nThe plugin exposes a few options that may used to configure it's behaviour.\n\n| Name                 | Type                | Default            | Description |\n| -------------------- | ------------------- | ------------------ | ----------- |\n| fontDir              | `string\\|undefined` | `undefined`        | Necessary, when fetching an external file, to know where to store the font files. This value can also be specified when defining the external resource as in object.  \n| fontPath             | `string\\|undefined` | `undefined`        | Necessary, when fetching an external file, as it will be used to set the font's `src` url. This value can also be specified when defining the external resource as in object.  \n| defaultFontFaceRules | `object\\|undefined` | `undefined`        | Default font face rules that will be applied to all styles _(manually defined or not)_.\n\nHere's an example of how those options can be used:\n\n```js\n// tailwind.config.js\n\nmodule.exports = {\n    // ...\n    plugins: [\n        require('@vicgutt/tailwindcss-font-face')({\n            fontDir: './path/to/where/the/externally/fetched/font/files/will/be/stored',\n            fontPath: '/value/that/will/be/used/for/the/font/face/src/url',\n            defaultFontFaceRules: {\n                fontFamily: 'My-awesome-font',\n                fontDisplay: 'swap',\n                fontStyle: 'normal',\n                fontWeight: 500,\n                // ...\n            },\n        }),\n    ],\n};\n```\n\n## Usage\n\nThe `fontFace` theme key accepts either [Manual styles](#manual-styles) or [External styles](#external-styles) or a mix of both.\nHere's how they can both be structured:\n\n### Manual styles\n\nIt expects CSS rules written as JavaScript objects in the same CSS-in-JS syntax used [throughout Tailwind](https://tailwindcss.com/docs/plugins#css-in-js-syntax).\nThat said, the following properties are considered \"special\" by the plugin:\n\n#### src\n\nThis property may be defined as a `string`, `object`, or an `array` of either or both.\nIf defined as an object, it requires the `url` key to be present and it's value to be the path from where the font file will be downloaded when needed by a browser.\nIt accepts an optional `format` key that denotes well-known font formats and avoids the browser from downloading unsupported font formats.\n\nSee the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src) from more details.\n\nHere's examples of how the src may be defined:\n\n```js\n{\n    src: '/the/font/path.woff2',\n    // - or -\n    src: { url: '/the/font/path.woff2', format: 'woff2' },\n    // - or -\n    src: { url: '/the/font/path.woff2', format: 'auto' }, // Will detect the \"woff2\" format from the file extension when possible\n    // - or a mix -\n    src: [\n        '/a/font/path1.woff2',\n        { url: '/a/font/path2.woff2' },\n        { url: '/a/font/path3.woff2', format: 'woff2' },\n        { url: '/a/font/path4.woff2', format: 'auto' },\n        { url: '/a/font/path5.unknown', format: 'woff2' },\n        { url: '/a/font/path6.unknown', format: 'auto' },\n    ],\n};\n```\n\nThis will produce the following CSS:\n\n```css\n@font-face {\n    src: url('/the/font/path.woff2');\n    /* or */\n    src: url('/the/font/path.woff2') format('woff2');\n    /* or */\n    src: url('/the/font/path.woff2') format('woff2'); /* Format automatically detected */\n    /* or a mix */\n    src: url('/a/font/path1.woff2'),\n        url('/a/font/path2.woff2'),\n        url('/a/font/path3.woff2') format('woff2'),\n        url('/a/font/path4.woff2') format('woff2'),\n        url('/a/font/path5.unknown') format('woff2'),\n        url('/a/font/path6.unknown');\n}\n```\n\n#### fontWeight\n\nThis property expects any valid [CSS \"font-weight\" value](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight) or any [Tailwind \"font-weight\" name](https://tailwindcss.com/docs/font-weight) minus the \"font-\" prefix.\nIt also accepts two values to specify a range that is supported by the font-face which can be written as an array or a string.\n\nThe following table demontrates the expected values:\n\n| Value             | Mapped to       | Description |\n| ----------------- | --------------- | ----------- |\n| number            | Itself          | Usefull for \"variable fonts\"\n| 100 to 900        | Itself          | Standard numeric font weight values\n| normal            | Itself          | Normal font weight. Same as 400.\n| bold              | Itself          | Bold font weight. Same as 700.\n| thin              | 100             | Tailwind font weight name for the \"100\" CSS value\n| extralight        | 200             | Tailwind font weight name for the \"200\" CSS value\n| light             | 300             | Tailwind font weight name for the \"300\" CSS value\n| medium            | 500             | Tailwind font weight name for the \"500\" CSS value\n| semibold          | 600             | Tailwind font weight name for the \"600\" CSS value\n| extrabold         | 800             | Tailwind font weight name for the \"800\" CSS value\n| black             | 900             | Tailwind font weight name for the \"900\" CSS value\n| 'value1 value2'   | value1 value2   | Specifying a font weight range\n| [value1, value2]  | value1 value2   | Specifying a font weight range\n\nHere's examples of how the fontWeight may be defined:\n\n```js\n{\n    fontWeight: 77,\n    // - or -\n    fontWeight: 'thin',\n    // - or -\n    fontWeight: 'normal',\n    // - or -\n    fontWeight: ['light', 900],\n};\n```\n\nThis will produce the following CSS:\n\n```css\n@font-face {\n    font-weight: 77;\n    /* or */\n    font-weight: 100;\n    /* or */\n    font-weight: normal;\n    /* or */\n    font-weight: 300 900;\n}\n```\n\n### External styles\n\nFont faces can be extracted, parsed and processed from any valid URL that exposes CSS styles. This feature is usefull for when you would like to locally host font files provided by services like Google fonts.\n\n#### Defining the URL\n\nTo fetch external styles, the plugin will expect a URL which can be passed in as a string, object or an array of either or both.\n\nHere's examples of how the URL may be specified:\n\n```js\n{\n    fontFace: 'https://fonts-provider.com/Montserrat.css',\n    // - or -\n    fontFace: [\n        'https://fonts-provider.com/Montserrat.css',\n        'https://fonts-provider.com/Mulish.css',\n    ],\n    // - or -\n    fontFace: { url: 'https://fonts-provider.com/Montserrat.css' },\n    // - or -\n    fontFace: [\n        'https://fonts-provider.com/Lato.css',\n        { url: 'https://fonts-provider.com/Montserrat.css' },\n        { url: 'https://fonts-provider.com/Mulish.css' },\n    ],\n};\n```\n\nPlease keep in mind that when fetching external font faces the plugin will need to know **where to store** the retrieved files and **which path to set** to the font faces' `src: url(...)` property.\n\n#### `fontDir` \u0026 `fontPath`\n\nWhen fetching external font faces the `fontDir` \u0026 `fontPath` properties must be defined either when defining the URL as an object or as global config options.\n\nHere's examples of how they may be specified:\n\n```js\n{\n    theme: {\n        fontFace: [\n            // The `fontDir` \u0026 `fontPath` are provided by the plugin options below\n            'https://fonts-provider.com/Montserrat',\n\n            // The `fontDir` \u0026 `fontPath` are provided directly, thus overwriting the plugin options\n            {\n                url: 'https://fonts-provider.com/Mulish.css',\n                fontDir: './public/specific/Mulish/font/dir',\n                fontPath: '/specific/Mulish/font/path',\n            },\n        ],\n    },\n    plugins: [\n        require('@vicgutt/tailwindcss-font-face')({\n            fontDir: './public/fonts/Montserrat',\n            fontPath: '/fonts/Montserrat',\n        }),\n    ],\n};\n```\n\nThis will produce styles similar to:\n\n```css\n/* Montserrat font faces */\n\n@font-face {\n    font-family: 'Montserrat';\n    font-style: normal;\n    font-weight: 200;\n    font-display: swap;\n    /* The font will be stored in './public/fonts/Montserrat' */\n    src: url('/fonts/Montserrat/Montserrat-normal-200-a92506f0a66e014d41e9315248f2d01d.woff2') format('woff2');\n    /* ... */\n}\n/* ... */\n\n/* Mulish font faces */\n\n@font-face {\n    font-family: 'Mulish';\n    font-style: normal;\n    font-weight: 200;\n    font-display: swap;\n    /* The font will be stored in './public/specific/Mulish/font/dir' */\n    src: url('/specific/Mulish/font/path/Mulish-normal-200-b96bb1e6727bb1c10705054f2b14b625.woff2') format('woff2');\n    /* ... */\n}\n/* ... */\n```\n\n#### Defining request options\n\nThis plugin uses the [sync-request](https://github.com/ForbesLindesay/sync-request) library to make synchronous HTTP requests.\nSynchronous HTTP requests are necessary because TailwindCSS's plugin system lack async excecution support.\n\nAll of [sync-request's options](https://github.com/ForbesLindesay/sync-request#usage) may be defined by passing in a `request` key:\n\n```js\n{\n    fontFace: {\n        url: 'https://fonts-provider.com/Mulish.css',\n        request: {\n            // These are the default values defined in \"AbstractFontsProvider.ts\"\n            maxRedirects: 5,\n            timeout: 5000,\n            retry: true,\n            maxRetries: 3,\n            retryDelay: 1,\n            headers: {\n                'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36',\n            },\n        },\n    },\n};\n```\n\nSome services like Google Fonts may determine which font faces to serve based on the browser. For that reason we spoof a Chrome 90 `user-agent` request header when fetching the resource.\n\n\u003c!-- ## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. --\u003e\n\n## Contributing\n\nIf you're interested in contributing to the project, please read our [contributing docs](https://github.com/VicGUTT/tailwindcss-font-face/blob/main/.github/CONTRIBUTING.md) **before submitting a pull request**.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicgutt%2Ftailwindcss-font-face","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvicgutt%2Ftailwindcss-font-face","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvicgutt%2Ftailwindcss-font-face/lists"}