HelloWorld WebPart

Overview

This repository contains a sample WebPart built for the SharePoint Framework (or SPFx). It uses React for components, Sass for styles and the @pnp/pnpjs library to interact with SharePoint APIs.

Prerequisites

You need a Node.js installation in one of the following versions:

1. v10.x for SharePoint Server 2019 or SharePoint Online
2. v8.x.x for SharePoint Server 2016 (requires the NODE_NO_HTTP2=1 environment variable)

After that, use the following command to install the global development dependencies:

• npm i -g gulp yo @microsoft/generator-sharepoint

Getting started

1. After cloning the repository, install the project dependencies:

• npm i

2. You must trust the security certificate generated by SPFx:

• gulp trust-dev-cert

3. Finally, use the command below to start a local instance of the SharePoint Workbench:

• gulp serve

4. Open the WorkBench to develop your WebPart locally:

• https://localhost:4321/temp/workbench.html

Interacting with SharePoint

You can develop the WebPart using real data from a SharePoint instance. This is possible through the remote version of the WorkBench. If you intend to use only that one, start the solution with the command below:

• gulp serve --nobrowser

Then, open the following route to use the remote version of the WorkBench:

• https://your-tenant.sharepoint.com/_layouts/workbench.aspx

Note that the data returned by the SharePoint API in the WorkBench is relative to the site present in the URL. When your WebPart queries the API for the current site's existing lists, the route above will return the root site's lists. The route below, on the other hand, will return the lists present in the site specified in the URL. For example:

• https://your-tenant.sharepoint.com/sites/your-site/_layouts/workbench.aspx

Keep this in mind while developing your WebPart. Whenever possible, use the WorkBench from the site where your WebPart will be deployed so you work with the intended data.

Deployment environment

You need to create an "App Catalog" site to host your WebParts if one does not exist yet. That is where you can manage the WebParts available to the SharePoint instance.

1. To create it, open the SharePoint Admin Center with an administrator account through the following route:

• https://your-tenant-admin.sharepoint.com/ (just add -admin)

2. Go to the "More Features" page and, under "Apps", select "Open".

3. Inside the "Apps" page, select "App Catalog" and click "OK".

4. On the next page, fill in your app catalog details:

• Title: Apps
• Web Site Address suffix: apps
• Administrator: pick an account to be the site admin

5. Finish creating the app catalog by clicking "OK".

6. Within a few minutes it will be created and active. To open it, use the following route:

• https://your-tenant.sharepoint.com/sites/apps

Deploying the WebPart

You need to generate a distribution package of the WebPart containing its files, minified and ready for deployment. After that, you must upload the WebPart package to an "App Catalog" site so the solution becomes available to be added to sites of a SharePoint instance.

1. Generate the solution package with the following commands:

• gulp bundle --ship
• gulp package-solution --ship

2. After that, open your "App Catalog" site and go to "Apps for SharePoint".

3. Upload your WebPart package or drag and drop it in the middle of the page.

4. In the window that appears, check which domains your solution will fetch content from.

• If "localhost" is listed, that means it will only work while your local server is running.
• If "SharePoint Online" is listed, your static files will be served directly from your SharePoint instance's app catalog or from Microsoft's CDN (see the article at the end to learn how to enable it).

5. Click "Deploy" to finish.

Adding your WebPart to a site

1. Open the site where you intend to use your WebPart.

2. Click the "New" button and select "App" (you can also get there through the gear icon in the top right corner).

3. Under "Apps you can add", find your WebPart and click it to install it.

4. In a few moments, your WebPart will be ready to use.

Architecture

This solution contains two sample services for interacting with the SharePoint API. The first service, BasicHttpService, uses the HTTP client made available through Javascript by the SharePoint context. It is a fairly basic and rather manual implementation. The second service, SPHttpService, is much more robust, since it uses the @pnp/pnpjs library under the hood. It ships with many ready-made features and its API covers different aspects of the SharePoint Framework.

Finally, using the second service is made easier by the serviceScope. This variable acts as a container for SPFx dependency injection. Through it, you can register your service class and get an instance from anywhere in your application.

Both services were added as examples of how to interact with the SharePoint API. In the React component HelloWorld.tsx, you can see both of them being used.

Whenever possible, use SPHttpService as a reference both for creating your own services with the serviceScope and for interacting with the SharePoint REST API.

Files

• config/package-solution.json: general data about the WebPart
• sharepoint/solution/helloworld-webpart.sppkg: artifact produced to deploy the WebPart
• src/webparts/helloWorld: main folder of the WebPart
• src/webparts/helloWorld/components: React components of the WebPart
• src/webparts/helloWorld/loc: strings and translations of the WebPart
• src/webparts/helloWorld/HelloWorldWebPart.manifest.json: default configuration of the WebPart
• src/webparts/helloWorld/HelloWorldWebPart.ts: main file of the WebPart

References

• Build your first SharePoint client-side web part (Hello World part 1)
• How to get started with React for building advanced SPFx solutions
• How to use the service locator pattern in SPFx React solutions
• SPFx – scoped context services
• Basic Tutorial · OData - the Best Way to REST

See more

• How to enable the Microsoft 365 CDN
• Official library for interacting with the SharePoint REST API
• Official React component library for the SharePoint Framework