Learning React JS in the SharePoint Framework

SPFXandReact

This month, Microsoft released RC0 of the SharePoint Framework (SPFX), and all first-release tenants would now be able to use SPFX — although the technology is still in preview. With these milestones met, it’s now time for developers to move beyond the theoretical and into the practical applications of SPFX.

 

 

For traditional Office and SharePoint developers, the move to SPFX presents several challenges. First, SPFX makes use of several open-source technologies such as NodeJS, NPM, and Gulp. Second, all of the samples and demonstrations make use of the Visual Studio Code development environment instead of Visual Studio. Third, SPFX development assumes knowledge of JavaScript frameworks such as React. All of this means that traditional Office and SharePoint developers have a lot to learn and should get started right away.

For this article, I am going to focus on introducing the React framework in SPFX. There are already a lot of “getting started” articles around SPFX, but I’ll have to cover some basics in order to take a look at the code generated in a typical SPFX project and explain the basics of the React framework. Although SPFX can support any number of JavaScript frameworks, learning the React framework for SPFX development is a good idea because the SPFX tooling can automatically generate React components for you. Additionally, SPFX makes use of React components and concepts.

Introducing React

React is a JavaScript framework for building user interfaces that can react to changes in application state. The UI is broken down into small components that can be nested, which simplifies development and maintenance. So, for example, you might define a navigation menu with child components that represent lists and links. As the state of the components changes, react can redraw them for you without tedious DOM manipulations on your part.

For the SharePoint developer, React is important because Microsoft made a decision to give it a prominent role in SPFX. Additionally, React is well-suited for client-side web part development, which tends to focus more on UI development. This stands in contrast to more complex frameworks, such as Angular, which are oriented around creating entire single-page applications (SPA).

Setting Up the Development Environment

Before generating a new client web part with SPFX, you must set up an appropriate development environment. Setting up the environment entails getting an Office 365 tenancy as well as the appropriate development tools. Although Microsoft has detailed set up instructions available, you only need a minimal development environment to start to learn React for creating web parts.

If you’re a traditional Office and SharePoint developer, then you probably have Visual Studio 2015 installed already. When working with SPFX, however, you will need to install Visual Studio Code. Next, you should install the latest version of NodeJS.

Once NodeJS is installed, you can install additional tooling using the Node Package Manager (NPM). NPM is a command-line package manager that’s similar in concept to the NuGet Package Manager found in Visual Studio. NPM can be invoked from the Node JS Command Prompt. Because it is a command-line utility, it uses text-based arguments to control package installation. The following commands will download the latest version of NPM, Yeoman, Gulp, TypeScript, and the SPFX generator. For this article, I won’t spend much time on the toolchain, but you can read about it in more detail here.

npm i -g npm@3
npm i -g yo
npm i -g gulp
npm i -g typescript@latest
npm i -g @microsoft/generator-sharepoint@latest

The first command installs version 3 of the Node Package Manager. As you work with new drops of SPFX, they may have requirements for newer versions of packages. The second command installs the Yeoman Generator package. Yeoman is really nothing more than your “new project” dialog. This package is the foundation for the SPFX project generator. The third command installs Gulp, which is used for building sort of like build targets in Visual Studio. The fourth command installs the latest version of TypeScript. The last command installs the latest version of the SPFX generator.

Generating a New Project

Once the development environment is created, you can simply and quickly create a new client web part. First, create a new folder where the project will be generated. Second, change the directory in the NodeJS command prompt to point to the new directory. Finally, invoke the SPFX generator using the following command.

yo @microsoft/sharepoint

The SPFX generator will ask for some information such as project name and project description before generating the new project. For this article, the most important question is regarding the target framework, which should be set to React. After you answer all the questions, the SPFX generator will create all the project files. When it is complete, you can open the project folder in Visual Studio Code. The new project is a fully-functional web part that can be executed directly from the NodeJS command prompt by invoking gulp serve.

React in the SharePoint Framework

When a project is created, SPFX will define a new client web part by inheriting from BaseClientSideWebPart. The name of the web part is set when you run the Yeoman generator. The form of the web part definition looks like the following code.

​export default class MyWebPart extends BaseClientSideWebPart<IMyWebPartProps>

When using React with the SPFX, your web part will override the constructor for BaseClientSideWebPart in order to be able to pass in the properties of the web part. Properties are a key concept in React. Components use property values to determine how to render themselves, and properties are considered immutable. You can think of properties as things such as a title or identifier for an element, but the key thing to remember is that these values do not change after the component is created. In SPFX, the properties for your web part are broken out into a separate interface. The simple web part generated by the tooling has only a description property defined as shown in the following code.

​export interface IMyWebPartProps {
description: string;
}

React components implement the render method to define the HTML to be rendered when a component is drawn. The simple web part generated by the tooling breaks out the rendering into a separate React component that displays static HTML. The following shows a greatly-simplified version of the rendering code.

​export default class ReactBasics extends React.Component<IReactBasicsProps, {}> {
public render(): JSX.Element {
  return <p className='ms-font-l ms-fontColor-white'> {this.props.description}</p>;
}

When writing the rendering code, you may make use of an XML syntax known as JSX. JSX is a preprocessor step that adds XML functionality to JavaScript. This allows you to write the desired HTML directly into the React component, greatly simplifying the task of defining the user interface. In the code above, you can also see how the component properties are used by enclosing them in curly braces.

Along with properties, React also has the concept of component state. State is the data associated with your React component, and it may change at any time. When state changes, React will redraw the component to reflect the change in state. You can think of state as the dynamic data to render in the UI. For example, you may run a REST query to retrieve all of the lists in a site and display them. Initially, your component state might be empty and, as a result, you might show a “loading” message. After the asynchronous REST query returns, your state changes and the component redraws displaying the set of lists. Unfortunately, the simple component generated by the tooling does not utilize any state changes. So, I’ll have to save that for another article.

Conclusions

Getting started with React in SPFX is relatively simple because the tooling generates all of the required artifacts for you. However, if you are a traditional Office and SharePoint developer, learning the new tooling as well as a new JavaScript framework can feel a bit overwhelming. In order to begin the learning process, you should generate a simple React component and then strive to understand the roles of properties, state, and the render method. In future articles, I’ll create more complex parts to examine React in more depth.