by 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.
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.
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
- SP starter kit – Useful source for start code samples – Link
- SharePoint React property pane controls and web part controls project – Link
- PnP JS Modules – PnPjs module for SharePoint operations – Link
- SPFx Webpart Samples – Sample webparts and examples. Please use it for reference only – Link
- 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 !!
Tech Huddle 
2 Comments