Inconvenient locally installing SharePoint Framework Yeoman generator

Installing the SharePoint Framework Yeoman generator locally allows you to easily isolate the specific version of the SharePoint Framework you need for each particular project. But if you’re using npm@5, it just got a bit more inconvenient.

Yeoman generators global or local

SharePoint Framework uses a Yeoman generator to scaffold projects. Typically, you install Yeoman globally which allows you to conveniently use it in your command line.

When it comes to installing Yeoman generators, you often see that they are installed globally as well. This allows you to scaffold a project in every directory on your disk. But it comes with a limitation too: you can have only one version of the particular generator installed on your machine. Usually it’s not a problem. But it becomes one, when working with the SharePoint Framework.

If you have an existing project using let’s say SharePoint Framework v1.3.2, and you want to add a new web part to it, using a different version of the generator could lead to breaking your project because of the difference in structure or dependencies. So instead, if you need to add new components to an existing project, you should always use the version of the generator matching the version of the SharePoint Framework used by the project.

But it’s not necessary to install the SharePoint Framework Yeoman generator globally. Instead, you could install it locally in your project just as any other devDependency. The benefit this offers you is that you always have a version of the SharePoint Framework Yeoman generator matching your project. Whenever someone pulls down the source code from source control and restores dependencies, the corresponding version of the SharePoint Framework Yeoman generator is installed as well and ready to use in the project.

Unfortunately, installing the SharePoint Framework Yeoman generator locally is not without caveats. Here is why.

Inconvenient installing SharePoint Framework Yeoman generator locally

If you want to work with a locally installed SharePoint Framework Yeoman generator, you start in an empty folder with nothing but a package.json file in it. You install the generator by executing in the command line:

npm install @microsoft/generator-sharepoint --save-dev

This installs the SharePoint Framework Yeoman generator in the node_modules folder, registers the generator in the package.json file as a devDependency, and if you’re using npm@5, also generates the lockfile.

Next, you scaffold the SharePoint Framework project, by executing:

yo @microsoft/sharepoint

As you can see, there is no difference in how you call the generator no matter if it’s installed globally or locally. Yeoman handles that automatically for you. But here comes the catch.

When scaffolding the project, the SharePoint Framework Yeoman generator replaces the existing package.json file with its own. As a result, the information about the @microsoft/generator-sharepoint dependency is lost. After installing SharePoint Framework dependencies, npm@5 uses the information from the package.json file to clean up unused packages. As expected, because @microsoft/generator-sharepoint is no longer listed as a dependency, it’s removed. So in order to keep it in your project, you have to install it again.

Ideally, the SharePoint Framework Yeoman generator should respect the existing project.json file. But as long as it doesn’t, you have to keep in mind to reinstall the generator after scaffolding the project if you want to use the locally installed SharePoint Framework Yeoman generator.