SPFx developer guide – setup and solution structure overview

Often I get enquiries to set up a SPFx development environment. It is a fairly straightforward process and some good documentation from Microsoft is available here. However, there are still many technical bits that the developers need to work out before they could start building a real world solution.

Hence in this blog, I will try to quickly outline the set up steps, solution structure overview, and at high level dependencies for anyone who is trying to jump into development of SPFx solutions. There are also few helper links and content below for anyone who looks for a quick links to SPFx repositories.

This is fairly long blog, from my blog standards :), so give yourself 2-3 min read or skip to the particular section you are interested in.

Pre-requisites

1. First and foremost, since most of the development for SPFx is done locally so you will need a laptop, desktop or Virtual machine that you have admin rights to install software.

2. Install Node LTS version, remember to install the LTS version and not the current version as SPFx toolchain is closely linked to LTS only. Link here.

3. Install Typescript or JavaScript Code editing tools. There are many tools available for the same but would recommend Visual Studio Code as it seamless integrates with the SPFx toolchain and easy to build. Install VS Code from here

Setup Steps:

1. Install Yeoman and Gulp. Just run the below command

npm install -g yo gulp

Yeoman is a scaffolding system that allows to create the initial folders and packages for the SPFx solution.

Gulp acts as a compile, build and packaging tool for SPFx packages.

2. Next we run the yo command to generate the initial solution. Below is a screenshot of the steps for sample React Webpart without tenant deployment. Choose the most appropriate for your solution.

SPFx Webpart set up

3. Install the necessary packages using npm install for development, some of the packages are below. Check helper guide section below for links to these libraries.

a. @pnpjs modules – helpful to connect and do CRUD operations on SharePoint

b. office-ui-fabric-react – this is part of SPFx scaffolding install now (from 1.4.1) but could be also explicitly installed if need latest controls.

c. msgraphclient and aadhttpclient – to connect and work with Graph client libraries and ADAL auth scenarios and much more.. This is specifically beneficial for authentication scenarios from external web apps to SharePoint or to graph. Will talk about this in an upcoming blog.

4. Install a dev certificate before testing with command below. See this link if you run into a HTTPS/2 issue.

gulp trust-dev-cert

5. Start the development. Import the components and necessary headers for eg. as below. Also add a init method to the webpart file in case you are initialising any global components such as ‘sp’ from pnpjs.

Import Tags SPFx solution - Visual Studio Code

5. Guild build – This is not a necessary step but why gulp build? as it will help compile and resolve any .scss file compile issues and not fail later the gulp serve)

6. Gulp serve to compile and troubleshoot the component in local hosting for debugging and testing. Modify launch.json to test in a hosted SharePoint site. There is a good article here to start with.

gulp serve --nobrowser

7. After build is complete, we are ready for packaging and deployment. We will look at detailed steps for these in another blog.

gulp --ship

gulp deploy-azure storage --ship (* for Azure CDN deployments only)

gulp package-solution --ship

8. After packaging the solution, you could retrieve the packaged solution (*.sppkg) from SharePoint -> solution folder in the webpart.

9. To install the solution, just drag and drop the solution in App catalog of your tenant. For details how to add the webpart to your web or ALM cycle, check this blog.

Understanding Solution structure and key files overview for a React Web part 

Below is a quick snapshot of important folders and files in the SPFx webpart solution. You could change the structure as you want but the below files are strongly typed to the solution behaviour.

  • *webpart.ts file – entry point of the web part call. Lifecycle methods and Property pane settings for the web part for located here.
Tip: Use the webpart.ts file as a Controller for your code, keep bare minimal business logic on this file
  • Components folder – Contains component files (.tsx) files for the components in the web part. (synonymous to user control in the old web part world).
Tip: Components files can also act as controls in other components, so try to reuse code as much as possible through segregrating your code into components
  • *manifest.json – Webpart ID and settings. Also default property pane settings are here
  • config.json – CDN links or inclusion for external Non AMD libraries
  • package-solution.json – npm packages and choice to include ClientAssets in SPFx package (includeClientSideAssets = true)
  • launch.json – debug and troubleshooting settings using Chrome debugger (install chrome debugger extension for the same)
  • node_modules – modules installed from npm
  • deploy-azure-storage.json – settings for deployment to Azure CDN Location
  • styling files (.scss or .css) – files that are used for styling. Yes, you could use .css files if you are not interested in using strongly types .scss styles. Just use this to include them in your code
    require('./<Filename>.css');

Helper Guides and Developer Repositories

  1. SP starter kit – Useful source for start code samples – Link
  2. SharePoint React property pane controls and web part controls project – Link
  3. PnP JS Modules – PnPjs module for SharePoint operations – Link
  4. SPFx Webpart Samples – Sample webparts and examples. Please use it for reference only – Link
  5. Office Fabric UI React controls – Responsive controls for SPFx webparts – Link. You could also use Bootstrap in SPFx, for reference, check this blog – Link

Conclusion:

In the above blog, I have tried to summarise the SPFx high level start up steps. If any step needs to be detailed, please leave a comment and will add a follow up blog on it. Thanks.

Happy Coding !!

Provisioning complex Modern Sites with Azure Functions and Flow – Part 3 – Post Provisioning Site Configuration

In the previous two blogs part 1 and part 2, we looked at steps to create a Modern team site and apply a custom provisioning template to it. In this blog, we will have a look at the steps for the post provisioning process to implement site specific requirements. Some of them could be:

1. Apply default values to list fields

2. Create a bunch of default folders

3. Manage Security groups (SP level) and permission level.

4. Navigation level changes

5. Add/Enable web parts or custom actions (SPFx extensions)

Most of the above steps are part of SharePoint Provisioning processes for a long time, just are less complex now with Provisioning templates doing a lot of heavy lifting. I will be writing very soon about PnP Templates, do and don’ts.

Pre-requisties

One key point to add is that, with Modern Team Sites and Office 365 Groups we cannot add AD security groups into a Office 365 Unified Group. For more information, please see this link.

The apply template process (link) takes about 45-90 min (long running process) for complex templates so wouldn’t be possible to start the post process on a flow wait state. Hence, we could trigger the post provisioning process on update of an inventory item or poll an endpoint for the status. In our case, we triggered the process when updating the inventory list with a status that apply template process is complete.

Post Provisioning Process

1. The first step of the Post Provisioning proces is to make sure that noscript is enabled on the team site (link) and all dependencies are ready such as Term stores, Navigation items, Site Pages, Content types, site columns etc. For a complex site template, this step will check for failure conditions to make sure that all artefacts are in place.

Note: The below sequence of steps could vary based on the solution and site structure in place 
but this was the faster way to isolate issues and ensure dependencies.

After the failure checks are done, we will start with the Site structure changes and navigation changes. For implementing navigation changes, check the blogs here and here.

2. Next, we will update any site specific site columns, site content types and permission level changes. A upcoming blog will have more details to this.

3. After that, we will update the changes for list structure, we will move to list specific updates such as default value setting, modifying list properties etc.

4. Next let’s move on to Apps and Site Pages updates. These changes take time because of SharePoint ALM lifecycle any possible duplications. So error handling is the key. Please check the blog here and for steps to deploy app and web parts here.

5. Before we finalize the site, let’s provision folders and metadata. This is not a simple process if you have to set metadata values for large number of folders like in our case 800 recursive folders (child in parent). So we will use the metadata file override. All the values in the defaults file have to be hardcoded before override.

Note: The metadata file override is not generally a good approach 
because of possible corruption that renders the library unusable
so do error handling for all cases. For the CSOM approach check here.

6. Finally, we will set the site Property bag values for Site to set some of the tags making the site searchable. Here is the blog for the same.

Conclusion

The above we saw the final process of Site Provisioning process with setting up site properties and attributes for preparing the site before handing it off to business for use.