SharePoint Framework SPFX with Angular2

SharePoint framework is the new client site development model. With the new Office 365 User Interface, the Page framework model has been changed altogether. Microsoft built a new framework to deliver customized User Interfaces in the form of Client Side web parts. The advantages of using the new SharePoint Framework (SPFX) can be listed as follows:

• Replacement for Script Editor or Content Editor Web Parts.
• No need to store custom settings for our web part in the form of SharePoint Lists. 
• Use of popular Client side frameworks link Angular, Angular2, Knockout, React etc.

The blog will be based on the following sections. Each section has its own significance and can be skipped if you are already aware regarding particular section.

1. Setting up Office 365 tenant
2. Setting up your development environment
3. Building your first Client web part using Angular2

1. Setting up Office 365 tenant

Sign up for an Office 365 tenant

Sign up for the Office Developer Program. You will receive a welcome mail with a link to sign up for an Office 365 Developer Tenant.
Note: Make sure that you are signed out of any existing Office 365 tenants before you sign up.

Create app catalog site

You will need an app catalog to upload and deploy web parts.
Go to the SharePoint Admin Center by entering the following URL in your browser. Replace yourtenantprefix with your Office 365 Developer Tenant prefix.

https://yourtenantprefix-admin.sharepoint.com

In the left sidebar, choose the apps menu item and then choose App Catalog.
Choose OK to create a new app catalog site.
In the next page, enter the following details:

• Title: Enter App Catalog.
• Web Site Address suffix: Enter your preferred suffix for the app catalog; for example apps.
• Administrator: Enter your username and choose the resolve button to resolve the username.

Choose OK to create the app catalog site.
SharePoint will create the app catalog site and you will be able to see its progress in the SharePoint admin center.

Create a new Developer Site collection

You also need a Developer Site.
Go to the SharePoint Admin Center by entering the following URL in your browser. Replace yourtenantprefix with your Office 365 Developer Tenant prefix.

https://yourtenantprefix-admin.sharepoint.com
In the SharePoint ribbon, choose New -> Private Site Collection.
In the dialog box, enter the following details:

• Title: Enter a title for your developer site collection; for example, Developer Site.
• Web Site Address suffix: Enter a suffix for your developer site collection; for example dev.
• Template Selection: Select Developer Siteas the site collection template.
• Administrator: Enter your username and choose the resolve button to resolve the username.

Choose OK to create the site collection.
SharePoint will create the developer site and you will be able to see its progress in the SharePoint admin center. After the site is created, you can browse to your developer site collection.

SharePoint Workbench

SharePoint Workbench is a developer design surface that enables you to quickly preview and test web parts without deploying them in SharePoint. SharePoint Framework developer toolchain contains a version of the Workbench that works locally and helps you quickly test and validate solutions you are building. It is also hosted in your tenancy to preview and test your local web parts in development. You can access the SharePoint Workbench from any SharePoint site in your tenancy by browsing to the following URL:

https://your-sharepoint-site/_layouts/workbench.aspx

2. Setting up your development environment

NodeJS

Install NodeJS Long Term Support (LTS) version. Use v4.6.0 LTS version as the latest was not supported and resulted in errors.

• If you have NodeJS already installed, please check you have the latest version using node -v. It should return the current LTS version.
• If you are using a Mac, it is recommended you use homebrewto install and manage NodeJS.

After installing node, make sure you are running V3 of npm by running the following command:
npm install –g npm@3
In case of Ubuntu Linux previous command might result in ‘permission denied’ message, so it should be instead executed as
sudo npm install –g npm@3

Code Editors

Install a code editor. You can use any code editor or IDE that supports client-side development to build your web part, such as:

• Visual Studio Code
• Atom
• Webstorm

If you're using a PC

• • You need to install windows-build-tools. windows-build-tools will install Visual C++ Build Tools 2015, provided free of charge by Microsoft. These tools are required to compile popular native modules. It will also install Python 2.7, configuring your computer and npm appropriately.
  • Run the following command:
    • npm install –g —production windows–build–tools

If you are using Ubuntu

• • You need to install compiler tools using the following command:
    • sudo apt–get install build–essential

If you are using fedora

You need to install compiler tools using the following command:
sudo yum install make automake gcc gcc–c++ kernel–devel

Install Yeoman and gulp

Yeoman helps you kick-start new projects, and prescribes best practices and tools to help you stay productive. SharePoint client-side development tools include a Yeoman generator for creating new web parts. The generator provides common build tools, common boilerplate code, and a common playground web site to host web parts for testing.
Enter the following command to install Yeoman and gulp:
npm install –g yo gulp

Install Yeoman SharePoint generator

The Yeoman SharePoint web part generator helps you quickly create a SharePoint client-side solution project with the right toolchain and project structure.
Enter the following command to install the Yeoman SharePoint generator:
npm install –g @microsoft/generator–sharepoint 
Important: Make sure for npm install command to install the relevant packages:

• the command prompt is opened using “Run as Administrator”
• Prompt defaults to System drive (“C:” in my case). 

3. Building your first Client web part using Angular2

Create a new project directory in your favorite location.
md Angular2App
Go to the project directory.
cd Angular2App
Create a new HelloWorld web part by running the Yeoman SharePoint Generator.
yo @microsoft/sharepoint
When prompted:

• Accept the default Angular2Appas your solution name and choose Enter.
• Select Use the current folderfor where to place the files.

The next set of prompts will ask for specific information about your web part:

• Accept the default Angular2Appas your web part name and choose Enter.
• Accept the default Angular2App descriptionas your web part description and choose Enter.
• Accept the default No javascript web frameworkas the framework you would like to use and choose Enter.

At this point, Yeoman will install the required dependencies and scaffold the solution files along with the Angular2App web part. This might take a few minutes.
When the scaffold is complete, you should see the following message indicating a successful scaffold:

For information about troubleshooting any errors, see Known issues.

Preview the web part

To preview your web part, build and run it on a local web server. The client-side toolchain uses HTTPS endpoint by default. However, since a default certificate is not configured for the local dev environment, your browser will report a certificate error. The SPFx toolchain comes with a developer certificate that you can install for building web parts.
To install the developer certificate for use with SPFx development, switch to your console, make sure you are still in the Angular2App directory and enter the following command:
gulp trust-dev-cert
Now that we have installed the developer certificate, enter the following command in the console to build and preview your web part:
gulp serve
This command will execute a series of gulp tasks to create a local, Node-based HTTPS server on ‘localhost:4321’ and launch your default browser to preview web parts from your local dev environment.

SharePoint client-side development tools use gulp as the task runner to handle build process tasks such as:

• Bundle and minify JavaScript and CSS files.
• Run tools to call the bundling and minification tasks before each build.
• Compile SASS files to CSS.
• Compile TypeScript files to JavaScript.

If you are new to gulp, you can read Using Gulp which describes using gulp with Visual Studio in conjunction with building ASP.NET 5 projects.
Visual Studio Code provides built-in support for gulp and other task runners. Choose Ctrl+Shift+B on Windows or Cmd+Shift+B on Mac to debug and preview your web part.

Important Note:
If you get any errors similar to the one below it is due to Typescript version 2.1:

Resolution:
The issue can be resolved by running the following command in the Angular2App folder:
npm install @types/lodash@4.14.50

SharePoint Workbench

SharePoint Workbench is a developer design surface that enables you to quickly preview and test web parts without deploying them in SharePoint. SharePoint Workbench includes the client-side page and the client-side canvas in which you can add, delete and test your web parts in development.

To add the HelloWorld web part, choose the add button. The add button opens the toolbox where you can see a list of web parts available for you to add. The list will include the HelloWorld web part as well other web parts available locally in your development environment.

Choose HelloWorld to add the web part to the page:

Congratulations! You have just added your first client-side web part to a client-side page.
Now, choose the pencil icon on the far left of the web part to reveal the web part property pane.

The property pane is where you can define properties to customize your web part. The property pane is client-side driven and provides a consistent design across SharePoint.
Modify the text in the Description text box to Angular2App Hello World

Notice how the text in the web part also changes as you type.

One of the new capabilities available to the property pane is to configure its update behavior, which can be set to reactive or non-reactive. By default, the update behavior is reactive and enables you to see the changes as you edit the properties. The changes are saved instantly as when the behavior is reactive.

Angular2 SharePoint Framework Integration

• • Firstly, replace the dependenciesin the json file with the one below:

The highlighted text will load all dependencies required for Angular2 integration.

• Open Command window from the solution directory by pressing Shift on keyboard + Right Mouse Click > Open command window here
• Run the following command to load all the angular2 dependencies for the project:

npm install

• Now open the solution directory in your favorite code editor. I will be using VSCodefor this blog but you can use any of the code editors as mentioned above.
• Modify the tsconfig.json to match the contents below:

• • Add a new folder app in the following hierarchy Angular2App > src > webparts > angular2App of the solution directory
  • Create two new typescript files within the app folder namely: “module.ts” and “app.component.ts”
  • Modify the contents of component.ts to define a simple text and input field as follows:

• • Create a template file under your app folder:

• • Modify the contents of module.ts to register your component:Note: Step 8-9 will be repeated for each new component. i.e. Each component will define two typescript files. A module file and a component file exposing the actual component
    • Locate and open the Angular2WebPart.ts. The file can be located within the following directory structure:

• • Add the following lines of text to top of the Angular2AppWebPart.ts file before the export default class line:

  
  import 'reflect-metadata';
  
  import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
  import { AppModule } from './app/app.module';
  require('zone.js');
  

• • Replace contents of render function of the web part as follows:

  
  public render(): void {
  this.domElement.innerHTML = '';
  platformBrowserDynamic().bootstrapModule(AppModule);
  }
  

This references component selector you identified in angular

• • Save all files in VSCode and run the following command:

gulp serve

• • Running Angular2 Client web part in the SharePoint Workbench can be seen from the image below:

Summary

This blog gives us the basic introduction to SPFX framework and integration with Angular2
In this blog we covered the following points:

• How to setup Office 365 tenant
• How to setup development environment
• How to develop and integrate Angular2 with SPFX framework.

If you have any questions about the SharePoint Framework, please let us know by filling out the contact form below.