Update 04-08-2015: I discovered a mistake in the watch task where it was not using the gulp-watch plugin, but was instead using the gulp.watch() function. Confusing! The gulp-watch plugin provides more functionality, such as watching for new files in directories, and I have updated the gulpfile.js to use this.
Update: The community wasn’t overly happy with the decision to remove LESS compilation from Web Essentials and so Mads Kristensen has created two new extensions to provide that functionality in Visual Studio 2015. See his blog post for more details. I personally think controlling the process yourself is a better solution, but I can understand that for smaller projects that it is probably just easier to use the extensions.
I have been preparing some older projects for migration to Visual Studio 2015 and ASP.NET 5 and wanted to share how I have setup LESS compilation with Gulp in Visual Studio 2013. I also have a very basic, bare bones solution in GitHub that is setup to compile LESS to CSS that can be referred to. It is available at https://github.com/matthewrwilton/VS2013GulpExamples.
- Install Node.js
- Install the Task Runner Explorer extension for Visual Studio 2013
- Install Gulp globally (run the “npm install gulp -g” command)
- Optional: Install the Grunt Launcher Visual Studio extension
- Optional: Add Intellisense for Grunt and Gulp in Visual Studio 2013
Disable compilation through Web Essentials
The first step is to stop Web Essentials from compiling LESS if you have it installed. To do this, create a solution settings file for Web Essentials (if you don’t have one already) by using the Web Essentials menu. In the Less settings change the values of the “CompileOnBuild” and “CompileOnSave” properties to false.
Add a package.json file at the root of the project
I find the easiest way to do this is to simply add a JSON file through Visual Studio and name it package. In the file create a JSON object and give it a name and a version property. You could use the “npm init” command to create the file, but it adds additional properties that you won’t require for just running LESS compilation. See the following example.
Install gulp and the required modules into the project
One way of doing this is to run the commands to install each module individually, e.g. “npm install –save-dev gulp”. Another (and faster) way is to add a devDependencies section into the package.json that contains the modules required and then run “npm install” either through the command line, or if you have the Grunt Launcher Visual Studio extension installed by right-clicking on the package.json file in the Solution Explorer and selecting the NPM install packages option from the menu. An example package.json with devDependencies follows.
The packages required to give the same functionality as Web Essentials are gulp, gulp-less, gulp-sourcemaps and gullp-watch. I am not outputting a minimised CSS at this stage, because I am still using the ASP.NET bundling feature. This will have to change in the future, because bundling is not going to be supported initially in ASP.NET 5.
Add a gulpfile.js at the root of the project and configure the tasks
This is where you will have to configure the LESS compilation. There are other resources available explaining how to write the gulpfile.js, so I won’t go into much detail here. I personally found the best place to reference when coding the gulpfile was by looking at the GitHub repositories for each module e.g. https://github.com/gulpjs/gulp, https://github.com/plus3network/gulp-less. An example gulpfile.js follows.
At a minimum you need to have tasks for each target CSS file you want to compile. By using the sourcemap module while compiling the LESS you can generate sourcemaps for the compiled CSS similar to Web Essentials.
To have the CSS compiled automatically when a LESS file is edited (like the CompileOnSave functionality Web Essentials had) setup a task that uses the gulp-watch module to watch the source LESS files and calls the appropriate task to compile those files into CSS. Then open the Task Runner Explorer window by right-clicking on the gulpfile.js file. In the Task Runner Explorer window bind the watch task to run when the solution is open by right-clicking on the watch task and then selecting Solution Open option from the Bindings sub-menu.
Once these steps are done, you should have LESS compilation through Gulp setup and working as Web Essentials did. There is still some further work required to be prepared for upgrading to Visual Studio 2015. This covers Web Essentials no longer compiling LESS, however as I briefly mentioned before bundling will not be available immediately in ASP.NET 5.
Finally I would recommend that you don’t track changes to the compiled CSS file in your source control repository. My personal experience is that automatic merging of these files never succeeds and I have to end up compiling it again to resolve the merge.