Tips for Getting Started with SharePoint Custom Development

SharePoint custom development has come a long way since SharePoint’s inception in 2001. The latest front is the SharePoint Developer Framework (SPFx), a suite of tools Microsoft released in 2017 for extending SharePoint Online, SharePoint 2016, and SharePoint 2019. It served as relaunch (much like SharePoint Online did) of features that had laid dormant in SharePoint because of Microsoft’s focus on other platforms. Well, SharePoint is cool again, and the SharePoint Developer Framework continues to be one of the best parts of modern SharePoint.

Here at Regroove, we’ve built dozens of web parts and extensions using the SharePoint Developer Framework, and over the past three years we’ve come up with our own set of best practices and tips for working with it. This article isn’t talking about how to literally setup a new SharePoint web part since Microsoft already has a good series of articles on that. Rather, these are five tips for using the SPFx that simplifies the process a bit and makes SharePoint custom development that much easier.

One last note: These tips focus on the web part portion of the SharePoint Framework and not extensions. Although some of the tips may apply to extensions there are no guarantees. The same goes for SharePoint 2016 and SharePoint 2019: since those versions of SharePoint are stuck with older versions of the Framework, our tips may not work. Our SharePoint custom development experience is in SharePoint Online.

1. Add a custom start command

Included in the standard SPFx project is a whole bunch of gulp commands to work with the project. Gulp is a toolkit and task runner for transforming your code, in this case into something that SharePoint can run. There are a bunch of included commands that do different things to your project, with the main one being “gulp serve”. “gulp serve” compiles your code and runs it locally so you can work on it without needing to upload it to a SharePoint site.

You’ll be running “gulp serve” a lot (and probably finding that you’ll be using the “-nobrowser” flag since you don’t want a new window every time the project starts) while working on your webpart. If you’ve done JavaScript development before, though, you’re probably more used to using NPM and the “npm start” command to get going. “Npm start” is the standard command to start developing, and almost every project uses it. However, the default SharePoint Framework project doesn’t come with an “npm start” command.

The first thing I do on every webpart I work on is add a new “npm start” command. All you need to do is make the following edit to your “package.json” file:

"scripts" : { "start": "gulp serve --nobrowser", ... },

And, going forward, all you need to do is type “npm start” in your terminal to get everything going. Even better, some editors (like VS Code) will automatically detect the command and give you a button to run it.

2. Simplify building your extension

Now, just like how gulp is used to start your project, gulp is also used to bundle your package and get it ready for upload. In version 1.4 of the SPFx Microsoft simplified uploading packages into one step, but packaging your project is spread out across two commands that require extra flags for them to work properly. Those two commands are

1. “gulp bundle — ship”
2. “gulp package-solution — ship”

You need to run those exact commands every time you want to upload your code. Running only one of the commands won’t give you the files you need to upload to SharePoint and skipping the “-ship” flag will build an app that is still looking for your local code.

You’ve probably guessed where this tip is going. Using NPM as our task runner on top of gulp, you can combine these commands into one command that is easily run. And, just as “npm start” is the standard command for starting a project, “npm run build” is the standard command for packaging it all up.

So, just as how I always add a “npm start” command to every webpart I work on, I also add a “npm buid” one:

"scripts" : { "start": "gulp serve --nobrowser", "build": "gulp bundle --ship && gulp package-solution --ship", ... },

3. Use the site workbench, not the local one

Once your project is running locally, you need to use something called the “workbench” to actually see and interact with it. The workbench is a special SharePoint page that is able to display your webpart without you needing to upload it.

By using a real list with the actual columns I’m going to interact with I can make sure I’m getting all my behaviour right. However, the list doesn’t have to contain real data.

There are two different workbenches. One Microsoft provides as a local workbench built into the SharePoint Framework, but every SharePoint site also has a workbench you can use. The URL for the workbench is always the same:

“YOUR SITE URL/_layouts/15/workbench.aspx”

So, on the site https://regroove.sharepoint.com/sites/Navo the workbench URL is “https:// regroove.sharepoint.com/sites/Navo/_layouts/15/workbench.aspx”

I only ever use the site-based workbench, for a few different reasons:

1. It lets me interact with the real SharePoint APIs, whether it’s a list on that same SharePoint site or a call to the user profile service
2. It’s easy to run under different profiles or in different tenancies (using Chrome Profiles)
3. Microsoft is deprecating the local workbench

The first point is key. Working with the real APIs is the best way to test your code, and, as long as you’re using test data, you can be sure your code will work once it’s pushed out.

Quick note about working with data in SharePoint: Almost all of my SharePoint web parts interact with a list somehow, which brings along with it all the quirks that lists have (expansion, selects, limits, etc.). By using a real list with the actual columns I’m going to interact with I can make sure I’m getting all my behaviour right. However, the list doesn’t have to contain real data. In fact, the list can be a copy of the target list, with dummy data added to it. In that way you’re working with a real list with test data, as opposed to a mocked list.

4. Extend TypeScript (or turn it off!)

There are two big decisions that Microsoft made with the SharePoint Framework: It uses CSS Modules and it uses TypeScript. Now, with some work you can remove both of these technologies, but at the end of the day Microsoft put them in there for a reason.

I love TypeScript. Almost every development project we do here at Regroove uses it and we’ve seen some huge benefits. However, even I can admit TypeScript is annoying sometimes. Especially with webparts.

One of the worst parts about the Microsoft scaffolding is that building fails on any type errors, even if they’re warnings. If you’re like myself, that means you’ll do a bunch of work, go to build the project, and then grumble as you have to remove a dozen extra semi-colons that aren’t hurting anyone but don’t have to be there.

I love Typescript… [but] even I can admit TypeScript is annoying sometimes.

So, to avoid situations like that, I always make sure to update the TypeScript configuration to match our own linting policies. This is made a bit more complicated because the webpart is built to use tslint, which has been deprecated in favour of eslint. However, you can still reference the tslint documentation. TSlint is controlled through the “tslint.json” file and that’s where you can turn off any rules bugging you or add additional ones if you want.

If you don’t want to worry about linting at all, you can also remove all the rules from the TypeScript config. Or, add the following comment to the top of every file in your project:

/* tslint:disable */

That will make sure TypeScript linting is skipped.

Finally, if your editor has a tslint extension (like VSCode), make sure to install it. That way you don’t have to wait for the build or for the code to compile to see what needs to be fixed. Also, don’t hold your breath for a switch to eslint: Microsoft has said that tslint is too integral to the build process to be removed anytime soon.

5. Use the site theme whenever possible

Part of the power of the SharePoint Framework comes with how easily it integrates into SharePoint. Tied into this is a set of variables you can use that will reference the theme of the SharePoint site you’re on.

A site theme is a palette of two to three colours. When you’re on a site, you’ll see the theme used all over the place such as in buttons, underlines, and tiles. By using the theme variables in your own webpart your components will match the theme and blend right into the site.

The different theme variables are semantic, meaning they describe the purpose of the colour instead of the actual colour. For instance, the buttons or icons on the site use the “themePrimary colour”. To use that colour yourself you just need to assign the variable to the value, like so:

.button { /* ... */ background-color: "[theme: themePrimary, default: #0078d7]"; border-color: "[theme: themePrimary, default: #0078d7]"; /* ... */ }

It is especially important to use the variables if your web part is going to be used on a bunch of different sites. Without them you would need to worry about picking unobtrusive colours or making the colours customizable. With the theme variables, you can guarantee (almost) that the colours will fit.

Even if your web part is living on one site, there’s no guaranteeing the site’s theme will stay the same through its entire lifetime. By using the theme variables, you no longer need to worry about that.

The other half of making a web part match SharePoint is to use Microsoft’s own UI library Fluent UI (recently renamed from the awkward “Office Fabric UI JS”). If you’re using React, the scaffolded app already includes Fluent UI and you can easily import any of the components.

Fluent is fairly comprehensive and contains most visual components you’ll need, from buttons to lists to different text styles. Better yet, Fluent is setup to use the site theme. It may take a while to get used to the naming (a list view is called DetailedList, a collection of users is a FacePile, etc.), but almost all the SharePoint UI elements are in there.

Bringing it all together

The SharePoint Framework is one of the best things to happen to SharePoint developers in a long time. It modernizes SharePoint in a really smart way, especially with its focus on SharePoint custom development tools and modern web practices that makes SharePoint custom development easier.

These tips are just some of the things we at Regroove have learned working with the SharePoint Framework over the past three years. After all, we built and launched Navo in 2017 (the year the SPFx came out) and have been updating Navo weekly since. In fact, we recently leverage SharePoint’s new pre-allocated space option to smooth out the Navo experience.

What about your own experience? If you’ve been using the SharePoint Framework, we’d love to hear about your own tips. Or, if you have any questions about SharePoint custom development, shoot them our way and we’d be happy to answer them.

Originally published at https://getnavo.com on October 6, 2020.