 This is a story about a mea culpa. That's me saying got it wrong fess up now I want to get it right and now I'm not speaking for Microsoft in this case I think that I am because I kind of the documentation was wrong for a little while and it's now been fixed but let's just be clear speaking for myself for the longest time we as SharePoint framework developers we were told install go globally when you're setting up your SharePoint developer environment however that was wrong it was always wrong a whole long even from the very beginning you should have been stalling the gulp CLI instead and you should be doing that globally not installing gulp why stay with me I'll explain hey I'm Andrew Coll this episode is also available as a blog post on boytunnels.io and as a podcast on boytunnels.show check out the description below the video for links to these other resources the best way to understand why you should be installing the gulp CLI globally and not gulp globally is you need to understand why there's two different packages and while this is not a complete story it's easiest to understand the transition from gulp version 3 to gulp version 4 but let's first understand how gulp is organized gulp originally was contained contained two things in a single package we have a JavaScript library that enabled you to use gulp from JavaScript code such as gulp file.js or when you were creating custom task libraries think of this like react you don't run react in your projects rather your project uses a react library to implement your user experience now the other thing the other part of gulp that was inside the single package was a program or the CLI that was allowing us to access and run gulp commands from the console so this is what looks for your projects gulp file.js to load the tasks that you can run from the console or you can list all the available tasks when you supply the dash dash tasks command line argument now originally the guidance was to install gulp both globally as well as locally within your project and that was fine when there was just one version of gulp because the CLI part of gulp could call and run the JavaScript library part of gulp if all the projects in your dev environment use the same version of gulp there ain't no problem but the team could see a point in the future where this might not be true what if some projects were using one version of gulp while other projects using a different version of gulp the team decided to split these two things out into two separate packages you've got the gulp CLI that's the standalone separate program that enables you to run gulp from the console and then you've got gulp the JavaScript library that you can use in your gulp file.js this package still had the CLI in it so most people didn't take notice of this change and even though the version one of the CLI was introduced way back in November of 2015 see SharePoint framework guys this predates even the SharePoint framework before it even got started in fact as a SharePoint framework developer you might not have ever heard of the gulp CLI you were told by Microsoft and me may culpa and others just to install gulp globally and everything just worked fine because we were all using gulp version 3 in our projects most SharePoint frameworks weren't using gulp and other projects they were just using SharePoint framework well then there was the version gulp 3 to gulp 4 transition when node released version 12 the gulp team realized that they had made us had to make a significant change to gulp to support the new node version and ultimately they decided that instead of adding all of this complex modifications to gulp v3 the better approach was just to say let's just release a brand new version that is not backwards compatible so they decided to say gulp v3 will continue to work on all versions of node up through node version 11 and then the new version gulp v4 will work from node v12 going forward but that doesn't explain why do we need this gulp CLI right okay stay with me gulp the program can only run gulp tasks that use the same matching library version so I'm gonna explain right here the conflicting gulp versions between the global and local installations now you can only run gulp tasks that use the same matching library version the CLI can only run the programs for the same for the library that matches the same version so when you install gulp version 3 globally you can run you can only run tasks and projects to use the gulp v3 library that's fine right because gulp is installed globally it's gonna run the CLI and they can run gulp v3 tasks which are in the projects and as long as they were gulp v3 they're cool in fact you could do the exact same thing with gulp version 4 you install gulp version 4 globally if you had projects that were using gulp version 4 it worked just fine but what happens when you have different versions what you can't do is you can't run gulp tasks written in one library version like v3 but you've installed a different gulp version as the CL as your as a program that's gonna run those tasks like version 4 so if I install version 4 all the sudden it doesn't work for my new projects and SharePoint framework developers we might have run into this when the spfx version 1.12.1 I believe was released Microsoft updated brand new projects to use the gulp v4 library instead of the v3 library and as such in the release notes they also told us to install gulp v4 globally well that was fine and our projects worked fine that were 1.12.1 except when we try to run gulp v3 against an older SharePoint framework project or v4 gets an older SharePoint framework project for example you had a SharePoint framework 1.11 project on the same environment you might run into an error and then again depending on what the task was doing you might not run into an error you might it might just be just fine but then one day because running one major version of gulp against a mismatch project major version it's simply not supported stuff is probably gonna break at some point in the future and this is where the guidance from Microsoft was misguided well I admit it my guidance I was telling developers was wrong too in fact I'm one of the maintainers of the SharePoint framework developer docs release notes for new versions and this got by me too but hey when you're wrong you're wrong you should admit it make it right that's what I'm doing right here so what am I telling you to do you should always install the gulp cli globally not gulp now as I mentioned previously the way the gulp team addressed this issue was to release a separate package gulp cli that is intended to be installed globally this guy's major version is version 2 once you do that you have the gulp program that's version agnostic with from the version of the gulp library that's being used with specific projects in your environment so now when you install the gulp cli the gulp cli can now run tasks that were written with gulp v3 or gulp v4 gulp the javascript library is installed in your project as a developer dependency a dev dependency within your project if it's using gulp tasks and for us SharePoint framework developers we don't have to worry about that that's already done for us so when we scaffold a new project it's already there nothing for us to do so you may be asking yourself I've never had this problem installing gulp globally why does this matter just because you haven't had the problem doesn't mean you won't have it in the future if you're using gulp v3 globally event you know eventually you're going to have a problem it's going to hit you at some point so gulp v3 is simply not supported in node js v12 or higher nor is it supported with gulp v4 projects and so while it may work right now in the future it's not going to you may also ask why don't do SharePoint framework does this even matter to me the answer is yes this isn't a SharePoint framework thing this issue has nothing to do with the SharePoint framework this issue is entirely about running gulp tasks and the version of node that's installed in your environment I've used the SharePoint framework as my example throughout this episode but only because it's what a lot of people like that that come to me what they're asking for what they're looking for SharePoint framework topics if you're just a node developer who works on projects that use gulp this applies 100 to you as well so again this was a story about a mea culpa which is me saying got it wrong but i want to fess up i want to fix it and while i'm not speaking for microsoft i am speaking for myself but i'm pretty sure you could say this is also microsoft guidance as well because the docs have been updated to tell you to use the gulp cli you got a question or comment let me know what you think by dropping a comment in the video below or tweeting me at andrew connell or at void tamas and if you like this episode man i'd really appreciate it if you'd share it with the rest of your friends this episode as i said earlier is also available as a blog post on void tamas.io and on the void tamas podcast at void tamas.show i've included links in the description below to these other resources and hey don't forget to subscribe to this channel and click that little bell in the corner to be notified of future episodes