Start Styling with Gulp and Sass

Last modified: October 12, 2023

1 Introduction

You can use Gulp to watch the files for any changes you make when styling with Sass. Gulp triggers auto-refresh by default so that your changes are immediately visible in the browser.

This how-to teaches you how to do the following:

  • Set up the Gulp project
  • Run Gulp

2 Prerequisites

Before starting this how-to, make sure you have completed the following prerequisites:

3 Setting Up the Gulp Project

To set up the Gulp project, follow these steps:

  1. Download gulp.zip from mendix/ux-theming.

  2. Unzip the folder into your project’s root folder.

  3. In your terminal, go to your project root folder by typing cd, then drag your root file into the terminal. Please note that if you do this on Windows and you encounter errors with installing the dependencies, open your CMD or PowerShell as Administrator.

  4. Install the dependencies by typing npm install:

4 Running Gulp

To run Gulp, follow these steps:

  1. You should still be in your root if you just finished the installation, so type npm run dev in your root.

  2. Make sure your Mendix project is running.

  3. For a quick test to see if everything is working, open theme/styles/sass/custom/_custom-variables.scss and type body{ background-color: red; }. Your background will then be a beautiful red:

And that’s it! Now you are ready to start styling your Mendix app with Sass.

5 Development and Production

When running npm run dev, Sass will compile the CSS files unminified and with source-mapping. This helps in debugging the styling, as a modern browser will point to the .scss file where a rule is specified.

When using this in production, you should run npm run build before committing and deploying. This will disable source-mapping and will minify the CSS files to minimize the file size.

6 Developer Portal Apps

When you use this setup in a collaborative app, please note that you will need to add the node_modules folder to the SVN ignore. This folder is generated by running npm install (as described in the Installing Gulp) section) and contains too many files. It is important not to forget this step!

If you have TortoiseSVN installed, right-click the node_modules folder and select TortoiseSVN > Add to ignore list:

7 Troubleshooting

If you encounter issues using this setup, please read the Troubleshooting section in the GitHub repo documentation. If this does not resolve your issue, please create a new GitHub issue.

8 Read More