When developing SharePoint Framework components (web parts and extensions) you may release a single one to an environment and be done with it. Or more likely you’ll be creating multiple web parts and extensions and will need to decide how to approach SPFx packaging.
Things to consider when packaging SPFx components
- How do I share my code between components?
- How do I share library code between components?
- How do ensure that components use the same version of the SharePoint Framework?
- How do I version dependencies of the components?
- How do I upgrade components?
- What is the development/test environment like?
All these questions really boil down to a single question:
Do you a create a multi-component SPFx project or have a project for each component?
* SPOILER *
I have concluded that the default approach to SPFx packaging should be to include all components into a single multi-component project. Avoid creating multiple packages where possible. Depending on the scale of the development team there may be some scenarios where this is not appropriate, in which case create as few multi-component projects as are necessary. Furthermore, I recommend creating a single multi-component JS bundle file for all web parts in package (a multi-component bundle), rather than the default approach of having a JS file for each component.
Terminology
Multi-component project/package: SPFx packaging such that a single sppkg file is produced which deploys multiple SPFx web parts or extensions.
Multi-component bundle: Only available within the context of a multi-component project, a multi-component bundle includes the JS required for all components as a single file rather than a file for each component.
Just do it
So take my word for it, add all your SPFx components to a single package and create multi-component bundles. To add additional web parts to an existing project just run the Yeoman generator again in the same folder location. Elio Struyf has a post about multi-component bundles and I’m sure that there will be official guidance release very shortly.
Or perhaps you’d like me to explain my rationale, the benefits, and where this approach may not meet your needs. In which case, please read on..
What you sacrifice by having a single project
Firstly, let’s discuss what is sacrificed by packaging SPFx components into a single sppkg package?
- You can no longer install or upgrade components individually. (However, the new site collection scoped app catalog may assist with this.)
- Depending on your development environment, it may be easier to govern source code and DevOps processes during development and test. For example if you have different teams working different web parts.
- During development you can build and deploy individual components which may lead to time savings if/when the volume of components becomes large. (In these cases the gulp tool chain could be modified to meet requirements.)
What you gain by having a single project
If the above list of sacrifices aren’t deal breakers then there are many benefits to be had by taking this approach.
- Sharing code between SPFx components is trivial. Sharing code between packages is hard.
- Deployment and upgrade is trivial especially with tenant-scoped deployment – just deploy a single package to the app catalogue and you are done.
- The risk of having multiple web parts using different versions of the SharePoint Framework is avoided.
- The risk of having multiple versions of third partly libraries loaded is greatly reduced.
- Total payload of components will be much smaller due to reduced duplication of shared code, library code (especially Office UI Fabric), and the framework itself due to multi-component bundling. Sub-optimal usage of external references, static vs dynamic import statements, and the bloat that some recommended frameworks currently inflict (Office UI Fabric React…) can lead to very substantial page weight increases. By using a multi-component bundle the worst case scenarios are avoided as in most cases these issues will impact a solution once for each bundle.
- Versioning of shared code is trivial because you don’t have to it. Internal dependencies are including the bundle and external dependencies are referenced to only once. The framework itself handles the component versioning for you.
And finally…
I’d be particularly interested to hear from people who have found strong reasons to package components individually because currently I believe that the benefits of multi-component SPFx packaging outweighs the benefits in nearly all scenarios.
Paul.
Hi Paul,
I am working on a project with several different SPFx web parts. When I scaffold each web part one by one, I have a giant node_module folders as well as completely separate dev environments of sorts. When I have separated them, it seems that I have to have all of the web parts in the package compiled, otherwise I get build errors. I do like including them all, however I am concerned that if I do that an get a huge typescript version error, or something like that, I may lose functionality from a all of my web parts, vs the specific one causing the problem. Is there away that I can run a gulp serve, however only on a specific web part? Maybe there is a way to adjust my entries in my config.json file if I want exclude a web part from my local compiler.
It is true that if you bundle all the web parts then a breaking change in library that you update or something like that might cause all the web parts to fail rather than just one. I would consider this a positive as the alternative is managing (and having the user download) multiple versions of the same library. I guess it does depend on how tightly coupled the web parts are and whether the client can accept that there is some risk to all web parts if making a change to any one in the package.
To answer you final question, yes, you can modify the config.json and just comment out all but a single web part which you are working on but, of course, doing this means that the other web parts are not included in the package and will not be available. I don’t see how this helps your situation but it can be done and I have done it in order to assist with build time performance issues when the package starts getting large. I found that is not very helpful as the full code base is still linted and parsed for packaging by web pack which means that the build/package time is still roughly 80% as time consuming – in my experience.
I am looking for such kind of solution having one SPFX project with multiple web parts but having multiple web parts in single SPFX solution can cause issues if there is issue in one web part. It will break all web parts coming from that single spfx project as there is only one package file to upload.