{"id":22423382,"url":"https://github.com/prantlf/grunt-embed-fonts","last_synced_at":"2025-08-01T07:32:21.246Z","repository":{"id":35378214,"uuid":"39641447","full_name":"prantlf/grunt-embed-fonts","owner":"prantlf","description":"Embeds webfont files to CSS stylesheets as base64-encoded data URIs to prevent CORS problems","archived":false,"fork":false,"pushed_at":"2023-06-05T07:31:59.000Z","size":245,"stargazers_count":10,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-08T09:53:36.185Z","etag":null,"topics":["cors","font-files","grunt-task","stylesheets","webfonts"],"latest_commit_sha":null,"homepage":null,"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/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2015-07-24T15:21:13.000Z","updated_at":"2023-08-17T04:35:14.000Z","dependencies_parsed_at":"2024-06-18T21:37:12.076Z","dependency_job_id":"bc283e3b-c334-49a8-bef8-da03a556b00a","html_url":"https://github.com/prantlf/grunt-embed-fonts","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrunt-embed-fonts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrunt-embed-fonts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrunt-embed-fonts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fgrunt-embed-fonts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/grunt-embed-fonts/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228348371,"owners_count":17905899,"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":["cors","font-files","grunt-task","stylesheets","webfonts"],"created_at":"2024-12-05T18:10:55.588Z","updated_at":"2024-12-05T18:10:57.866Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# grunt-embed-fonts\n\n[![Latest version](https://img.shields.io/npm/v/grunt-embed-fonts)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/grunt-embed-fonts)\n](https://www.npmjs.com/package/grunt-embed-fonts)\n[![Coverage](https://codecov.io/gh/prantlf/grunt-embed-fonts/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/grunt-embed-fonts)\n\nThis module provides a grunt multi-task injecting content of font files into\nstylesheets using data URIs.\n\nWhen you develop a HTML5 component, your styling may include special fonts.\nIf the page, which hosts your component has not the same origin, the server\nhas to include the CORS headers in the response with the font file\n(`Access-Control-Allow-Origin: *` at least) according to the\n[W3C Font fetching requirements].  You should always try to\nconfigure the web server to do it to get the best performance.  If you\ncannot, you can embed the fonts in the CSS files by this task, but the\nsize of the base64-encoded fonts for the page to load will be circa 35%\ngreater.  Additionally, the browser will load all fonts immediately with\nthe stylesheet, otherwise only the needed font faces and formats would be\ndownloaded.\n\nFrom version 0.4.0 on, MIME types used by default comply with [IANA] and\n[W3C WOFF] font MIME type specifications.  If you need MIME types generated\nby previous versions (either all types as \"font/{file ext}\" or all types\nas \"application/x-font-{file ext}\"), look at options `fontMimeType` and\n`xFontMimeType` below.\n\n## Installation\n\nYou need [node \u003e= 6][node], [npm] and [grunt \u003e= 0.4][Grunt] installed\nand your project build managed by a [Gruntfile] with the necessary modules\nlisted in [package.json].  If you haven't used Grunt before, be sure to\ncheck out the [Getting Started] guide, as it explains how to create a\nGruntfile as well as install and use Grunt plugins.  Once you're familiar\nwith that process, you may install this plugin with this command:\n\n```shell\n$ npm install grunt-embed-fonts --save-dev\n```\n\n## Configuration\n\nAdd the `embedFonts` entry with the embed-fonts task configuration to the\noptions of the `grunt.initConfig` method:\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    all: {\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\nThe configuration consists of key-value pairs with the output stylesheet\npath as a key pointing to the input stylesheet file.\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(fonts/test.woff) format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/font-woff;base64,ZmlsZTgK\") format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nMIME types are assigned to font files by their file extension according\nto the following table:\n\n| File ext. | MIME Type                     | Since         | Note                                |\n| --------- | ----------------------------- | ------------- | ----------------------------------- |\n| .eot      | application/vnd.ms-fontobject | December 2005 |                                     |\n| .otf      | application/font-sfnt         | March 2013    | earlier application/x-font-opentype |\n| .svg      | image/svg+xml                 | August 2011   |                                     |\n| .ttf      | application/font-sfnt         | March 2013    | earlier application/x-font-truetype |\n| .woff     | application/font-woff         | January 2013  |                                     |\n| .woff2    | font/woff2                    | March 2016    | proposed by W3C                     |\n\nSee summarizing post at [Stack Overflow] and [IANA] with [W3C WOFF]\nspecifications for more information.\n\n### Options\n\n#### fontMimeType\nType: `Boolean`\nDefault value: `false`\n\nForce using \"font/...\" MIME Type in the embedded font face\ndefinition instead of the latest IANA/W3C recommendation.\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    old: {\n      options: {\n        fontMimeType: true\n      },\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(fonts/test.woff) format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:font/woff;base64,ZmlsZT...\") format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\n#### xFontMimeType\nType: `Boolean`\nDefault value: `false`\n\nForce using \"application/x-font-...\" MIME Type in the embedded font face\ndefinition instead of the latest IANA/W3C recommendation.\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    old: {\n      options: {\n        xFontMimeType: true\n      },\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(fonts/test.woff) format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/x-font-woff;base64,ZmlsZT...\") format(\"woff\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\n#### mimeTypeOverrides\nType: `Object`\nDefault value: `{}`\n\nOverride a MIME typ assignments for one or more specific file extensions\nto use the value specified in the key-value pair of the options object.\n\nThis option has the highest priority; `fontMimeType`, `xFontMimeType`\nand the default MIME type assignment will not apply for the specified file\nextensions.  File extesions not specified by `mimeTypeOverrides` will\nbe processed by usual rules (first by checking `fontMimeType`, then by\nchecking `xFontMimeType` and finally by the choosing the preferred MIME\ntype according to the latest specifications and drafts.)\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    old: {\n      options: {\n        mimeTypeOverrides: {\n          otf: 'application/x-font-opentype'\n        }\n      },\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url('fonts/test.woff') format(\"woff\")\n       url(fonts/test.otf) format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/font-woff;base64,ZmlsZT...\") format(\"woff\"),\n       url(\"data:application/x-font-opentype;base64,ZmlsZT...\") format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\n#### applyTo\nType: `array`\nDefault value: `['eot','svg','ttf','otf','woff','woff2']`\n\nOnly embed specific MIME types.\n\nThe benefit of @font-face is that it allows the browser to choose which\nfont-type to use. In some cases it is beneficial to embed only the most\ncommon MIME types and have the other files as a fall-back.\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    old: {\n      options: {\n        applyTo: ['woff']\n      },\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/font-woff;base64,ZmlsZT...\") format(\"woff\"),\n       url(fonts/test.otf) format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/font-woff;base64,ZmlsZT...\") format(\"woff\"),\n       url(fonts/test.otf) format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\n#### only\nType: `array`\nDefault value: `[]`\n\nOnly embed fonts with a name that match any of the RegExps provided.\n\nIf you only want to embed some of your fonts, provide an array of RegExps that match their filenames.\n\n```js\ngrunt.initConfig({\n  embedFonts: {\n    old: {\n      options: {\n        only: [/(?\u003c!skip-)font\\d+/]\n      },\n      files: {\n        'dist/css/style.css': ['src/css/style.css']\n      }\n    }\n  }\n});\n```\n\nAn example from the input stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(fonts/font12.woff) format(\"woff\"),\n       url(fonts/skip-font13.otf) format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\nAn example from the generated output stylesheet:\n\n```css\n@font-face {\n  font-family: 'Test';\n  src: url(\"data:application/font-woff;base64,ZmlsZT...\") format(\"woff\"),\n       url(fonts/skip-font13.otf) format(\"opentype\");\n  font-weight: 400;\n  font-style: normal;\n}\n```\n\n### Loading\n\nLoad the plugin in `Gruntfile.js`:\n\n```javascript\ngrunt.loadNpmTasks('grunt-embed-fonts');\n```\n\n## Build\n\nCall the `embedFonts` task:\n\n```shell\n$ grunt embedFonts\n```\n\nor integrate it to your build sequence in `Gruntfile.js`:\n\n```js\ngrunt.registerTask('default', ['embedFonts', ...]);\n```\n\n## Notes\n\nThis task replaces `url(...)` expressions in `@font-face {...}` styles only.\nCommented out styles are processed too.  Paths to the font files are expected\nto be relative to the stylesheet file path.  Already embedded fonts or fonts\nnot in the local file system are ignored.\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding\nstyle.  Add unit tests for any new or changed functionality. Lint and test\nyour code using Grunt.\n\n## License\n\nCopyright (c) 2015-2022 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[node]: http://nodejs.org\n[npm]: http://npmjs.org\n[package.json]: https://docs.npmjs.com/files/package.json\n[Grunt]: https://gruntjs.com\n[Gruntfile]: http://gruntjs.com/sample-gruntfile\n[Getting Gtarted]: https://github.com/gruntjs/grunt/wiki/Getting-started\n[W3C Font fetching requirements]: http://www.w3.org/TR/css-fonts-3/#font-fetching-requirements\n[IANA]: http://www.iana.org/assignments/media-types/media-types.xhtml\n[W3C WOFF]: https://www.w3.org/TR/WOFF/#appendix-b\n[Stack Overflow]: http://stackoverflow.com/a/20723357/623816\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fgrunt-embed-fonts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fgrunt-embed-fonts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fgrunt-embed-fonts/lists"}