{"id":13606098,"url":"https://github.com/levchak0910/css-media-splitter","last_synced_at":"2025-04-13T05:40:06.989Z","repository":{"id":221702406,"uuid":"755145209","full_name":"levchak0910/css-media-splitter","owner":"levchak0910","description":"The tool extracts all media at-rules into dedicated files and download them only when the user device matches the media query.","archived":false,"fork":false,"pushed_at":"2024-10-20T12:54:57.000Z","size":542,"stargazers_count":39,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T05:39:57.138Z","etag":null,"topics":["css","media-queries","nuxt","nuxt-module","vite","vite-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/css-media-splitter","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/levchak0910.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-02-09T14:14:20.000Z","updated_at":"2025-04-02T18:26:58.000Z","dependencies_parsed_at":"2024-02-19T18:12:43.349Z","dependency_job_id":"2f891f5a-0ff1-41e5-9c05-2322061e2f91","html_url":"https://github.com/levchak0910/css-media-splitter","commit_stats":null,"previous_names":["levchak0910/css-media-splitter"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levchak0910%2Fcss-media-splitter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levchak0910%2Fcss-media-splitter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levchak0910%2Fcss-media-splitter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/levchak0910%2Fcss-media-splitter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/levchak0910","download_url":"https://codeload.github.com/levchak0910/css-media-splitter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670507,"owners_count":21142897,"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":["css","media-queries","nuxt","nuxt-module","vite","vite-plugin"],"created_at":"2024-08-01T19:01:06.023Z","updated_at":"2025-04-13T05:40:06.663Z","avatar_url":"https://github.com/levchak0910.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Plugins"],"sub_categories":["Framework-agnostic Plugins"],"readme":"# css-media-splitter\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./assets/css-media-splitter.png\" alt=\"css-media-splitter logo\" height=\"200\"\u003e\n\u003c/p\u003e\n\nThe tool extracts all @media at-rules into dedicated files and download them only when the user device matches the media query.\n\nThis technique is the most valuable for mobile-first applications. It reduces the size of the CSS downloaded and increases the coverage ratio, so makes page loading faster and prevents a \"Reduce unused CSS code\" issue in the Lighthouse report.\n\nThe package exposes:\n\n- `css-media-splitter/plain` - handler for plain HTML \u0026 CSS projects. (maintainer: [@levchak0910](https://github.com/levchak0910))\n- `css-media-splitter/vite-plugin` - plugin for Vite based projects. (maintainer: [@levchak0910](https://github.com/levchak0910))\n- `css-media-splitter/nuxt-module` - module for Nuxt based projects. (maintainer: [@levchak0910](https://github.com/levchak0910))\n- `css-media-splitter/api` - helper functions for writing custom solutions. (maintainer: [@levchak0910](https://github.com/levchak0910))\n\n_Your favorite framework is not supported yet?_ - please refer to [CONTRIBUTION.md](./CONTRIBUTING.md#new-integration).\n\n## How it works\n\nThe tool is modifying the application by transforming HTML and CSS files. It was developed to be used on the final bundle after any build process was finished.\n\nThe algorithm:\n\n1. run through all CSS source files and extract all @media at-rules.\n2. remove all @media at-rules from CSS source files.\n3. write dedicated media files with all CSS rules grouped under one @media at-rule.\n4. generate manifest with relations between source files and media files.\n5. include the loader into all HTML files.\n\n_source file_ in scope of this tool equals to a **compiled CSS or HTML file** from your **final bundle**. Please, don't confuse with the file you actually work with.\n\n## Usage\n\n### Install the package\n\n```bash\nnpm i -D css-media-splitter\n```\n\n```bash\nyarn add -D css-media-splitter\n```\n\n```bash\npnpm add -D css-media-splitter\n```\n\n### Plain app\n\n```ts\nimport processCssMediaSplitter from \"css-media-splitter/plain\"\n\nconst result = await processCssMediaSplitter({ distDir: \"dist\" })\n```\n\nUse `result` which contain `manifest`, `loader` and `report` depending on the project setup.\n\nExample could be found in [playground](./playground/plain/media-splitter.ts).\n\n### Vite\n\n```ts\n// vite.config.ts\nimport { defineConfig } from \"vite\"\nimport VitePluginCssMediaSplitter from \"css-media-splitter/vite-plugin\"\n\nexport default defineConfig({\n  plugins: [\n    VitePluginCssMediaSplitter(),\n  ],\n})\n```\n\nExamples could be found for:\n\n- no framework app - [vite playground](./playground/vite/vite.config.ts)\n- VUE SPA app - [vue-spa playground](./playground/vue-spa/vite.config.ts)\n- VUE SSR app - [vue-ssr playground](./playground/vue-spa/vite.config.ts)\n\n### Nuxt\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: [\"css-media-splitter/nuxt-module\"],\n})\n```\n\nExample could be found in [playground](./playground/nuxt/nuxt.config.ts)\n\n### Options\n\n#### distDir\n\nAvailable in: `plain`\n\nPath to `dist` folder. Should be an absolute fs path or the folder name relative to the root folder.\n\nIn `vite-plugin` and `nuxt-module` is set based on vite/nuxt config respectively.\n\n#### mediaFileMinSize\n\nAvailable in: `plain`, `vite-plugin`, `nuxt-module`\n\nUse this option to define how large media file content should be, so it will be extract into a dedicated file.\n\nThis option is useful when media file content is small and it will take more space in the loader manifest than having it in the CSS source file.\n\nBy default equals to **100** (experimentally calculated, _not recommended_ to set a smaller size).\n\n**In Vite project**: `vite.config.ts`\n\n```ts\n{\n  plugins: [ VitePluginCssMediaSplitter({ mediaFileMinSize: 250 }) ],\n}\n```\n\n**In Nuxt project**: `nuxt.config.ts`\n\n```ts\n{\n  modules: [ [\"css-media-splitter/nuxt-module\", { mediaFileMinSize: 250 }] ],\n}\n```\n\n## Internals\n\n### Loader\n\nBy default, the loader will be included before the first `link`/`style`/`script` with the src path ends with `.css` or `.js` extension.\n\nIn some scenarios it is not relevant, then you can put comment `\u003c!-- css-media-splitter:loader --\u003e` in place before any `link`/`style`/`script` is defined and the comment will be replaced automatically.\n\nExample in vue-ssr playground - [comment](./playground/vue-ssr/index.html) on line 7.\n\nWhen the comment is not the case too, the loader can be inserted programmatically using functions from `css-media-splitter/api`.\n\nExample in nuxt-module - [nuxt.hook \"close\"](./src/integrations/nuxt-module.ts) on line 42.\n\n## Credits\n\n- [starter-vite-plugin](https://github.com/elonehoo/starter-vite-plugin) - starter template ([@elonehoo](https://github.com/elonehoo))\n- [postcss-extract-media-query](https://github.com/SassNinja/postcss-extract-media-query) - original idea ([@SassNinja](https://github.com/SassNinja))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevchak0910%2Fcss-media-splitter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flevchak0910%2Fcss-media-splitter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flevchak0910%2Fcss-media-splitter/lists"}