{"id":29170247,"url":"https://github.com/mendixlabs/ux-theming","last_synced_at":"2025-07-01T12:39:42.556Z","repository":{"id":41826141,"uuid":"46915468","full_name":"mendixlabs/ux-theming","owner":"mendixlabs","description":"Make UX theming in Mendix a lot easier","archived":false,"fork":false,"pushed_at":"2022-04-27T21:49:33.000Z","size":75,"stargazers_count":26,"open_issues_count":3,"forks_count":9,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-04-13T17:55:37.282Z","etag":null,"topics":["gulp","sass","ux"],"latest_commit_sha":null,"homepage":"","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/mendixlabs.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}},"created_at":"2015-11-26T09:02:48.000Z","updated_at":"2024-03-25T13:27:58.000Z","dependencies_parsed_at":"2022-08-11T18:40:24.048Z","dependency_job_id":null,"html_url":"https://github.com/mendixlabs/ux-theming","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/mendixlabs/ux-theming","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendixlabs%2Fux-theming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendixlabs%2Fux-theming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendixlabs%2Fux-theming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendixlabs%2Fux-theming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mendixlabs","download_url":"https://codeload.github.com/mendixlabs/ux-theming/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mendixlabs%2Fux-theming/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262964053,"owners_count":23391941,"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":["gulp","sass","ux"],"created_at":"2025-07-01T12:39:33.858Z","updated_at":"2025-07-01T12:39:42.465Z","avatar_url":"https://github.com/mendixlabs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gulp for Mendix theming\n\n\u003e **Note: With Mendix 8, we decided to go with a different tool: [Calypso](https://docs.mendix.com/howto/front-end/calypso). That is the officially supported tool. It will still be possible to do styling using ux-theming, but _it is not officially supported_. If you encounter problems using Gulp, please move to Calypso.**\n\nMake it [easier to develop Mendix themes](https://docs.mendix.com/howto/ux/style-with-gulp-and-sass), without the use of [Scout](https://docs.mendix.com/howto/ux/create-a-custom-theme-with-the-mendix-ui-framework) or [Koala](https://docs.mendix.com/howto/ux/setup-mendix-ui-framework-with-koala)\n\n[Using this with Mendix 8? Please read this](#mendix-8-caveats)\n\n## Prerequisites (only need to do this once)\n\nThe following things need to be installed:\n* [Node.js](https://nodejs.org/en/) **Please ensure you install the LTS version, 14.x.x. This is important!! It will fail on older versions*\n\nFor Windows it is *recommended* to install Node.js through `nvm-windows`, in order to avoid issues with acces rights. You can find a [Microsoft install guide here](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows#install-nvm-windows-nodejs-and-npm)\n\n## Installation (automated)\n\nRun `npx install-ux-theming` in your project folder (terminal like CMD or Powershell)\n\n## Installation (Manual)\n\n1.) Download the latest release (ZIP-file) [here](https://github.com/JelteMX/ux-grunt-theming/releases). **Do NOT download the source files, but choose Gulp.zip**\n\n2.) Unzip in your project root folder\n\n3.) Open a terminal and go to your project root folder.\n\n_If you do this on Windows and you encounter errors with installing the dependencies, open your CMD or Powershell as Administrator. This shouldn't happen if you installed Node.JS through NVM-Windows, see above_\n\n4.) Install dependencies using ``npm install``\n\n(**_If you use this for a Teamserver project, make sure you do not include node dependencies in you team-project: add the ``node_modules`` folder to your SVN ignore_**)\n\n## Usage\n\n* **default**\n\nWill compile your sass everytime you make a change\n\n```bash\n  npm run start\n```\n\n* **dev**\n\nWill run browsersync and watch your files\n\n```bash\n  npm run dev\n```\n\n* **build**\n\nBuilds a minified version of the CSS\n\n```bash\n  npm run build\n```\n\n### Tasks:\n\nThe **default** task will check your theme folder (check Gruntfile.js/Gulpfile.js for the location) and will:\n* copy changed .css files to your deployment folder\n* when there are changes detected in any ```.scss``` file, run sass and place them in the source folder (on which these files will be copied to deployment as well)\n\nThe **dev** task will do the same as default, but it will start your browser through a [Browsersync](http://www.browsersync.io/docs/grunt/) proxy. Any changes that you make in the css files will be automatically injected in your browser. You do not have to manually refresh your browser.\n\nThe **build** task will build all the CSS, minifying everything. This is **important** to do before committing the styling in the project. If you will use the default/dev task, it will keep the source mapping in the CSS, resulting in a huge filesize.\n\n## Modifying parameters\n\nThere are a few parameters that you can change. Open your ``Gruntfile.js`` or ``Gulpfile.js``, you can change these values at the top:\n\n* ``sourceStyleFolder``\n* ``deploymentStyleFolder``\n* ``proxyAddress``\n\nMake sure ``proxyAddress`` is pointed to your local deployment.\n\n## Troubleshooting\n\n### ``npm install`` fails\n\nMake sure you have the package.json and Gruntfile.js/Gulpfile.js in your root folder. Also, if there are errors installing (this can happen when you install the Gulp version), make sure you have administrator rights. See point 3 at Installation.\n\n### \"I started the dev task, but my ``localhost:3000`` keeps loading\"\n\nHave you pointed to the right local deployment address? Check the proxyAddress in your Gulp-/Gruntfile.js. This should correspond to the address of your local deployment.\n\n### \"I use the DEV task, but on reload it is missing styles\"\n\nThis is a common problem when you are using this in new Mendix Projects where it is using Deeplinks (e.g. http://localhost:3000/link/page). The reason for this is that the paths to the styles are relative in your HTML. Please check the following:\n\n* Open the 'index.html' (or the one that is used, for example 'index2.html')\n* In the ``\u003chead\u003e`` section you will find the links to stylesheets:\n\n```html\n  \u003clink rel=\"stylesheet\" href=\"lib/bootstrap/css/bootstrap.min.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"mxclientsystem/mxui/ui/mxui.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"css/custom.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"css/custom/custom.css?{{cachebust}}\"\u003e\n```\n\n* Make sure that any of these links to the stylesheets are prefixed with a ``/``, so it will always refer to the root:\n\n```html\n  \u003clink rel=\"stylesheet\" href=\"/lib/bootstrap/css/bootstrap.min.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"/mxclientsystem/mxui/ui/mxui.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"/css/custom.css?{{cachebust}}\"\u003e\n  \u003clink rel=\"stylesheet\" href=\"/css/custom/custom.css?{{cachebust}}\"\u003e\n```\n\nThis should fix your problem with missing stylesheets after a reload\n\n### \"I use the DEV task, but on reload I don't see any changes in Mendix 7\"\n\nThis happens when the pages have urls (e.g. `http://localhost:3000/p/page_name`) and the HTML page includes relative links to the CSS files.\n\nMendix 7 uses a `settings.json` in the theme folder to determine which style files it needs to include. Most likely this looks like this:\n\n```json\n...\n    \"cssFiles\": [\n        \"styles/css/lib/lib.css\",\n        \"styles/css/custom/custom.css\"\n    ],\n...\n```\n\nThe way to fix this issue is to add a slash in front of these files:\n\n```json\n...\n    \"cssFiles\": [\n        \"/styles/css/lib/lib.css\",\n        \"/styles/css/custom/custom.css\"\n    ],\n...\n```\n\n### \"I get the following error:\"\n\n``gulpInst.start.apply(gulpInst, toRun); TypeError: Cannot read property 'apply' of undefined``\n\nYour Gulp is outdated. Please run ``npm install gulp-cli -g`` again. Or use **npm**, see usage for 1.6.0 and newer.\n\n### Mendix 8 caveats\n\nWhen using UX-theming in Mendix 8, some issues might occur with an infinite loop or folders not being recognized. \n\nMost likely scenario is that the theme folder has changes. The new Mendix 8 structure (since Beta 3) has a distinct folder for web and for native. Make sure you set the following folders correctly in your Gulpfile:\n\n```js\n// What is the name of the style folder in this theme folder?\nvar sourceStyleFolder = 'theme/styles/web';\n\n// What is the name of the style folder in the deployment folder?\nvar deploymentStyleFolder = 'styles/web';\n```\n\nThis should fix most of the issues. If not, keep on reading.\n\nOther issues might occur with SVN and possible rewriting Gulpfile.js. A few things to try:\n\n- Remove node_modules, package.json, package-lock.json and Gulpfile.js. Replace them with a fresh copy downloaded here\n- Not only ignore node_modules, but also Gulpfile.js. This means you will have to add the Gulpfile to the project if you download it again or someone in your team is working on it\n- Make sure you use the latest LTS version (10.xx.x) of NodeJS\n\nOur current testing indicates it still works in Mendix 8, but might be less reliable. Above workarounds might work, they might not. We're also looking into updating the libraries, to make sure we fix any issues that might arise with that.\n\n## Done theming?\n\nIf you do not want the theming files to be part of the project (you can safely commit them, as long as you will add ``node_modules`` to **SVN Ignore**), you can clean your project folder by deleting:\n* ```package.json```\n* ```Gruntfile.js``` or ```Gulpfile.js```\n* ```node_modules``` folder\n\n## TODO\n\nNone\n\n## License\n\nThe MIT License (MIT)\nCopyright (c) 2021 Mendix\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmendixlabs%2Fux-theming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmendixlabs%2Fux-theming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmendixlabs%2Fux-theming/lists"}