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
Starting a new project generally requires some initial setup before you can jump into code. SharePoint Framework (SPFx) is no exception. I hope you find this article helpful the next time you create a new project.
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
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"
}
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 account on GitHub has a repository 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, so “use at your own risk”.
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
I will focus on the new version of the library (previously PnP-JS-Core) but the same is valid for the previous version.
“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.
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
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.
At the time of writing, the following controls are available:
- FileTypeIcon
- ListView
- Placeholder
- SiteBreadcrumb
- WebPartTitle
- IFrameDialog
Reusable SPFx property pane controls
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.
At the time of writing, the following controls are available:
- PropertyFieldColorPicker
- PropertyFieldDateTimePicker
- PropertyFieldListPicker
- PropertyFieldPeoplePicker
- PropertyFieldSpinButton
- PropertyFieldTermPicker
- PropertyFieldMultiSelect
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.