sharepoint-react-app-boilerplate

An opinionated boilerplate for creating React-based SPAs utilizing TypeScript that are backed by SharePoint REST services.

This boilerplate facilitates the creation of apps that integrate rather than extend SharePoint. With it you can create stand-alone React-based applications, fully-branded experiences, RPAs and tools that utilize SharePoint as a data source. Used as a pre-built starter, this project integrates a number of packages and configuration to ease the developer experience, allowing for the local serve of apps while in development, proxying the SharePoint network communication to an actual SharePoint environment as well as other pre-configured functionality.

This project was bootstrapped with Create React App with typescript and enhanced with the following modules to get started building a full-page SharePoint app as quickly as possible.

UI Components

• @material-ui/core - React components that implement Google's Material Design.

Frameworks

• TypeScript - Static type checking.
• lodash - A modern JavaScript utility library.
• moment - Parse, validate, manipulate and display dates and times in JavaScript.
• axios - Promise based HTTP client for the browser and node.js.

SharePoint

• sp-rest-proxy - Provides a proxy to a SharePoint environment for live testing.
• @pnp/js - Fluent JavaScript API for consuming SharePoint and Office 365 REST APIs with TypeScript support.
• sp-pnp-node - Provides an easy way to use @pnp/js from node with support of various authentication strategies.

Unit Testing

• husky - Hooks git to perform custom tasks on pre-commit.
• nock - Allows for mocking REST endpoints for end-to-end testing without a live backend.
• enzyme - JavaScript testing utility for React that makes it easier to assert, manipulate and traverse React components.

Other

• craco - A package created by the ShareGate team to allow configuring CRA without ejecting.
• prettier - Why lint when you can auto-fomat your code?
• fetch - Fetch support for non-modern browsers.

Getting Started

Prerequisites

To start developing with sharepoint-react-app-boilerplate you'll need a few things: First, make sure you've got a recent version of node.js and git installed.

It is suggested that yarn be used instead of npm. Install yarn with npm install -g yarn

I also recommend VSCode as an editor, but feel free to use whatever editor suits your fancy.

Clone and Install Dependencies

Next, you'll need to clone the sharepoint-react-app-boilerplate repository and install its dependencies.

# clone the repo
$ git clone -o sharepoint-react-app-boilerplate -b master --single-branch https://github.com/rdacorporation/sharepoint-react-app-boilerplate/ my-app

# change directory to your app
$ cd my-app

# install the dependencies with yarn
$ yarn install

Develop

Simply execute $ yarn start to start a local development webserver.

The first time the application runs, it will prompt for your SharePoint environment url and login in order to seamlessly connect to your SharePoint environment

To reset the SharePoint configuration, simply delete the 'sp-rest-proxy' folder and re-run yarn start, it will once again prompt for configuration.

Now, modify the files in your editor as needed!

Available Scripts

In the project directory, you can run:

yarn start

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

yarn test-coverage

Launches the test runner in coverage mode to generates and display code coverage.

yarn test-debug

When used in conjunection with VSCode, runs unit tests in debug mode, stopping at breakpoints and interactively debugged through the IDE.

yarn build

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

yarn deploy

Builds and deploys the app to a /sp-app document library contained in the configured SharePoint web. Configure the desired target document library by editing the corresponding line in package.json.

yarn prettier

Runs prettier on all source files

yarn analyze

yarn analyze-vendor

Uses source-map-explorer to visualize the dependency tree. Useful to determine what packages are taking up space

yarn docker-build

yarn docker-run

Builds a docker container that hosts the app. Requires docker to be installed. See the FAQ for more information.

Commit hooks

On pre-commit this boilerplate will:

1. Execute prettier to ensure code format consistency

if the above fails, the commit will not succeed.

Note: Previous versions of this boilerplate also executed unit tests on commit to ensure a standard of code coverage. In practice, this hindered rather than helped development by reducing commits. If code-coverage on commit is desired, add test-ci to the husky pre-commit hook in package.json

Suggested VSCode Extensions

• eslint - Integrates ESLint JavaScript into VS Code.
• debugger-for-chrome - debug browser apps running in Chrome via VSCode without leaving VSCode
• jest - auto-runs unit tests and shows code coverage
• Wallaby.js - Continuous testing tool for JavaScript (payware)

FAQ

- Why would I use sharepoint-react-app-boilerplate over SharePoint Framework (SPFx)?

If you're extending SharePoint through webparts, application customizers, field customizers, or command sets, SPFx is the choice for you.

If you're integrating SharePoint by treating it as a headless CMS, building React-based apps, RPAs, or tools that interact with SharePoint that are hosted either within or outside of SharePoint, providing a fully-branded experience with SharePoint as the backend without paying the SharePoint branding tax, or composing an React-based application that utilizes SharePoint data in addition to other external services, sharepoint-react-app-boilerplate facilitates these use cases.

- Can I build a docker container that hosts my application?

Yes. The scripts to do so are part of this boilerplate.

yarn docker-build

yarn docker-run

If building a container that runs in a production environment, you may want to configure the dockerfile to run a streamlined express server behind an nginx proxy rather than the currently configured webpack development server.

Note: sp-rest-proxy encrypts credentials with a local machine key, ensure that the sp-rest-proxy options set to encryptPassword: false or supply desired credentials via environment variables.

Be wary of the SharePoint Online REST endpoint limits. You may want to provide a caching layer in between the app and SharePoint to minimize SharePoint traffic (outside the scope of this project).

- Is it possible to have a site created with sharepoint-react-app-boilerplate hosted outside of SharePoint, that uses an app account to retrieve content? (NodeJS-based Provider Hosted App using App Credentials)

Yes, the recommended approach to doing so is:

1. Create your app credentials by visiting https://<your tenant>/_layouts/15/appregnew.aspx. Record the client id and secret.
2. Modify the app permission level by visiting https://<your tenant>/_layouts/15/appinv.aspx and supplying the desired permissions xml and by creating and trusting it on the same page.
3. Remove any already-configured authentication by removing the sp-rest-proxy folder.
4. Utilize the app credentials by running yarn start and supplying the client id and secret recorded in step 1.
5. Develop your application.
6. Host the application using sp-rest-proxy. For instance, by following the steps above to build a docker container, pushing it to a docker hub and utilizing hosting services such as DigitalOcean, Azure App Service for Containers or AKS.

- Can I deploy my application that I created with sharepoint-react-app-boilerplate via a SharePoint app?

Yes - this has been done with this boilerplate.

The general strategy is:

1. Build your app using this boilerplate.
2. Run yarn build
3. Take the files contained in the ./build folder and add them to a Visual Studio (full) based SharePoint App project.
4. Build and deploy the app with Visual Studio.

These steps can be performed as part of a CI/CD process by dynamically generating a .csproj and inserting the files contained in the ./build folder. This has been done before with this boilerplate, but we currently don't provide the generator project, scripts or template to do so.

- Can I use sharepoint-react-app-boilerplate as part of an Azure DevOps build pipeline?

Yes, a sample azure-pipelines.yml file is part of this boilerplate. The 'Yarn' Azure DevOps extension is required.

- Can I use Office UI Fabric instead of Material Design?

Yes, simply remove the material design package and add office ui fabric

yarn remove @material-ui/core @material-ui/icons

yarn add office-ui-fabric-react

- I'm more familiar with Bootstrap for styling, how do I use Bootstrap instead of Material Design?

Remove material ui and add bootstrap

yarn remove @material-ui/core @material-ui/icons

yarn add bootstrap reactstrap

MDBReact is an option as well.

- This is a start, but how should I structure my components?

I suggest the Component Folder Pattern

- Can I interactively debug with VSCode while running this boilerplate?

Yes - It's a bit finicky, but it works most of the time all of the time.

Two VSCode launch configurations exist to allow for debugging unit tests and attaching to an existing Chrome instance to allow for debugging (debugger-for-chrome VSCode extension is required).

You may also find success by ensuring that VSCode is configured to 'Auto-Attach' (configuration exists in this project to do so by default) and running yarn test-debug in VSCode terminal to debug unit tests. The bottom bar should turn orange and VSCode will stop at breakpoints.

If you have a way of making this process more streamlined and reliable, through better VSCode launch configuration or other avenues, we welcome the pull request.

- Can I run the unit tests on an automated build server that doesn't have access to a SharePoint environment?

Yes - This boilerplate utilizes Nock to record and mock the SharePoint REST requests/responses. Follow the pattern in ./src/services/*.test.ts to setup your tests to mock the interaction with SharePoint so that concerns are seperated and you're only testing the front-end components. This solves a plethora of issues commonly encountered when attempting to utilize CI/CD practices while providing a reasonable amount of code coverage with SharePoint (or other) backed REST services.

In General:

1. Develop components/stores that interact with SharePoint in some manner.
2. Create unit tests that test these stores.
3. Run the unit tests so that corresponding test fixtures in ./nock_fixtures/ are created. Remove the ./nock_fixtures folder and re-run if you wish to run all unit tests directly against your SharePoint environment.
4. Once unit tests pass, commit changes along with the ./nock_fixtures/ folder.

If you have automated builds on commit configured, your build server will run the unit tests using the mocked responses, thus not requiring a live connection to a SharePoint environment from the build server. Consult the nock documentation for further information and advanced scenarios.

- How do I upgrade the packages within my app?

I highly recommend npm-check-updates. Install with yarn install -g npm-check-updates and run with ncu in your project folder.

- Can I use sharepoint-react-app-boilerplate in conjunction with other projects stored in a single repository?

I would recommend to use sharepoint-react-app-boilerplate within a monorepo approach. Go multi-repo if that suits your project/team.

- What projects has sharepoint-react-app-boilerplate been used on?

We have used sharepoint-react-app-boilerplate on a number of customer-facing projects hosted on SharePoint. The Brightcove SharePoint Connector is also based on this boilerplate.