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.
- @material-ui/core - React components that implement Google's Material Design.
- 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.
- 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.
- 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.
- 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.
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.
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
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!
In the project directory, you can run:
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.
Launches the test runner in the interactive watch mode.
See the section about running tests for more information.
Launches the test runner in coverage mode to generates and display code coverage.
When used in conjunection with VSCode, runs unit tests in debug mode, stopping at breakpoints and interactively debugged through the IDE.
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.
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.
Runs prettier on all source files
Uses source-map-explorer to visualize the dependency tree. Useful to determine what packages are taking up space
Builds a docker container that hosts the app. Requires docker to be installed. See the FAQ for more information.
On pre-commit this boilerplate will:
- 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
eslint
- Integrates ESLint JavaScript into VS Code.debugger-for-chrome
- debug browser apps running in Chrome via VSCode without leaving VSCodejest
- auto-runs unit tests and shows code coverageWallaby.js
- Continuous testing tool for JavaScript (payware)
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.
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:
- Create your app credentials by visiting
https://<your tenant>/_layouts/15/appregnew.aspx
. Record the client id and secret. - 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. - Remove any already-configured authentication by removing the
sp-rest-proxy
folder. - Utilize the app credentials by running
yarn start
and supplying the client id and secret recorded in step 1. - Develop your application.
- 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:
- Build your app using this boilerplate.
- Run
yarn build
- Take the files contained in the ./build folder and add them to a Visual Studio (full) based SharePoint App project.
- 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.
Yes, a sample azure-pipelines.yml
file is part of this boilerplate. The 'Yarn' Azure DevOps extension is required.
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
Remove material ui and add bootstrap
yarn remove @material-ui/core @material-ui/icons
yarn add bootstrap reactstrap
MDBReact is an option as well.
I suggest the Component Folder Pattern
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:
- Develop components/stores that interact with SharePoint in some manner.
- Create unit tests that test these stores.
- 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.
- 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.
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.
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.