When SharePoint Framework was released publicly, I started wondering: how can we use the latest generator while supporting older projects?

Following the recommendations

When you setup your development environment for building SharePoint Framework solutions, you start with installing Yeoman and the SharePoint Framework Yeoman generator. You follow the recommendation and install the generator globally.

You scaffold your SharePoint Framework project using the latest version of the generator available - v1.1.1 at the time of writing this article. You add a few web parts and extensions. You finish the code and ship the solution. Everything is working as expected.

Over the next few months Microsoft releases a few updates to the SharePoint Framework Yeoman generator and you update your installed version accordingly. This way you can benefit of the bug fixes and latest features. But then you’re asked to add another web part to your old project.

Remember, your old project was created using the generator v1.1.1. By now, you updated your generator to v1.5. When you add a new web part, it looks different than other web parts in your project. And when you try to build your project, all you see are errors. Instead of coding the new web part, you’re trying to figure out what’s wrong.

One for all

With the SharePoint Framework Yeoman generator you can create new projects, but also add artifacts to existing projects.

The SharePoint Framework Yeoman generator is an npm package, which typically, developers install globally on their machines. When you install an npm package globally, you only need to install it once, and can then use it in all your projects. Also, you have only one version of it installed. If you want to use another version, you replace the version you had with the version you want to use.

When scaffolding new project, the latest version of the generator allows you to benefit of the latest bug fixes and features. But if you add new artifacts to an existing project, there is a risk, that they will cause the project to break.

Microsoft does their best to keep up with the tools they use in the SPFx toolchain like Webpack, gulp or TypeScript. Also, the SharePoint Framework is continuously evolving to provide us with a rich set of features to build customizations. But all that comes at a price.

The SharePoint Framework Yeoman generator changes regularly, and it’s not always possible for the new versions to be backwards compatible. You can either hope things will keep working or you can control the version of the generator that you’re using.

Lock the generator

You want your project and the toolchain used to create it to be in sync. If you create a project using the generator v1.1.1, you want to keep using that exact version of the generator for adding other artifacts. If you want to benefit of the latest features and updates, you update the project and then use the new generator. So, how can you do that?

Create a virtual machine for each project

In the past, when building SharePoint customizations, you used a virtual machine. With a VM you could run a version of SharePoint as close as possible to the target production environment. SharePoint VMs were big and inconvenient to use. They came however with an important benefit: for every project you could choose which version of SharePoint you wanted to use to ensure that your solution would work when deployed to production.

Similarly to developing farm solutions in the past, you could create a VM for building SharePoint Framework solutions and install a specific version of the SharePoint Framework generator in it. It doesn’t matter if you had to come back to that project the next day, month or year, you could keep using the specific version of the generator.

While absolutely viable, this option is far from optimal. Even though SharePoint Framework VMs are significantly smaller than classic SharePoint VMs, they’re still bigger and less convenient to use than other approaches available to you.

Use Docker containers

Another option that helps you isolate your projects and their toolchain is using Docker containers.

If you’re new to Docker, without going into details, think of Docker containers as lightweight virtual machines. Docker images are templates used to run Docker containers - instances of a specific virtual machine. Docker images contain an operating system - often a Linux distribution - and a set of applications varying from Node.js to databases.

Using Docker, you can create (or simply use) an image with the specific version of the SharePoint Framework Yeoman generator. For each project you can then choose which container you have to start so that it matches the version of SPFx used to create that project.

Docker images are significantly easier to handle and work with than VMs. Before you can use them, you have to learn the basics of Docker. If for some reason you can’t use Docker, there are other options that you can consider.

Use NVM

If you prefer developing on the host, you can use the Node Version Manager (NVM) to run the different versions of the SharePoint Framework Yeoman generator. With NVM you can have different versions of Node.js installed side-by-side and can easily switch between them. All versions are isolated and each version comes with its own storage for global packages.

Using NVM you would install a different version of Node.js for each version of the SharePoint Framework Yeoman generator that you want to use. For example, today you would install Node.js v6.11.1 with SharePoint Framework Yeoman generator v1.1.1. In the future, if you wanted to use the SPFx generator v1.2, without losing the ability to switch back to v1.1.1, you would use NVM to install another version of Node.js, for example v6.12, and would install the SPFx generator v1.2. In both cases you would follow the guidance and install the generator globally. Whenever you needed to use another version of the generator, you would use NVM to switch to the corresponding version of Node.js.

In the context of the SharePoint Framework, Node.js is used only as runtime for the developer tools and is not used in production. This is why you don’t always have to use its latest version and it’s not bad to go back a few versions. Using NVM and separate Node.js versions to isolate the SharePoint Framework generator is convenient with little overhead of managing global packages in each version of Node.js. By adding aliases to specific Node.js versions installed with NVM you can make it easier to know which version corresponds to which project.

Install the SPFx generator locally

In contrary to what the guidance says, in this option, you install the SharePoint Framework Yeoman generator locally in the project. After creating the project, you add the SPFx generator to the list of dev dependencies in your project. The next time you retrieve the project from the source control and run npm install to restore its dependencies, the specific version of the SPFx generator will be restored along with other dependencies giving you a complete set of tools required to work on that project.

Caveats

There are a few things that you should keep in mind if you want to use this approach.

Yeoman and its generators can be installed locally

For a while it’s been unclear whether Yeoman and its generators are meant to be used locally or not. Recently, Simon Boudrias, who is working on Yeoman, confirmed that Yeoman runs locally just fine.

We do, like any other tool you're using on npm.

— Simon Boudrias (@Vaxilart) July 18, 2017

Install SharePoint Framework Yeoman generator only locally

If you have a version of the SharePoint Framework Yeoman generator installed globally, that version will take precedence of any version installed locally in your project. While you can have Yeoman installed globally, the SPFx generator should be installed only locally in your projects.

Add the SPFx generator to your dev dependencies

After scaffolding a project using the SPFx generator, you have to re-install the SPFx generator to add it to the dev dependencies in your project (run npm i @microsoft/generator-sharepoint -D). The SPFx generator currently overwrites the contents of the project.json losing the reference to your SPFx generator dependency. If you forget to do this, when you restore your project’s dependencies, the SPFx generator will not be among them and you won’t be able to add new artifacts to your project.

Lock dependencies versions

Don’t forget to lock the versions of your dependencies using npm shrinkwrap or other lock file. Without this, it will be all for nothing and when restoring dependencies, you could still pull in a newer version of the generator than the one you used originally.

Despite its caveats, installing the SPFx generator locally as a project dependency is by far my preferred option of keeping the version of the SPFx generator in sync with the created project. Storing the generator as a dev dependency in the project is intuitive and requires little overhead. When restoring project dependencies you automatically get the right version of the generator without having to manually retrieving a correct image or a VM.

Which option are you going to use in your next project?