Using Gulp.js for your Mendix project

Designing your project in Mendix can be a lot more efficient using Gulp.js. In this article I will explain step-by-step how to automate your Mendix front-end workflow.

By the end of this article, you’ll have a workflow that:

  • Compiles Sass to CSS
  • Spins up a browser
  • Refreshes the browser automatically whenever you save a file
  • Copy automatically your styling changes within theme in the root folder to the styles folder in deployment

Installing Gulp.js and it’s modules

First, lets install Node.js and open its command prompt.

Node.js command prompt screen

Install Gulp by using the following command in the command line by typing: npm install gulp -g

The npm install command we've used here is a command that uses Node Package Manager (npm) to install Gulp onto your computer.

The -g flag in this command tells npm to install Gulp globally onto your computer, which allows you to use the gulp command anywhere on your system.

Now that you have Gulp installed, let’s start the configure Gulp for your Mendix project!

Go to your Mendix project folder and open the Node.js command prompt. Type cd but don’t press the return button yet. Drag and drop your project folder into to the command prompt. After that, press the return button.

Creating our project

Gulp works with a json and javascript file and node_modules. First we’re concentrating us to the json file. Go back to the command prompt and run npm init. You’ll get a lot of questions but skip them all by pressing the return button.

The npm init command will create a package.json file for your project which stores information about the project, like the dependencies used in the project (Gulp is an example of a dependency).

npm init will prompt you:

{
 “name”: “your mendix project name”,
 “version”: “1.0.0”,
 “description”: “”,
 “main”: “index.js”,
 “scripts”: {
 “test”: “echo \”Error: no test specified\” && exit 1"
 },
 “author”: “”,
 “license”: “ISC”
}

Once the package.json file is created, we can install Gulp into the project by using the following command: npm install gulp --save-dev.

Check the project folder when the command has finished executing. You should see that Gulp created a node_modules folder.

Working Mendix project folder

Gulp.js configuration for a Mendix project

Jelte Lagendijk, developer at Mendix, created a GIT repository where you’ll find Gulp as wel as Grunt files. In this article we’re using Gulp.

Normally you would create a gulpfile.js for your own project but Jelte Lagendijk (thanks!) created a configuration file custom made for a Mendix project. You can download all files from Jelte’s GIT repository or you can use mine by downloading the gulpfile.js and package.json clicking this link.

Unpack the zip and place both files in the root folder of your Mendix project (overwrite the previously created package.json). Open gulpfile.js with a code editor of your choice (I’m using Visual Studio Code). Now we’re setting up the gulpfile.js for your project.

At the top of the gulpfile.js you’ll find three things that you have to configure:

  • var sourceStyleFolder
  • var deploymentStyleFolder
  • var proxyAddress

The settings described above are the settings I’m using for my own Mendix project. The theme folder in the root folder is called ‘theme’. The name of my style folder in deployment is ‘styles’ and after running the Mendix project locally, my proxyaddress is 8089. After changing these settings to your own Mendix project, save it and you’re almost there!

Install extra node_modules

Time to install the modules we’re using to automate your Mendix front-end workflow! Go to the Node.js command prompt and install the modules using these npm commands:

  • npm install gulp-sass
  • npm install browser-sync
  • npm install path
  • npm install gulp-sourcemaps
Install node_modules globally

Let’s start the magic!

You’re all set! Run your Mendix project locally and if the Node.js command prompt is still open type in gulp dev and press return. A browser window will appear with your project and any changes you make in the sass files will automatically be injected into your browser. You do not have to manually refresh your browser. Also, you don’t have to use the styles folder in deployment anymore. All changes done in the root theme folder will automatically change in the deployment folder.

Done styling?

You’re all set and ready to commit your changes? Press the ctrl+c keys to stop your Gulp.js session. Select the gulpfile.js and package.json files and the node_modules folder and place them in a separate folder in your documents, desktop or what so ever and delete them from your Mendix project folder to keep you Mendix project as clean as possible.

That’s it!

Hopefully you’ll understand how to set up Gulp.js for a Mendix project. It saves a lot of time and helped me becoming a more efficient (Mendix) front-end designer (AKA Design Developer)!

I want to thank Zell for writing this great article about starting with Gulp.js and Jelte Lagendijk for setting it up for a Mendix project!

P.s. hopefully my dutchism is a understandable