{"id":48462385,"url":"https://github.com/hyva-themes/hyva-modules-tailwind-js","last_synced_at":"2026-04-07T02:31:59.603Z","repository":{"id":41392519,"uuid":"482042230","full_name":"hyva-themes/hyva-modules-tailwind-js","owner":"hyva-themes","description":"Hyvä-themes TailwindCSS utility functions","archived":false,"fork":false,"pushed_at":"2026-03-18T15:06:43.000Z","size":722,"stargazers_count":11,"open_issues_count":1,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-03-19T05:37:54.238Z","etag":null,"topics":["css-properties","design-tokens","tailwindcss","tailwindcss-v3","tailwindcss-v4"],"latest_commit_sha":null,"homepage":"https://hyva.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"osl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyva-themes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-04-15T17:57:48.000Z","updated_at":"2026-03-18T15:07:00.000Z","dependencies_parsed_at":"2026-02-05T10:02:10.443Z","dependency_job_id":null,"html_url":"https://github.com/hyva-themes/hyva-modules-tailwind-js","commit_stats":{"total_commits":11,"total_committers":1,"mean_commits":11.0,"dds":0.0,"last_synced_commit":"85dc1dd4dbbb12fbef1f7238b2e0ecb4cad60b92"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/hyva-themes/hyva-modules-tailwind-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyva-themes%2Fhyva-modules-tailwind-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyva-themes%2Fhyva-modules-tailwind-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyva-themes%2Fhyva-modules-tailwind-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyva-themes%2Fhyva-modules-tailwind-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyva-themes","download_url":"https://codeload.github.com/hyva-themes/hyva-modules-tailwind-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyva-themes%2Fhyva-modules-tailwind-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31498069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"online","status_checked_at":"2026-04-07T02:00:07.164Z","response_time":105,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-properties","design-tokens","tailwindcss","tailwindcss-v3","tailwindcss-v4"],"created_at":"2026-04-07T02:31:57.802Z","updated_at":"2026-04-07T02:31:59.598Z","avatar_url":"https://github.com/hyva-themes.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyvä Themes Tailwind Utilities\n\n[![Go to hyva.io](https://img.shields.io/badge/hyva.io-0A23B9)](https://hyva.io)\n[![CI](https://img.shields.io/github/actions/workflow/status/hyva-themes/hyva-modules-tailwind-js/test.yml?label=\u0026branch=main\u0026logo=github\u0026color=0A23B9\u0026labelColor=2b1c2c)](https://github.com/hyva-themes/hyva-modules-tailwind-js/actions)\n[![Version](https://img.shields.io/npm/v/%40hyva-themes%2Fhyva-modules?label=\u0026logo=npm\u0026color=0A23B9\u0026labelColor=2b1c2c)](https://www.npmjs.com/package/@hyva-themes/hyva-modules)\n[![License](https://img.shields.io/github/license/hyva-themes/hyva-modules-tailwind-js?color=004d32\u0026labelColor=2b1c2c)](https://github.com/hyva-themes/hyva-modules-tailwind-js/blob/main/LICENSE.md)\n\nThis NPM package is meant to be used with an installation of Hyvä.\nIf you're not sure what Hyvä is, please check out [hyva.io](https://www.hyva.io/) to learn more.\n\n## Installation\n\n\u003e [!NOTE]\n\u003e If you are using Hyvä 1.1.14 or newer, this package is already included in your `package.json` file by default.\n\nYou can install `hyva-modules` via `npm` or other Node-based package managers like `pnpm`:\n\n```sh\nnpm install @hyva-themes/hyva-modules\n```\n\n## Usage\n\nThis plugin provides multiple helper functions and Node scripts. Some are built for Tailwind CSS v4, and others are kept for backwards compatibility with Tailwind CSS v3.\n\nBelow is a list of each of these functions and their use cases.\n\n## Node Commands for Creating CSS for TailwindCSS\n\nThis solution makes our code more future-proof since we don't rely on any Tailwind CSS or PostCSS logic.\nMaking it independent of the bundler or a compiler allows us and you to use it with any stack.\n\nThis has been built for Tailwind v4 support,\nsince Tailwind v4 no longer has a JavaScript configuration and only CSS can be used.\n\n### `hyva-init`\n\nThis command creates a `hyva.config.json` in the theme folder next to `package.json`.\nThis file is used to configure the other `hyva-*` commands.\n\nTo run it, use: `npx hyva-init`.\n\n### `hyva-tokens`\n\nThis command creates a `generated/hyva-tokens.css` from a design token input.\n\nTo run it, use: `npx hyva-tokens`.\n\nBy default, this will look for a `design.tokens.json`,\nbut if you use **Figma**, you can configure it in `hyva.config.json` to use this file instead:\n\n```json\n{\n    \"tokens\": {\n        \"src\": \"acme.figma-tokens.json\",\n        \"format\": \"figma\"\n    }\n}\n```\n\nSince the format of Figma is diffrent, you need to also pass the `format` key with the value `figma`.\n\nIf you only need a few simple tokens, you can also create the tokens directly in `hyva.config.json`:\n\n```json\n{\n    \"tokens\": {\n        \"values\": {\n            \"colors\": {\n                \"primary\": {\n                    \"lighter\": \"oklch(62.3% 0.214 259.815)\",\n                    \"DEFAULT\": \"oklch(54.6% 0.245 262.881)\",\n                    \"darker\": \"oklch(37.9% 0.146 265.522)\"\n                }\n            }\n        }\n    }\n}\n```\n\nBy default, `generated/hyva-tokens.css` will be created using `@theme` as the CSS selector, which is the Tailwind v4 syntax.\nYou can change the `cssSelector` to anything you want via `tokens.cssSelector`.\nFor example, use `:root` for Tailwind v3 compatibility:\n\n```json\n{\n    \"tokens\": {\n        \"cssSelector\": \":root\"\n    }\n}\n```\n\nYou can also customize the dark mode wrapper used for dark tokens with `tokens.mediaDark`.\nIt accepts either a CSS `@media` rule or a CSS selector, and defaults to `@media (prefers-color-scheme: dark)`.\nFor example, to use a class-based dark mode strategy:\n\n```json\n{\n    \"tokens\": {\n        \"mediaDark\": \".dark\"\n    }\n}\n```\n\nAfter this, you can import this file into your Tailwind CSS like any other CSS file.\n\n### `hyva-sources`\n\nThis is the replacement for `mergeTailwindConfig` and `postcssImportHyvaModules` in Tailwind v4 projects.\nThis command will create a `generated/hyva-source.css` in your project based on the Hyvä-compatible modules.\n\nTo run it, use: `npx hyva-sources`.\n\nThis uses the same `app/etc/hyva-themes.json` file as `mergeTailwindConfig` and `postcssImportHyvaModules`\nand creates a CSS file using the Tailwind v4 syntax for importing and sourcing the module files.\n\nSince this is now handled by this command, we have moved the exclusion of modules to `hyva.config.json`.\n\nJust as with `postcssImportHyvaModules`, you provide a list of modules you want to exclude.\n\nSince we have a bit more freedom, this command is not just for Hyvä-compatible modules.\nYou can even include extra paths. For example,\nyou don't need to include the parent theme manually; you can let this command handle that for you.\n\nHere is an example config where you can see the exclude and include options in action:\n\n```json\n{\n    \"tailwind\": {\n        \"include\": [\n            { \"src\": \"app/code/Acme/hyva-module\" },\n            { \"src\": \"vendor/hyva-themes/magento2-default-theme\" }\n        ],\n        \"exclude\": [\n            { \"src\": \"vendor/hyva-themes/magento2-hyva-checkout/src\" }\n        ]\n    }\n}\n```\n\nIf you want to keep a module's `@source` for Tailwind class scanning but skip its CSS imports, add `keepSource: true` to the exclude entry:\n\n```json\n{\n    \"tailwind\": {\n        \"exclude\": [\n            { \"src\": \"vendor/hyva-themes/magento2-hyva-checkout/src\", \"keepSource\": true }\n        ]\n    }\n}\n```\n\nBy default, module CSS files are resolved from the `view/frontend` area. You can change this with `tailwind.area` — for example, to target an admin theme:\n\n```json\n{\n    \"tailwind\": {\n        \"area\": \"adminhtml\"\n    }\n}\n```\n\nBy default, external modules from `hyva-themes.json` are automatically included. You can disable this with `tailwind.includeExternalModules: false` to use only the modules listed under `tailwind.include`:\n\n```json\n{\n    \"tailwind\": {\n        \"includeExternalModules\": false,\n        \"include\": [\n            { \"src\": \"app/code/Acme/HyvaModule\" }\n        ]\n    }\n}\n```\n\n## CSS Defaults\n\nThis package provides several optional CSS modules that offer default styling for common HTML elements.\nThey are optimized for TailwindCSS v4 and Hyvä Themes and serve as lightweight alternatives to official TailwindCSS plugins.\n\nTo use a module, add the corresponding `@import` rule to your stylesheet.\n\n```css\n/* Import all modules at once */\n@import \"@hyva-themes/hyva-modules/css\";\n```\n\nAlternatively, you can import modules individually as needed.\n\n### Prose\n\nA lightweight, unopinionated alternative to the `@tailwindcss/typography` plugin.\nIt provides sensible typographic defaults for long-form content (like CMS blocks) without imposing specific colors or a `max-width`.\n\n```css\n@import \"@hyva-themes/hyva-modules/css/prose.css\";\n```\n\n### Forms\n\nA minimal alternative to the `@tailwindcss/forms` plugin, providing clean, basic styles for form elements.\n\n```css\n@import \"@hyva-themes/hyva-modules/css/forms.css\";\n```\n\n### Fallback\n\nThis module restores utility classes from older TailwindCSS versions (v2/v3) that have been removed in v4.\nIt ensures backward compatibility with older Hyvä compatibility modules and helps prevent compilation errors during upgrades.\n\n```css\n@import \"@hyva-themes/hyva-modules/css/fallback.css\";\n```\n\n## Tailwind v3\n\nThe following utilities are for **Tailwind v2** and **v3** projects. If you are on Tailwind v4, use `hyva-sources` and `hyva-tokens` instead.\n\n### `mergeTailwindConfig`\n\nThis function is used in **Tailwind v2** and **v3** for merging Tailwind configurations from Hyvä-compatible modules into your theme.\n\nTo use this module, import `mergeTailwindConfig` into your `tailwind.config.js` and wrap the exported module object in this function:\n\n```js\nconst { mergeTailwindConfig } = require('@hyva-themes/hyva-modules');\n\nmodule.exports = mergeTailwindConfig({\n  // Your theme's Tailwind config here...\n});\n```\n\nFor more information on Tailwind merging,\nplease read our documentation at [docs.hyva.io](https://docs.hyva.io/hyva-themes/compatibility-modules/tailwind-config-merging.html).\n\n### `postcssImportHyvaModules`\n\nThis is complementary to `mergeTailwindConfig`, but for CSS.\n\nTo use this module, import `postcssImportHyvaModules` into your `postcss.config.js` and include it in the list of plugins.\n\n\u003e [!IMPORTANT]\n\u003e The `hyva-modules` plugin must be placed before the `postcss-import` and `tailwindcss/nesting` plugins.\n\n```js\nconst { postcssImportHyvaModules } = require('@hyva-themes/hyva-modules');\n\nmodule.exports = {\n    plugins: [\n        postcssImportHyvaModules,\n        require('postcss-import'),\n        // ...other PostCSS plugins\n    ],\n};\n```\n\nFor more information on CSS merging,\nplease read our documentation at [docs.hyva.io](https://docs.hyva.io/hyva-themes/compatibility-modules/tailwind-source-css-merging.html).\n\n### `twVar` and `twProps`\n\nYou can opt into CSS variables in your Tailwind configuration using the `twVar` and `twProps` functions.\n\nWith `twVar`, you can add a CSS variable to one or more Tailwind CSS tokens. For example:\n\n```js\nconst { twVar, mergeTailwindConfig } = require('@hyva-themes/hyva-modules');\nconst colors = require('tailwindcss/colors');\n\nmodule.exports = mergeTailwindConfig({\n    theme: {\n        extend: {\n            colors: {\n                primary: {\n                    lighter: twVar('primary-lighter', colors.blue['600']),\n                    DEFAULT: twVar('primary', colors.blue['700']),\n                    darker: twVar('primary-darker', colors.blue['800']),\n                },\n            },\n        },\n    },\n    // The rest of your Tailwind config...\n});\n```\n\nThis will render any Tailwind color utility class with the following CSS value:\n\n```css\n.bg-primary {\n    --tw-bg-opacity: 1;\n    background-color: color-mix(\n        in srgb,\n        var(--color-primary, #1d4ed8) calc(var(--tw-bg-opacity) * 100%),\n        transparent\n    );\n}\n```\n\n\u003e The method for handling opacity with all color syntaxes is based on the upcoming Tailwind CSS v4,\n\u003e which uses the CSS function `color-mix()` to make this possible.\n\u003e We have reused this to make the transition easier in the future.\n\nYou can change the value in your CSS or inline on the page with:\n\n```css\n:root {\n    --color-primary: hsl(20 80% 50%);\n}\n```\n\nIf you don't want to set this for each Tailwind CSS token, we also offer the `twProps` function.\nThis acts as a wrapper and uses the keys as the name for the CSS variable.\nFor example, if `twProps` wraps `primary \u003e lighter`, it will create the name `--primary-lighter`.\n\n\u003cdetails\u003e\n\u003csummary\u003eIn this example, we can create the same effect as \u003ccode\u003etwVar\u003c/code\u003e with less effort:\u003c/summary\u003e\n\n```js\nconst { twProps, mergeTailwindConfig } = require('@hyva-themes/hyva-modules');\nconst colors = require('tailwindcss/colors');\n\nmodule.exports = mergeTailwindConfig({\n    theme: {\n        extend: {\n            colors: twProps({\n                primary: {\n                    lighter: colors.blue['600'],\n                    DEFAULT: colors.blue['700'],\n                    darker: colors.blue['800'],\n                },\n            }),\n            textColors: {\n                primary: twProps({\n                    lighter: colors.blue['600'],\n                    DEFAULT: colors.blue['700'],\n                    darker: colors.blue['800'],\n                }, 'text-primary'),\n            },\n        },\n    },\n    // The rest of your Tailwind config...\n});\n```\n\n\u003c/details\u003e\n\n#### How to apply `twProps` as a wrapper without applying it to all Tailwind CSS tokens\n\nYou can use `Object.assign()` to split two groups inside any Tailwind config group (e.g., `colors`),\nso only one part gets the variables and the other part is left as is.\n\n\u003cdetails\u003e\n\u003csummary\u003eCode Sample\u003c/summary\u003e\n\n```js\nconst { twProps, mergeTailwindConfig } = require('@hyva-themes/hyva-modules');\nconst colors = require('tailwindcss/colors');\n\nmodule.exports = mergeTailwindConfig({\n    theme: {\n        extend: {\n            colors: Object.assign(\n                twProps({\n                    primary: {\n                        lighter: colors.blue['600'],\n                        DEFAULT: colors.blue['700'],\n                        darker: colors.blue['800'],\n                    },\n                    secondary: {\n                        lighter: colors.blue['100'],\n                        DEFAULT: colors.blue['200'],\n                        darker: colors.blue['300'],\n                    },\n                }),\n                {\n                    background: {\n                        lighter: colors.blue['100'],\n                        DEFAULT: colors.blue['200'],\n                        darker: colors.blue['300'],\n                    },\n                    green: colors.emerald,\n                    yellow: colors.amber,\n                    purple: colors.violet,\n                }\n            ),\n        },\n    },\n    // The rest of your Tailwind config...\n});\n```\n\n\u003c/details\u003e\n\nFor more information on `twVar` and `twProps`,\nplease read our documentation at [docs.hyva.io](https://docs.hyva.io/hyva-themes/working-with-tailwindcss/css-variables-plus-tailwindcss.html#method-2-using-the-new-twprops-and-twvar-functions).\n\n### License\n\nThis package is licensed under the **Open Software License (OSL 3.0)**.\n\n* **Copyright:** Copyright © 2020-present Hyvä Themes. All rights reserved.\n* **License Text (OSL 3.0):** The full text of the OSL 3.0 license can be found in the `LICENSE.txt` file within this package, and is also available online at [http://opensource.org/licenses/osl-3.0.php](http://opensource.org/licenses/osl-3.0.php).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyva-themes%2Fhyva-modules-tailwind-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyva-themes%2Fhyva-modules-tailwind-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyva-themes%2Fhyva-modules-tailwind-js/lists"}