This SharePoint Freamework toolchain represents a set of building tools, libraries and framework packages which help building and deploying client side projects. Toolchain helps to client side components to be developed and tested on environment which has SharePoint Workbench.
You can also use toolchain for code compilation, packaging the client-side projects into SharePoint app package.
SharePoint Framework not only uses npm packages but also uses its dependencies and publish own packages to npm registry.
SharePoint Framework packages
SharePoint Framework contains several npm packages which work together for developers. List of those packages are provided below:
It is a Yeoman plug-in which is used to setup a client side project for SharePoint Framework. It automatically adds all defaults, best practices and required packages.
It defines core libraries of client side application required for SharePoint Framework.
This is local environment for testing and debugging client side application.
It is responsible for versioning and loading client side components, web-parts and other assets. It is built upon SystemJS and WebPack standards and is the first module of SharePoint Framework to load on page.
It defines various shared interfaces used by other modules of SharePoint Framework.
It provides custom bundle of lodash for use with SharePoint Framework’s module loader. It only includes a subset of most essential functions.
It defines custom tslint rules for usage with SharePoint client-side projects.
It provides a custom bundle of office-ui-fabric-react that is optimized for use with the SharePoint Framework’s module loader.
Common building tools packages
The SharePoint Generator installs required npm packages in the project. These packages can be installed in two ways either locally or globally. In case of web part projects, web part code depends on various SharePoint and common build packages therefore it requires these packages to be installed locally.
When we install any package, it is provisioned in node_modules folder in project structure. This folder contains the packages along with all of the dependencies. SharePoint Framework packages are located under node_module\@microsoft folder. @microsoft denotes that these npm packages are published by Microsoft.
Every time you create new project using generator, generator installs SharePoint framework packages and its dependencies. This way, npm makes developers life easy by managing web part projects without affecting other projects in local development environment.
The package.json file is kept in client side project. It contains a list of dependencies the projects depends on. Each dependency may also have dependencies. In this file, we can provide dependencies based on criteria like runtime dependencies and build dependencies for the package. You can see two properties as “dependencies” and “devDependencies”. The “devDependencies” property informs about dependencies to be required for build. Let us see an example below.
“@types/webpack-env”: “>=1.12.1 <1.14.0”
“@types/chai”: “>=3.4.34 <3.6.0”,
“@types/mocha”: “>=2.2.33 <2.6.0”
“build”: “gulp bundle”,
“clean”: “gulp clean”,
“test”: “gulp test”
However there is a lot of packages installed on development machine, but these are for implementation, building, compiling, bundling and packaging. Final minified version of web part which is deployed on CDN or SharePoint doesn’t include any of these packages.
Working with Source Control system
In the preferred case, we don’t want to check-in all dependencies available in node_modules folder into source control. It can be done if we exclude node_modules folder from list of files to ignore during check-ins.
If you are using “git” as your source control system, Yeoman scaffolded web part project contains a file with extension .gitignore. This file helps to ignore node_modules folder and items if you need.
Now, what will happen, if other team member downloads code from source control first time? How will that machine get dependencies required for project? The answer is very simple. You have run following command.
npm will scan the package.json file and install the required dependencies.
SharePoint Framework build tasks
SharePoint Framework uses gulp as its Task Runner to perform following processes:
- Run tools to call the bundling and minification tasks before each build.
- Compile LESS or SASS files to CSS.
The toolchain has following tasks which are defined in @microsoft/sp-build-core-tasks package.
- build – Builds the client-side solution project
- serve – Serves the client-side solution project and assets from the local machine.
- nuke – Cleans the client-side solution project’s build artifacts from the previous build and from the build target directories (lib and dist)
- test – Runs unit tests, if available, for the client-side solution project.
- package-solution – Packages the client-side solution into a SharePoint package.
- deploy-azure-store – Deploys client-side solution project assets to Azure Storage.
However, you can also create your own gulp task. To run these tasks, append the task name with gulp command for example.
e.g. gulp serve
You cannot run multiple tasks at a time in single command. The command “serve” runs different tasks targeted as BUILD mode and launches SharePoint Workbench. But if “ship” parameter is specified, command targets to SHIP mode.
Usually, when your web part project is ready to ship or deploy in a production server, you will target SHIP. For other scenarios like testing and debugging you would target BUILD. The SHIP target also ensures that the minified version of the web part bundle is built.
To target SHIP mode, you append the task with –ship:
In DEBUG mode, the build tasks copy all of the web part assets, including the web part bundle, into the “dist” folder.
In SHIP mode, the build tasks copy all of the web part assets, including the web part bundle, into the “temp\deploy” folder.
I have covered SharePoint Framework Toolchain and have also described that we can create custom gulp task by our self.
In the next article, we’ll go through building it.
Thank you for reading…
Please like, share and subscribe!