Introduction to the SharePoint Framework (SPFx)

Although those web parts (SEWP and CEWP) are still available in SPO, scripting is disabled by default now on a lot of sites so they are inaccessible without additional steps being taken by an administrator.

SPFx aims to provide a more coordinated and controlled approach to customising page layouts than the old approach where any user with sufficient site permissions could download a random JavaScript fragment or file they’d read about on the Internet, smash a SEWP on a web parts page, add the JS fragment or file link, and who knows what it would do! 😉

Each SPFx solution is a code project in its own right, with a set of source files, a build pipeline, and a distributable package produced at the end of it (which then needs to be uploaded to SharePoint).

Something interesting is that the development language of choice is TypeScript. If you don’t have any experience of TypeScript then I have written an introduction to it here.

Setting Up Your Dev Environment

Your SPFx development environment will be very similar to recent advances in web development generally: using NPM to download and manage dependencies, Visual Studio Code (or another editor of your choice) to write the code, and gulp and other tools to compile, minify, and bundle your solution.

So, first things first… Let’s set up a development machine so that we can create and build projects:

• Download and install the latest Long Term Support (LTS) version of Node Package Manager (NPM) from here.
• Download and install a suitable code editor if you don’t already have one (e.g. Visual Studio Code).

Creating a New Project

Now the initial prerequisites are satisfied, it is time to get a project off the ground.

Microsoft’s documentation (e.g. here) recommends using “npm install” with the -g argument to do a global installation so you don’t have to install Yeoman and Gulp per-project, but I struggled to get this working reliably. It might be because the PATH variable needs to be updated with locations for Yeoman and Gulp or something but I just chose to keep everything local to the project to increase the likelihood of it building reliably across developers’ machines in a team environment.

To start a new project, do the following:

• Open a command-line prompt or PowerShell session window.
• Change the working directory to project’s root folder (which you’ll need to create if you haven’t already.
• Install ‘yeoman’ and ‘gulp’ using NPM, at the command-line prompt:

npm install -g yo gulpCode language: plaintext (plaintext)

• Next, install the yeoman SharePoint project generator configuration, by typing the following at the command-line:

npm install -g @microsoft/generator-sharepointCode language: plaintext (plaintext)

• Then create a new project scaffold (baseline for your code) using the project generator and yeoman:

yo @microsoft/sharepointCode language: plaintext (plaintext)

• At this point you’ll be asked for some answers to configuration options…
  • Enter a name for your new project.
  • Choose the environment(s) you are targeting.
  • Use the current working folder to create the project files in.
  • Select N when asking if you want to deploy the solution globally.
  • Select N when asked if the solution will contain unique permissions.
  • Finally, choose the type of package you are developing (WebPart or Extension).
  • Depending on the type of project you chose in the previous step you may be prompted with some more options.
• (Optional) if you want to run your project locally in the ‘simulator’ without getting security warnings in the browser you can also trust the self-signed development certificate:

gulp trust-dev-certCode language: plaintext (plaintext)

Your SPFx Project Files

Let’s have a walk around your SPFx project and the files it contains. Off the project root, you are likely to have the following sub-folders:

• config – contains project configuration files.
• dist – used when building/bundling your project into a deployable package.
• images – where your graphics assets should be put.
• lib – used during the build process.
• node_modules – for anyone familiar with NPM you’ll know this is where your local modules will be downloaded to. For example, local copies of the gulp and yeoman modules will be here.
• src – lastly, but most important, this is where your source code files should go and there should already be some example files there by default to get you started.

Assuming you are creating a web part project, one of the first things to consider is if you want it to support SharePoint Online’s new ‘full width’ mode for modern sites. If so then you’ll have to add…

"supportsFullBleed": trueCode language: JSON / JSON with Comments (json)

… to the YourWebPartName.manifest.json file in the src\webparts\YourWebPartName sub-folder.

Developing Your Custom Solution

Now that you know your way around your project folders, it is time to start working on your code. As previously mentioned the files you are going to be most interested in are in the src sub-folder tree. We’ll look at these first and do a bit of development work, and then we can revisit the files in the project’s root folder and explain what they are all for.

So, you’ve got a project scaffold set up from which you can develop a custom web part (or page extension). For convenience, let’s assume you named your web part ‘MyFirst’. That being the case there should be a few files in the src/webparts/MyFirst sub-folder:

• MyFirstWebPart.manifest.json – this contains configuration details (description, properties, etc.) for your web part.
• MyFirstWebPart.module.scss – this is where you specify your custom (CSS) styles.
• MyFirstWebPart.ts – this is the web part code, written in TypeScript!

At this point, if you aren’t familiar with SCSS then I would recommend you do some reading up on it, but basically it is a way to bring something akin to object orientated programming to CSS to make development of large, complex solutions more manageable as CSS style fragments (or ‘mixins’) can be defined once and referenced (or inherited) many times in other styles.

As mentioned at the beginning of this article, we’re also targeting TypeScript (TS) here – not plain JavaScript (JS) – and, while the two look very similar and have a lot of common syntax, there are key differences between them that you need to appreciate. First and foremost, TS is a strongly typed language that brings some order to the wastelands of the invariant data-types that JS wields. TS code is very much aimed at making the development process more manageable but it cannot be run directly itself, and instead must be cross-compiled into JS for distribution/execution.

If you take a look at your TS file, it may look more like a C# source code file than anything else… You’ve got ‘import’ directives at the top, an interface being defined to specify your web part properties, and a class that implements a base-class (with reference to the properties interface).

You may have also noticed at this point that there is an import statement for the styles that are defined in the SCSS file, and that those styles can be referenced as strongly typed CSS class names in the TS code!

Look for the ‘render’ method… this is where your web part visual layout is defined and the method that will be called to render your web part into a host page. As you can see, you can easily create complex layouts if you need to, with HTML controls attached to event handlers, etc. Notice that CSS styles from the SCSS file are referenced in code to directly assign the CSS class to an HTML control.

Main Project Configuration Files

The default structure of the scaffold project is controlled by Microsoft and may change over time.

At the time of writing the following root folder files are of particular merit and worth mentioning:

• .gitignore – used by Git as a basis for which files to ignore from commits to a source code repository (if using Git).
• gulpfile.js – build pipeline configuration file. Used to build the SPFx solution.
• package.json – specifies the NPM packages that are required by the SPFx app.
• tsconfig.json – specifies the TypeScript configuration/compilation settings.
• tslint.json – specifies TypeScript ‘linting’ rules that are used by editors for live coding style compliance checking.
• .editorconfig – used by some code editors to set the rules used for formatting (e.g. tab = 2 spaces or tab = 4 spaces, etc.)

Running Your Project

Once you have finished editing your source code and are ready to preview/test, use can use gulp to compile and serve the web part to a simulation workbench on the localhost that uses mock data…

gulp serveCode language: plaintext (plaintext)

This will start a mini web server at localhost:4321, and will then open your default web browser at that URL.
NOTE: the workbench doesn’t work correctly on Internet Explorer (IE). You’ll need to use a more standards compliant browser instead.

You can also open the workbench on your tenancy too, and as long as the gulp server is still running you should be able to access and test your web part there as well. As an example the URL might be:

https://your-tenancy.sharepoint.com/sites/your-site/_layouts/workbench.aspxCode language: plaintext (plaintext)

or even just:

https://your-tenancy.sharepoint.com/_layouts/workbench.aspxCode language: plaintext (plaintext)

Packaging Your Project for Release

If gulp’s mini web server is running it should trigger on-the-fly re-builds whenever you save changes to your source code. This can be useful but often leads to build errors being displayed because you’ve saved code changes in progress and it doesn’t currently build. No damage should be done, but it can mean the workbench isn’t working half the time!

If you want to ‘clean’ your project at any time then just run this at the command-line prompt:

gulp cleanCode language: plaintext (plaintext)

Once you are ready to bundle and package up your solution for deployment, you can run the following:

gulp bundle
gulp package-solutionCode language: plaintext (plaintext)

The above two commands will bundle and package the project in debug mode (i.e. without any file minification, etc.) The package will be saved to the sharepoint/solution sub-folder off your project root.

The package is deployed just like an Add-in (i.e. to a SharePoint App Catalog).

Once you have tested your project, you can create a minified production deployment package by adding –ship to the end of the previous commands, like this:

gulp bundle --ship
gulp package-solution --shipCode language: plaintext (plaintext)