{"id":16349448,"url":"https://github.com/jednano/postcss-font-pack","last_synced_at":"2025-07-10T02:38:00.210Z","repository":{"id":57328064,"uuid":"38900822","full_name":"jednano/postcss-font-pack","owner":"jednano","description":"PostCSS plugin to simplify font declarations by validating only configured font packs are used and adding fallbacks.","archived":false,"fork":false,"pushed_at":"2022-08-05T13:19:21.000Z","size":99,"stargazers_count":19,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-01T15:02:57.060Z","etag":null,"topics":["font","font-packs","postcss","postcss-plugin"],"latest_commit_sha":null,"homepage":null,"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/jednano.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}},"created_at":"2015-07-10T20:31:56.000Z","updated_at":"2024-05-30T08:38:42.000Z","dependencies_parsed_at":"2022-09-18T17:50:47.668Z","dependency_job_id":null,"html_url":"https://github.com/jednano/postcss-font-pack","commit_stats":null,"previous_names":["jedmao/postcss-font-pack"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jednano/postcss-font-pack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jednano%2Fpostcss-font-pack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jednano%2Fpostcss-font-pack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jednano%2Fpostcss-font-pack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jednano%2Fpostcss-font-pack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jednano","download_url":"https://codeload.github.com/jednano/postcss-font-pack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jednano%2Fpostcss-font-pack/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260109459,"owners_count":22960025,"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-packs","postcss","postcss-plugin"],"created_at":"2024-10-11T00:59:46.339Z","updated_at":"2025-07-10T02:38:00.189Z","avatar_url":"https://github.com/jednano.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postcss-font-pack\n\n\u003cimg align=\"right\" width=\"135\" height=\"95\"\n     title=\"Philosopher’s stone, logo of PostCSS\"\n     src=\"http://postcss.github.io/postcss/logo-leftp.png\"\u003e\n\n[![NPM version](http://img.shields.io/npm/v/postcss-font-pack.svg?style=flat)](https://www.npmjs.org/package/postcss-font-pack)\n[![npm license](http://img.shields.io/npm/l/postcss-font-pack.svg?style=flat-square)](https://www.npmjs.org/package/postcss-font-pack)\n[![Travis Build Status](https://img.shields.io/travis/jedmao/postcss-font-pack.svg)](https://travis-ci.org/jedmao/postcss-font-pack)\n[![codecov](https://codecov.io/gh/jedmao/postcss-font-pack/branch/master/graph/badge.svg)](https://codecov.io/gh/jedmao/postcss-font-pack)\n[![Dependency Status](https://gemnasium.com/badges/github.com/jedmao/postcss-font-pack.svg)](https://gemnasium.com/github.com/jedmao/postcss-font-pack)\n\n[![npm](https://nodei.co/npm/postcss-font-pack.svg?downloads=true)](https://nodei.co/npm/postcss-font-pack/)\n\n[PostCSS](https://github.com/postcss/postcss) plugin to simplify font declarations by validating only configured font packs are used, adding fallbacks and transpiling human-readable font declaration values into valid CSS.\n\n## Introduction\n\nDealing with fonts can be a pain, especially on teams where not everybody knows where to find the exact fonts they are allowed to use. As a result, mistakes are made, inconsistencies are introduced and maintenance becomes a nightmare. PostCSS Font Pack aims to solve this problem with configuration.\n\n## Configuration\n\nLet's start with the following assumptions:\n- We're using \"Times New Roman\" because it's a commonly used [web safe font](http://www.w3schools.com/cssref/css_websafe_fonts.asp). It also illustrates how to use fonts that need quotes in this plugin.\n- We've installed [Roboto](http://www.fontsquirrel.com/fonts/roboto?q%5Bterm%5D=roboto\u0026q%5Bsearch_check%5D=Y) and already setup its [@font-face](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face).\n\nThese fonts can be defined in JSON format. You might call it `font-packs.json`:\n\n```json\n{\n\t\"times\": {\n\t\t\"family\": [\"'Times New Roman'\", \"Times\", \"serif\"],\n\t\t\"propGroups\": [\n\t\t\t{},\n\t\t\t{\n\t\t\t\t\"weight\": [\"bold\", 700]\n\t\t\t}\n\t\t]\n\t},\n\t\"roboto\": {\n\t\t\"family\": [\"Roboto\", \"Arial\", \"sans-serif\"],\n\t\t\"propGroups\": [\n\t\t\t{\n\t\t\t\t\"style\": \"italic\",\n\t\t\t\t\"weight\": [\"light\", 300],\n\t\t\t\t\"stretch\": \"condensed\",\n\t\t\t\t\"variant\": \"small-caps\"\n\t\t\t}\n\t\t]\n\t}\n}\n```\n\nWith the above configuration, we can write our CSS using the [font shorthand property](https://developer.mozilla.org/en-US/docs/Web/CSS/font):\n\n```css\n.foo {\n\tfont: bold 1rem/1.2 times;\n}\n\n.bar {\n\tfont: light condensed italic 1rem/1.2 roboto;\n}\n```\n\nThis would transpile into the following:\n\n```css\n.foo {\n\tfont: 700 1rem/1.2 'Times New Roman', Times, serif;\n}\n\n.bar {\n\tfont: 300 condensed italic 1rem/1.2 Roboto, Arial, sans-serif;\n}\n```\n\nNotice the weight was changed from `bold` to `700` and from `light` to `300`. This came from the configuration's declaration value aliases, which were defined as `\"weight\": [\"bold\", 700]` and `\"weight\": [\"light\", 300]`, respectively. You can do this with any of the prop groups, but since `style: italic`, `stretch: condensed` and `variant: small-caps` are already understood by the browser, it only made sense to use an alias for the weight in this case. You could have just as well congired the weight as `\"weight\": 300`, but that's not as human-readable as `light`, which the browser doesn't understand.\n\nAlso, notice that fallback fonts were added to the `font-family`. This allows you to keep your syntax easy to read/write and let the plugin do the dirty work with configuration.\n\nYou don't have to use the font shorthand property. You can also write-out each declaration individually or you can use the [`postcss-nested-props`](https://github.com/jedmao/postcss-nested-props) plugin to enable a nested syntax. Just make sure you unwrap the nested with that plugin before you run this one.\n\n## Linting\n\nThis plugin also handles linting so you can sleep sound knowing that nobody is using fonts or combinations of font declarations that are not supported or otherwise go against the design of the site. The following rules would all throw the same error, \"pack not found\":\n\n```css\n.foo {\n\tfont-family: \"Futura PT\";\n}\n\n.bar {\n\tfont-family: roboto, sans-serif;\n}\n\n.baz {\n\tfont: light 1rem/1.2 roboto;\n}\n```\n\nEven though the `light` weight is found in your configuration, there is no font pack that uses `light` without also using `italic` and `condensed`. You have to use all three of them together to form a pack and to pass linting.\n\nAs you can see, this plugin will stop unsupported font declarations dead in their tracks.\n\n## Ignoring sections\n\nIf you need to ignore a specific declaration, but don't want to ignore the entire stylesheet, you can do so by _preceding the declaration_ with a special comment:\n\n```css\n.foo {\n\t/* postcss-font-pack: ignore-next */\n\tfont: \"Comic Sans\", cursive;\n}\n```\n\nThis will cause the linter to ignore **_only_** the very **_next_** selector.\n\nYou can also ignore ranges:\n\n```css\n/* postcss-font-pack: start-ignore */\n.foo {\n\tfont: \"Comic Sans\", cursive;\n\tfont-size: 38px;\n}\n/* postcss-font-pack: end-ignore */\n```\n\n## Installation\n\n```\n$ npm install postcss-font-pack\n```\n\n## Usage\n\n### JavaScript\n\n```js\npostcss([\n\trequire('postcss-font-pack')({\n\t\tpacks: require('./font-packs.json')\n\t})\n]);\n```\n\n### TypeScript\n\n```ts\nimport * as postcssFontPack from 'postcss-font-pack';\n\npostcss([\n\tpostcssFontPack({\n\t\tpacks: require('./font-packs.json')\n\t})\n]);\n```\n\n## Options\n\n### `ignoreDeclarations`\n\nType: `{ [prop: string]: string; }`\nRequired: `false`\nDefault: `undefined`\n\nA collection of declarations that you would like to ignore. These could be CSS hacks or something else that you really don't want throwing validation errors. Example below:\n\n```js\n{\n\tignoreDeclarations: [\n\t\t{ font: '0/0 serif' }\n\t]\n}\n```\n\n### `requireSize`\n\nType: `boolean`\nRequired: `false`\nDefault: `false`\n\nWhen `true`, an error will be thrown if you have a rule with one or more font declarations, but without a font size.\n\n```css\n.foo {\n\tfont-family: roboto;\n\t/* missing required font-size */\n}\n```\n\nRegardless of this option, if you have a rule with only a `font-size` specified you will get an error:\n\n```css\n.foo {\n\tfont-size: 1rem;\n\t/* font-size missing required family */\n}\n```\n\n### `packs`\n\nType: `Object`\nRequired: `true`\n\nAn object literal where the keys are slugified fonts and the values are font packs. Each font pack consists of a required `family` and an optional collection of property groups, named as `propGroups`.\n\n#### `pack.family`\n\nType: `string[]`\nRequired: `true`\n\nIf your font slug is `times`, this is where you would define the extended font name along with any fallbacks.\n\n_Note: If your font name requires quotes, you must add them yourself._\n\n#### `pack.propGroups`\n\nType: `PropGroup[]`\nRequired: `false`\n\nDefine the property combinations that can be used together to reference a font.\n\n##### `pack.propGroups[n]`\n\nType: `PropGroup`\n\nEach prop group may contain 0 or more of the following keys:\n- [`weight`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)\n- [`style`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style)\n- [`variant`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)\n- [`stretch`](https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch)\n\nEach value can be a `string` or a `string[]` with two values. The first value is a slugified value that you can type in your CSS to reference the associated key. The second value is what the first value will be transpiled into, so make sure they are CSS-valid. The `weight` values can additionally be numbers.\n\nIf an empty object is provided, this indicates that you want to support this font family with default browser values for weight, style, variant and stretch.\n\n_Note: If you don't include an empty object you will be unable to reference a family without also referencing additional properties._\n\n## Testing\n\nRun the following command:\n\n```\n$ npm test\n```\n\nThis will build scripts, run tests and generate a code coverage report. Anything less than 100% coverage will throw an error.\n\n### Watching\n\nFor much faster development cycles, run the following commands in 2 separate processes:\n\n```\n$ npm run build:watch\n```\n\nCompiles TypeScript source into the `./dist` folder and watches for changes.\n\n```\n$ npm run watch\n```\n\nRuns the tests in the `./dist` folder and watches for changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjednano%2Fpostcss-font-pack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjednano%2Fpostcss-font-pack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjednano%2Fpostcss-font-pack/lists"}