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.
