Starting a new project generally requires some initial setup before you can jump into code. SharePoint Framework (SPFx) is no exception.
Unfortunately, we often forget to configure something that then needs to be added during the development phase, which may introduce some issues. I hope you find this article helpful the next time you create a new project.
Last updated: 13 July 2018
Note: There are now ways to extend the SharePoint Yeoman generator and automate some of the steps below, and also more updates on this to come. If you are interested, I suggest you follow Stefan Bauer‘s blog. Rodrigo Silva has also done a really good session on SharePoint Saturday Madrid 2018.
Introduction
In this article you can find a checklist covering the main tasks I generally do when starting a new SharePoint Framework project:
- Check outdated NPM global modules
Add TSLint configuration- Update project version
- Define deployment location
- Add custom gulp tasks
- Install additional node modules
- Setup CI/CD
Check outdated NPM global modules
Microsoft is doing a really good job on publishing new versions of the SharePoint Framework. We generally get a new version every few weeks with bug fixes and often new features. You can find information on the latest releases at the bottom of this page.
If you are creating a new project, you should always ensure that you are using the latest version of the SPFx Yeoman generator. To do that, you can use the NPM command to check for global outdated modules:
npm outdated -g
You can simply run the following command to update @microsoft/generator-sharepoint module if it is listed in the output of the command:
npm install @microsoft/generator-sharepoint -g
Since you are here, you may as well check if other modules are listed as outdated and consider updating them.
Add TSLint configuration
Update: SPFx 1.6.0 now (finally!) scaffolds the tslint.json file at the root of the project, so this step is no longer required.
As explained on a previous post on my personal blog, SPFx solutions do not provide default support for TSLint extension on Visual Studio Code. To solve this, let’s simply add a tslint.json file at the root folder, pointing to the folder where the TSLint rules are declared:
{
"rulesDirectory": "./config"
}
Unfortunately, at the time of writing, this is still not supported by default on the latest SPFx version (1.5.1).
Update project version
SharePoint Framework projects contain two locations where the version is specified: package.json and package-solution.json.
When the project is created, the version on package.json is set as 0.0.1, but the version on package-solution.json is set to 1.0.0.0. As you can see by the version format, the version number is not the only difference here. Package.json follows the Semantic Versioning specification (SemVer), but the same is not true for package-solution.json.
To make things a little simpler, let’s set the version on package.json to be the same as package-solution.json file (ignoring the last 0) – 1.0.0
Later we will add a gulp task to keep both files in sync.
Define deployment location
My preference is to use Office 365 public CDN by default. If you use asset packaging, to include asset files within the solution package (.sppkg) for deployment, it makes the whole deployment story a lot simpler and extremely easy to maintain.
If you want more flexibility, you can use a SharePoint library (as CDN), Azure CDN, or any other CDN provider. Just make sure that your project is correctly configured with the details for the deployment location.
Add custom gulp tasks
SPFx solutions already contain really useful gulp tasks that provide all the core functionality to assist you on developing and packaging the solution.
Having said that, there are a few extra additions that I find very useful and always end up adding to all projects:
version-sync
This is the custom task responsible for keeping package.json and package-solution.json versions synchronized. It was created by Stefan Bauer and you can check the details and copy the task code from his blog post.
The task is then configured to run on “postversion”, which means that when you use NPM to update the version of your project, the task will fire and sync files automatically in the background.
sp-dev-build-extensions
The SharePoint GitHub repository contains a project called sp-dev-build-extensions where you can find multiple gulp tasks. Usage will depend on your project, deployment location, and so on.., so pick the ones you need.
You may want to include the ones that will help you setup your CI/CD pipeline (details below), so plan upfront. The Office 365 CLI is another option here, but I personally haven’t had the time to test it yet.
Install additional node modules
You can argue that this is not something you can do upfront, as you will not know the dependencies that your project will end up with. And I agree. But this section is to cover the dependencies that you know upfront that you will use.
Below I will list the node modules that I generally end up using on all my projects. If you are not currently using them, you should reconsider your options as they provide some great functionality.
PnPJS
To install the most common modules simply run:
npm install @pnp/logging @pnp/common @pnp/odata @pnp/sp @pnp/graph --save
From the library’s website: “PnPJS is a fluent JavaScript API for consuming SharePoint and Office 365 REST APIs in a type-safe way.”
Once you try it for the first time, you simply won’t want to be writing REST calls again as long url strings. It now also provides support for SharePoint Managed Metadata and Microsoft Graph!
PnPJS has some really good documentation and a getting started guide, so you will easily find all the information you need to install, configure and use the library.
Reusable React controls
Simply enter the following command to install the dependency to your project:
npm install @pnp/spfx-controls-react --save --save-exact
If you want you solution to contain controls that leverage Office UI Fabric and look similar to out-of-the-box SharePoint controls, you should include the PnP Reusable React controls in your solution. They contain plenty of documentation on how to get started and use the controls in your solution.
I strongly encourage you to keep checking the list of available controls as they get updated frequently!
Reusable SPFx property pane controls
Simply enter the following command to install the dependency to your project:
npm install @pnp/spfx-property-controls --save --save-exact
The PnP Reusable SPFx property pane controls contain a set of reusable controls that you can add to your web part property pane in order to provide a rich configuration experience for your end users with minimal effort. Check the documentation to learn how to get started and use the controls in your web parts.
I strongly encourage you to keep checking the list of available controls as they get updated frequently!
I strongly encourage you to keep checking the list of available controls as they get updated frequently!
Setup CI/CD
CI/CD is a very important topic and you should consider it even before you start developing. Depending on how your company/team is structured, this may or may not fall inside your competency.
It is important to define and implement the minimal CI/CD pipeline to automate builds, tests and releases from the beginning. This way you will be able to detect when new issues are introduced.
It’s important that you consider the “right tools for the job” as a CI/CD pipeline can be achieved through lots of different tools and configurations, and can also significantly change depending on specific project requirements.
Is the post missing something that you think should be included? If so, then please leave a comment below.
This blog post was originally posted on Collab 365