In this lab you work with the SharePoint Framework as an end user and then get your local & online environment configured for developing with the SharePoint Framework.
- Create & Configure your SharePoint Online Developer Tenant
- Setup your local SPFx Developer Environment
- Interact with SPFx Client-Side Web Parts in Modern Sites
To complete this lab, you need the following:
-
Office 365 tenancy
If you do not have one, you obtain one (for free) by signing up to the Office 365 Developer Program.
In this exercise you will configure your SharePoint environment to be ready for SharePoint Framework development.
-
Open a browser and navigate to your Office 365 tenant's SharePoint Admin Center site: https://{{REPLACE_WITH_YOUR_TENANTID}}-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx.
Replace the text
{{REPLACE_WITH_YOUR_TENANTID}}in the above URL with the unique prefix for your Office 365 tenant. -
Select Classic features in the left-hand navigation.
-
Select the Open button under Apps.
-
When the new page opens, select App Catalog.
If you are taken to an app catalog site as shown in the following image, then your tenant already has an app catalog, created by someone previously. In this case, you can skip to the next step to create a developer site collection.
Otherwise, if you are presented with a form to create an app catalog (as shown in the following image), your tenant does not already have an app catalog. In this case, continue with the following steps to create an app catalog.
-
Select Create a new app catalog site option & select the OK button.
-
On the Create App Catalog Site Collection page, enter the following details and select OK.
- Title: app catalog
- Web Site Address (suffix): appcatalog
- Administrator: enter your username & select the check names icon to resolve your username
SharePoint Online will provision the app catalog for the tenant.
-
Open a browser and navigate to your Office 365 tenant's SharePoint Admin Center site: https://{{REPLACE_WITH_YOUR_TENANTID}}-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx.
Replace the text
{{REPLACE_WITH_YOUR_TENANTID}}in the above URL with the unique prefix for your Office 365 tenant. -
On the SharePoint Admin Center site, select Sites > Active sites from the left-hand navigation and then select Create.
-
On the Create a site panel, select the Other options button.
-
On the Other options panel, keep the default value of Team site in the Choose a template dropdown and then enter the following values to create a new team site collection and select Finish.
- Site name: Developer Site
- Site address: ../sites/DeveloperSite
- Primary administrator: use the people picker to select your account
- Select a language: English
NOTE: After a few minutes the site collection will be created. On the SharePoint Admin Center site, select the Sites > Active Sites item in the left-hand navigation. You will see a list of all classic and modern sites including the Developer site that you just created.
In this exercise you will setup your local developer environment with everything you need start creating SharePoint Framework components.
You will need a text editor to edit your code files. There are no requirements for what you need in a text editor.
The remainder of this lab & most examples you find from Microsoft use Visual Studio Code.
The tools used in compiling, debugging and packaging SharePoint Framework projects are built using Node.js, a runtime that enables JavaScript to run locally vs. a browser. Therefore the first step is to install the runtime, Node.js, before installing the required tools.
Node.js is available in two different releases: the long term support release (aka: LTS) is the most stable version that is recommended for most users while the current version contains the latest features. Before installing Node.js, you should verify you haven't previously installed it as part of another install. Open a command prompt or terminal (depending on your developer platform) and execute the following command:
node -vIf a version number is returned, you already have Node. The SharePoint Framework build toolchain is tested and supported against the 8.x and 10.x LTS versions. So, if you have version 10.x you do not need to download and install a newer version. If you have version 9.x you should install the current LTS version. If you have version 8.x you have the option to keep the current version or install the current LTS version. Finally, if you have version 7.x or earlier you should install the current LTS version.
If you do not need to install the current LTS version of Node then skip to the next section.
-
Open a browser and navigate to the Node.js Foundation site: https://www.nodejs.org.
-
Select Downloads from the top menu navigation.
-
Select LTS and then select the installer for your developer environment. Both Windows and macOS installers are available. This page contains options for additional installs as well such as SunOS, Linux, AIX and even source code downloads.
-
Run the installer to install Node.js and the included version of NPM (a package manager that Node.js uses, similar to .NET's NuGet).
The SharePoint Framework development experience utilizes a set of tools built on Node.js that are popular among web developers. These tools are built on Node.js which means they can be used on any platform and will work the same way. This includes Windows, macOS and Linux.
-
Install Yeoman - http://yeoman.io
Yeoman is a scaffolding engine which executes generators that prompt the user with questions. Based on the answers to these questions, Yeoman then creates the folders and files defined by the generator.
-
Open a command prompt / terminal window and execute the following command to install Yeoman globally with NPM:
npm install --global yo
-
-
Install the SharePoint Framework Yeoman generator.
Microsoft has created a Yeoman generator for scaffolding SharePoint Framework projects.
-
Open a command prompt / terminal window and execute the following command to install the SharePoint Framework Yeoman generator globally with NPM:
npm install --global @microsoft/generator-sharepoint
-
-
Install Gulp - https://gulpjs.com
Gulp is a task runner utility. It's similar to MSBuild, a tool used by .NET developers and Visual Studio to compile projects, package solutions into redistributes and start a debugging experience.
-
Open a command prompt / terminal window and execute the following command to install Gulp globally with NPM:
npm install --global gulp
-
In this exercise you will add and interact with SharePoint Framework based client-side web parts in a SharePoint Online modern site collection.
-
Open a browser and navigate to the development site you created in the first exercise. If prompted, login using your Work or School credentials.
-
Select the Pages link in the left-hand Quick Launch navigation menu.
-
In the Pages library, select the New button from the toolbar and select Site Page to create a new page.
-
Set the name of the page to Getting Started.
-
Select the web part icon button to open the list of available web parts.
-
Select the web part Text.
-
When the web part is added to the page, add some text and use the rich-text formatting tools provided in the toolbar.
-
Click Save as draft to see the page as your users will see it.
NOTE: The instructions below assume you are using v1.9.1 of the SharePoint Framework Yeoman generator.
Use the tools installed in exercise 2 to create a new SharePoint Framework component and test it in the local developer environment.
-
Open a command prompt and change to the folder where you want to create the project.
-
Run the SharePoint Yeoman generator by executing the following command:
yo @microsoft/sharepoint
Use the following to complete the prompt that is displayed:
- What is your solution name?: HelloWorld
- Which baseline packages do you want to target for your component(s)?: SharePoint Online only (latest)
- Where do you want to place the files?: Use the current folder
- Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites?: No
- Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant?: No
- Which type of client-side component to create?: WebPart
- What is your Web part name?: HelloWorld
- What is your Web part description?: HelloWorld description
- Which framework would you like to use?: No JavaScript framework
After provisioning the folders required for the project, the generator will install all the dependency packages using NPM.
-
When NPM completes downloading all dependencies, run the project by executing the following command:
gulp serve
-
The SharePoint Framework's gulp serve task will build the project, start a local web server and launch a browser open to the SharePoint Workbench.
-
Select the web part icon button to open the list of available web parts.
-
Select the HelloWorld web part.
-
Edit the web part's properties by selecting the pencil (edit) icon in the toolbar to the left of the web part.
-
In the property pane that opens, change the value of the Description Field. Notice how the web part updates as you make changes to the text.
-
Close the browser and stop the local web server by pressing CTRL+C in the command prompt.
