SPFX

DEPRECATED: This article has been updated. Please see the latest version at SharePoint Framework (SPFx) Quick Start (Gulp toolchain for SPFx v1.21.0 and earlier)

This article left in place for historical reference.

BLAH BLAH BLAH! Just take me to the code!

Even though this post is more wordy than I like, this is the Quick Start guide I use when I am setting up a new computer to work with SPFx. Microsoft has a very detailed guide for SPFx setup at Set up your SharePoint Framework development environment. The Microsoft guide is good, but covers a lot of stuff that you might not need. If my guide doesn’t work for you, I would recommend that you go back to the official documentation. When working with SPFx, there are lots of additional tools that can be installed to enhance your development experience. For this Quick Start, I wanted to keep those tools to a minimum. I deviate from the “stock” installation from Microsoft with three tools that I use on a daily basis and feel are critical for developers that will be building many SPFx projects over long periods of time.

Recently, I had to set up a new development machine. These days, my primary development tasks are centered around SharePoint Framework (SPFx) solutions, so setting that up was my first goal. Everything was going smoothly until I tried to install the certificate that the development web server needs for developing SPFx solutions. From there, I descended down the certificate rabbit hole. After a couple of days of research and asking everyone I know for help, I was finally able to complete the task and decided that I better document it before I forget.

Conferences are slowing coming back and I am personally looking forward to talking to attendees, sponsors, and speakers in person again. First on the agenda this year is the M365 Collaboration Conference (formally the SharePoint Conference) in Orlando, FL, Jun 8-10. The “big” conference is still scheduled for Las Vegas in December, but this is a hybrid event that promises to be an exciting time as we transition from the virtual world we have lived in for the past year. I am honored to be chosen to deliver a couple of sessions during the conference and am looking forward to the trip.

Recently, I built a web part for a client, which led to a discussion about why the web part background was static white, which did not reflect the branding on the page. My quick fix was to just change the color manually, but now I wanted to know more about how I could build webparts that are aware of the area that they are in. It turns out, there are several options, depending on the capabilities needed and the web part framework.

Microsoft warned us! The Document Object Model (DOM) on web pages was a common target in my pre-SPFx solutions, especially the ones that used jQuery. When SPFx came along, Microsoft was very clear that the classes and element ids on the modern page were not an API. By that, they meant that there was no contract with developers that those values would not change in the future. The future is here!

Acknowledging Microsoft’s warning, I vowed to stay in the box and not rely on any classes that were not included as part of my solution. Other than “fixing” the workbench to behave like an actual page in SharePoint, I went a long time before breaking my vow. I have a client that complained non-stop about the white-space between web parts on their intranet homepage. I calmly explained multiple times why Microsoft chose to design the modern page with this white-space, but they insisted that I needed to change it. Eventually, the “client is right” mantra won, so I built a web part that would allow the client to adjust the horizontal and vertical spacing between web parts. Again, I warned them that one day the page might just disappear. Happy client == happy paycheck!

As soon as I got the call about the white-space being back, I had a pretty good idea what happened. Sure enough, when I cracked open the Dev Tools of my favorite browser (Edge), it didn’t take long to find the issue. The two classes I used to adjust spacing were no longer there. There were new classes in their place that seem pretty cryptic, having what appears to be an identifier (partial GUID) as part of the class name. Those class names did not look like a stable place to be targeting at all. To Microsoft’s credit, they (mostly) took the old class names and moved them into an attribute called data-automation-id. Not only did this help track down what had changed, but gave me new targets to “fix” my broken web part for now.

I recently ran into a situation where building and debugging a SPFx web part seemed to go off the rails. Then I figured out that my normal pattern of skipping the ‘gulp clean’ command during project deployment had cause what I thought was bizarre behavior in Site Collection Features and toolbox.

I was working for a client that does not have a dedicated development or QA environment due primarily to political reasons. They also block access to all non-company tenants. Fortunately, I am able to do my development “off network” and once everything is ready, I move the code inside the firewall. Since this was an update to an existing web part, I knew deploying it to the same tenant as the existing web part was going to be tricky. The existing web part is on the company intranet home page, so getting into a site for testing without affecting the original web part meant deploying into a “QA” site app catalog. I thought this would work and there shouldn’t be any conflict. Famous last words …