{"id":14278795,"url":"https://github.com/rspack-contrib/rsbuild-plugin-rem","last_synced_at":"2025-04-14T10:20:23.652Z","repository":{"id":254106454,"uuid":"841473172","full_name":"rspack-contrib/rsbuild-plugin-rem","owner":"rspack-contrib","description":"An Rsbuild plugin to generate rem units from pixel units.","archived":false,"fork":false,"pushed_at":"2025-03-11T06:56:12.000Z","size":83,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-27T23:32:56.922Z","etag":null,"topics":["rsbuild","rsbuild-plugin","rspack"],"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/rspack-contrib.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-12T13:30:13.000Z","updated_at":"2025-03-25T13:38:34.000Z","dependencies_parsed_at":"2024-10-28T11:46:13.600Z","dependency_job_id":"82515c06-38b2-44ac-b107-0bf53a5dfe93","html_url":"https://github.com/rspack-contrib/rsbuild-plugin-rem","commit_stats":null,"previous_names":["rspack-contrib/rsbuild-plugin-rem"],"tags_count":2,"template":false,"template_full_name":"rspack-contrib/rsbuild-plugin-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-rem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-rem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-rem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rspack-contrib%2Frsbuild-plugin-rem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rspack-contrib","download_url":"https://codeload.github.com/rspack-contrib/rsbuild-plugin-rem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860007,"owners_count":21173342,"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":["rsbuild","rsbuild-plugin","rspack"],"created_at":"2024-08-23T07:01:04.434Z","updated_at":"2025-04-14T10:20:23.645Z","avatar_url":"https://github.com/rspack-contrib.png","language":"TypeScript","funding_links":[],"categories":["Plugins"],"sub_categories":["Rsbuild Plugins"],"readme":"# @rsbuild/plugin-rem\n\n\u003cp\u003e\n  \u003ca href=\"https://npmjs.com/package/@rsbuild/plugin-rem\"\u003e\n   \u003cimg src=\"https://img.shields.io/npm/v/@rsbuild/plugin-rem?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square\u0026colorA=564341\u0026colorB=EDED91\" alt=\"license\" /\u003e\n\u003c/p\u003e\n\nEnglish | [简体中文](./README.zh-CN.md)\n\nThe Rem plugin implements the rem adaptive layout for mobile pages, allowing the font size to be dynamically adjusted according to the screen size, making web pages adaptively displayed on screens of different sizes.\n\nThe plugin provides the following capabilities:\n\n- Integrates [postcss-pxtorem](https://npmjs.com/package/postcss-pxtorem) to convert the `px` units in CSS to `rem`.\n- Inserts runtime code into the HTML template to set the fontSize of the root element.\n\n## Usage\n\nInstall:\n\n```bash\nnpm add @rsbuild/plugin-rem -D\n```\n\nAdd plugin to your `rsbuild.config.ts`:\n\n```ts\n// rsbuild.config.ts\nimport { pluginRem } from \"@rsbuild/plugin-rem\";\n\nexport default {\n  plugins: [pluginRem()],\n};\n```\n\n## Options\n\n### Default Options\n\n```js\nconst defaultOptions = {\n  enableRuntime: true,\n  rootFontSize: 50,\n  screenWidth: 375,\n  rootFontSize: 50,\n  maxRootFontSize: 64,\n  widthQueryKey: \"\",\n  excludeEntries: [],\n  supportLandscape: false,\n  useRootFontSizeBeyondMax: false,\n  pxtorem: {\n    rootValue: 50,\n    unitPrecision: 5,\n    propList: [\"*\"],\n  },\n};\n```\n\n### Details\n\n### enableRuntime\n\n- **Type:** `boolean`\n- **Default:** `true`\n\nWhether to generate runtime code to calculate and set the font size of the root element.\n\n### inlineRuntime\n\n- **Type:** `boolean`\n- **Default:** `true`\n\nWhether to inline the runtime code to HTML. If set to `false`, the runtime code will be extracted into a separate `convert-rem.[version].js` file and output to the dist directory.\n\n### rootFontSize\n\n- **Type:** `number`\n- **Default:** `50`\n\nThe root element font size.\n\n```js\npluginRem({\n  rootFontSize: 30,\n});\n```\n\n### maxRootFontSize\n\n- **Type:** `number`\n- **Default:** `64`\n\nThe root element max font size.\n\n### widthQueryKey\n\n- **Type:** `string`\n- **Default:** `''`\n\nGet clientWidth from the url query based on `widthQueryKey`.\n\n### screenWidth\n\n- **Type:** `number`\n- **Default:** `375`\n\nThe screen width for UI design drawings (Usually, `fontSize = (clientWidth * rootFontSize) / screenWidth`).\n\n### excludeEntries\n\n- **Type:** `string[]`\n- **Default:** `[]`\n\nTo exclude some page entries from injecting runtime code, the item is the page entry name. It is usually used with `pxtorem.exclude`.\n\n```ts\n// rsbuild.config.ts\nimport { pluginRem } from \"@rsbuild/plugin-rem\";\n\nexport default {\n  source: {\n    entry: {\n      page1: \"./src/page1/index.tsx\",\n      page2: \"./src/page2/index.tsx\",\n    },\n  },\n  plugins: [\n    pluginRem({\n      excludeEntries: [\"page2\"],\n    }),\n  ],\n};\n```\n\n### supportLandscape\n\n- **Type:** `boolean`\n- **Default:** `false`\n\nUse height to calculate rem in landscape.\n\n### useRootFontSizeBeyondMax\n\n- **Type:** `boolean`\n- **Default:** `false`\n\nWhether to use `rootFontSize` when large than `maxRootFontSize`.\n\n### pxtorem\n\n- **Type:** `object`\n- **Default:**\n  - `rootValue`: Default is the same as `rootFontSize`\n  - `unitPrecision`: `5`\n  - `propList`: `['*']`\n\nCustomize the [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem#options) options.\n\n```js\npluginRem({\n  pxtorem: {\n    propList: [\"font-size\"],\n  },\n});\n```\n\n## Usage Guide\n\n### CSS conversion properties\n\nBy default, rootFontSize is 50. So the CSS styles value are converted according to the ratio of `1rem : 50px`.\n\n```css\n/* input */\nh1 {\n  margin: 0 0 16px;\n  font-size: 32px;\n  line-height: 1.2;\n  letter-spacing: 1px;\n}\n\n/* output */\nh1 {\n  margin: 0 0 0.32rem;\n  font-size: 0.64rem;\n  line-height: 1.2;\n  letter-spacing: 0.02rem;\n}\n```\n\nBy default, Rsbuild converts all CSS properties from px to rem. If you want to convert only the `font-size` property, you can setting `pxtorem.propList` is `['font-size']`.\n\n```ts\npluginRem({\n  pxtorem: {\n    propList: [\"font-size\"],\n  },\n});\n```\n\n### How to ignore some CSS properties converted to REM?\n\n[pxtorem.propList](https://github.com/cuth/postcss-pxtorem#options) in addition to specifying which attributes need to be converted, you also can specify which elements are not converted through `!`:\n\n```ts\npluginRem({\n  pxtorem: {\n    propList: [\"*\", \"!border-width\"], // not convert 'border-width'\n  },\n});\n```\n\nIf you only want some individual CSS properties not to be converted to REM, you can also refer to the following writing method:\n\n```css\n/* `px` is converted to `rem` */\n.convert {\n  font-size: 16px; // converted to 1rem\n}\n\n/* `Px` or `PX` is ignored by `postcss-pxtorem` but still accepted by browsers */\n.ignore {\n  border: 1px solid; // ignored\n  border-width: 2px; // ignored\n}\n```\n\nMore info about [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem#a-message-about-ignoring-properties).\n\n### Setting the page rootFontSize\n\nThe formula for calculating the font size of the page root element is:\n\n```\npageRootFontSize = clientWidth * rootFontSize / screenWidth\n```\n\nIn a mobile browser with a screen width of 390, the default value for rootFontSize is 50 and the screenWidth of the UI design is 375.\n\nThe calculated font size for the root element of the page is 52 (`390 * 50 / 375`).\n\nAt this point, 1 rem is 52px, 32px (0.64 rem) in the CSS style, the actual size in page is 33.28 px.\n\n```ts\npluginRem({\n  rootFontSize: 50,\n  screenWidth: 375,\n});\n```\n\n### Customize maxRootFontSize\n\nIn the desktop browser, the page rootFontSize obtained from the calculation formula is often too large. When the calculated result large than the maxRootFontSize, the maxRootFontSize will used as the page rootFontSize.\n\nIn the desktop browser with a screen width of 1920, the calculated rootFontSize is 349, which exceeds the default maxRootFontSize of 64. 64 is used as the current root element font value.\n\n```ts\npluginRem({\n  maxRootFontSize: 64,\n});\n```\n\n### How to get the rootFontSize value that is actually in effect on the page?\n\nThe actual rootFontSize in effect for the page is calculated dynamically based on the current page. It can be seen by printing `document.documentElement.style.fontSize` or obtained by `window.ROOT_FONT_SIZE`.\n\n### How to specify the actual rootFontSize value of the page?\n\nBy default, the actual rootFontSize of the page will be dynamically calculated based on the situation of the current page. If you want to specify the actual rootFontSize of the page, you can turn off the `enableRuntime` configuration and set it in [Custom HTML template](/config/html/template) and inject `document.documentElement.style.fontSize = '64px'` by yourself.\n\n```ts\nexport default {\n  html: {\n    template: \"./static/index.html\",\n  },\n  plugins: [\n    pluginRem({\n      enableRuntime: false,\n    }),\n  ],\n};\n```\n\n### How to determine if REM is in effect？\n\n1. CSS: Check the generated `.css` file to see if the value of the corresponding property is converted from px to rem.\n2. HTML: Open the Page Console to see if a valid value exists for `document.documentElement.style.fontSize`.\n\n## License\n\n[MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-rem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-rem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frspack-contrib%2Frsbuild-plugin-rem/lists"}