Your Quickstart to Modern SharePoint DevelopmentIf you are using SharePoint Online, you probably have come across the beautiful modern interface of Communication and Team sites, which can drastically improve the ROI of your SharePoint investment. This is not just a fresh new look applied to the site- it’s also a new editing experience for content creators
The way you interact with web parts has changed as well, instead of using the ribbon at the top of the page and adding them to specific zones, now you can fluidly design the layout of the page one section at a time. You can add your custom web parts to the available selection, but the development of those has evolved to utilize the SharePoint Framework (SPFx).
This blog post is intended for former SharePoint developers that are looking at making the transition to SPFx, providing some insights from a former SharePoint classic and On-Premise developer who has made the jump.
The New SharePoint World
If you are coming from SharePoint On-Premise, you have likely utilized the Publishing Features to change the look and feel of SharePoint, create custom components with JavaScript-based frameworks, deploy code solutions to the farm, and take advantage of the SharePoint add-in model.
When you are moving to SharePoint Online, the paradigm shifts to a multi-tenant cloud environment where it is no longer a possibility to deploy your code to your SharePoint servers directly.
On top of that, the new Team sites and Communication sites do not use the Publishing Infrastructure features, the pages have new web parts available, and you will quickly notice that you can’t embed JavaScript code directly to the page.To develop new functionality, you will need to use the SharePoint Framework (SPFx) which can be implemented in two different ways:
- SPFx web parts: client-side controls inside a SharePoint page that can be added in the same way that out of the box web parts.
- SPFx extensions: customization of the SharePoint experience, can be used to add scripts to the page and manipulate HTML placeholders (application customizers), customize the fields in a modern list (field customizers), and add new commands (command sets).
In this post, we will focus only on SPFx web parts since it’s what you’ll need to do first. It’s important to mention that SPFx is framework-agnostic, so technically you can use any JavaScript framework you are already familiar with to work with it. However, you’ll quickly realize that the most popular framework used for SPFx is React.js, if you’re familiar with .Net MVC or Angular, the learning curve of React.js is pretty quick.
What Do I Need to Get Started With SPFx?
The basic setup is quite simple: Node.js (LTS 10.x), Gulp, Yeoman, and the Yeoman SharePoint generator.
You can follow the Set up your SPFx development environment article to get your computer ready with the needed tools to start creating SPFx web parts.
Additionally, the hello world web part tutorial is great to make sure your environment works correctly and to set a starting workflow. You will be using the workbench to test your web part and it includes the commands to package your app and add it to an app catalog.
As a quick side note, instead of using your tenant app catalog, you might want to consider using a site collection app catalog when you’re developing and testing your SPFx web part. Check the Use the site collection app catalog article for a great explanation of the use and setup of this feature.Creating Enterprise SPFx Web PartsThe hello world web part is a great example of how to get started, but it’s way too simple for most practical uses of custom development. You are probably looking to create a custom SPFx web part because you need to implement features like connectivity to other web services or handle a more complex UX flow.
The React.js components are simple and that makes them very powerful, they exist independently from one another and the props do not change in the component itself, any changes would exist in the state of the component. However, using only the state and props can become quite confusing and messy when you start adding complexity to your web part, which is likely to happen organically when you continue development in several sprints, adding new features as users interact with it.
One option to address this issue is adding a framework that can handle the interaction flow so it’s simpler for developers to figure out what is the right location for the code they are writing as they add functionality or fix bugs.ReduxRedux is a framework based in three principles: you have a single source of truth for the global state of your application, your state is read-only and only manipulated through actions, and the changes are made with pure functions (always return a new state instead of mutating the previous one). Learning this framework can be done extremely quickly by watching the first videos of the series Getting started with Redux, the first 10 videos are below 4 minutes each and easy to understand.
You can manually add Redux to your SPFx web part code created by the Yeoman generator, but if you want to take a shortcut, you can clone the sample in GitHub.
This sample organizes your code using the following folders:
Actions: declaration and implementation of the methods that will call the reducer to produce a new state, the implementation will include the logic of the change that is being executed and will result in a dispatch to the reducer to apply the change to the state.
API: calls to any external API, like your Azure-hosted web application RESTful API.
Components: the dummy React components, each one with their props file and styles.
Reducers: the implementation of your reducers, this is the only location where the state of the application is changed by receiving the actions and producing a new state. For small applications, you are likely only going to have a single reducer, but if the web part grows you can separate your reducers to increase efficiency.
State: the sample is using Immutable.js, so this section contains the implementation of the state updates using this library.
Store: the configuration of your single store, you normally won’t need to change this unless you’re adding additional middleware to your code.
Tests: your unit tests, the sample is using chai to execute them.
Implementing a framework/code structure like the one in the sample will help your team by establishing some standards regarding the location of the web part code. This familiarity will help team members get started quicker when joining the team or when coming back to an existing code base after a break.
Other great libraries to consider when creating SPFx web parts include:
PnPjs
If your web part is interacting with SharePoint elements, the Graph API, or another Office 365 API, you should definitively check the packages included in the PnPJs. As part of the community-based Patterns and Practices effort, you can submit issues and bug fixes to the code. Plus, it has quite decent documentation.
These packages can save you a considerable amount of time versus creating your implementation of the API calls, especially when dealing with list driven behavior in your web part.
Fluent UI
The Fluent UI is a collection of controls that you can easily import into your web part that match the look and feel of the Modern UI.
Each control includes several code samples to configure in different scenarios as well as a section for best practices based on the UX guidelines.
Using the Fluent UI will make your web part look like it’s a part of the SharePoint page rather than a complete custom component. Also, Fluent UI saves you time since the calls to the components are already documented and include a lot of accessibility options.
Modern SharePoint Development Best PracticesWhen it comes to developing for Modern SharePoint, there are a few best practices you should follow to ensure success.
Scope of your customization
When creating an SPFx web part, make sure that your code is isolated to your web part so that it doesn’t bleed outside of this scope.
For instance, you might be considering using a web font that is not available for SharePoint in your web part which is okay too. However, you shouldn’t be applying CSS rules that will also apply this font to elements outside of your web part. Your web part has no control of the code outside of the React.js wrapper, so manipulating the DOM this way might lead to unexpected results.When using SPFx extensions, make sure that your changes are applied only to the supported placeholders (in the case you are using an application customizer).
If there is not a configuration option in SharePoint to perform a global change, your best option would be to submit an idea in User Voice to bring it to the attention of the product group.
Unit Testing
This is not specific to SPFx web parts; unit testing is highly recommended in an enterprise scenario, as it will likely save you time in the long run when making code changes.
SPFx has a lot of flexibility for any JavaScript-based unit testing framework, there is even a sample repository of the Jest testing framework with SPFx.
Unit testing also plays a prime role in a continuous integration environment, which leads to…
Azure DevOps pipeline
The hello world web part is a good example of the basic workflow you will follow when coding and deploying your SPFx web part, but as your team grows, it’s likely you are going to need to create a continuous integration environment with automated builds and deployments.
Azure DevOps is a great platform that can help your organization by using these different areas:
Boards: management of the backlogs and user stories on each sprint, plus bugs and tasks. Each of those can be associated with specific branches and pull requests to provide traceability of the changes to the code base.
Repos: your code repositories, including your pull requests and code reviews. Using a centralized code repository and a consistent branching strategy across multiple projects will make it easier for your developers to join new projects.
Pipelines: different environments can be configured to allow continuous integration once a pull request is completed; you can create automated quality gates that will make sure that you won’t be introducing build-breaking errors into your code.
Test Plans: management of your test runs, configurations and even load testing.
Artifacts: allows the distribution of packages to teams using different public and private feeds.
Depending on the level of maturity of your team, you may benefit from using all the different areas of Azure DevOps or just a few. A great place to start if you have not used ADO before is implementing the repos and pipelines for automated building/testing and continuous integration.
Modern Script Editor
One of the samples available in GitHub is the React Script Editor, which provides an option to the classic script editor web part in Modern pages.
In some cases, this might be a quicker alternative than recreating the functionality in a brand new SPFx web part, but exercise caution to make sure your team is not abusing this web part to avoid the development of valid SPFx web parts.
Additionally, the web part by default will respect the site setting that allows/blocks the execution of client-side scripts. This is intentional since ignoring the setting could represent a governance issue, but be aware that by changing the source code, the web part can be compiled to ignore the site setting.
All modern team and communication sites block the execution of client-side scripts by.
The tools mentioned in this post will help you quickly ramp up in the development of SPFx web parts. You can save a lot of time by using an established code structure and adapt it to fit your development team as the team works on more projects.
If you’d like to chat more about SharePoint development or want an expert to help with your SharePoint project, contact us to learn more.
