Minimal Path to Awesome
This page will help you get up to speed as quickly as possible. You will learn how to get a copy of the repository, install the few dependencies required by the project, compile, run tests and check code coverage for the project.
- Install Dependencies
- Clone the Repository
- Install all NPM Packages
- Transpile the TypeScript for Building
- List All Gulp Tasks
- Execute All Unit Tests
- View Code Coverage Reports
- Build the Library
- See a Working Directive
This project has a few minimal dependencies that must be installed on your developer workstation in order to build and contribute to the project.
Node.js & NPM
Node.js is used for building & testing the project. Install either the latest stable version of Node.js or the long-term support (LTS) version on your machine from https://nodejs.org.
NOTE: The project has been tested with the 4.2.x LTS version & 5.x stable version.
NOTE: You can also use Node Version Manager (NVM) to install Node.js if you wish. NVM enables you to have multiple versions of Node.js installed on your machine and switch between them for testing on different versions. This is entirely optional:
Installation of Node.js includes NPM, the package manager for Node.js.
Global NPM Packages
Many parts of the project are implemented using TypeScript, but more importantly the build process is written in TypeScript. As such, you need to install one NPM package globally:
- typescript: main TypeScript compiler
$ npm install -g typescript
Clone the Repository
You need the code, so clone it locally:
$ git clone https://github.com/ngOfficeUIFabric/ng-officeuifabric.git ng-officeuifabric
Install all NPM Packages
Once you have the codebase, you need to install the NPM packages the repository depends on. Run the following command to download & install all the packages to the local cloned repo:
$ npm install
Transpile the TypeScript
You can see this if you try to get a list of all the gulp tasks after cloning the repository... immediately after running gulp, you will get a strange error about not being able to find modules or files:
$ gulp module.js:339 throw err; ^ Error: Cannot find module './build/gulp/config' at Function.Module._resolveFilename (module.js:337:15) at Function.Module._load (module.js:287:25) at Module.require (module.js:366:17) at require (module.js:385:17) at Object.<anonymous> (/Users/ac/Dev/Scratch/ng-officeuifabric/gulpfile.js:3:16) at Module._compile (module.js:425:26) at Object.Module._extensions..js (module.js:432:10) at Module.load (module.js:356:32) at Function.Module._load (module.js:311:12) at Module.require (module.js:366:17)
- you update the build process such as changing or adding Gulp tasks
tsc, telling it to treat the folder (
./) as a project (
-p) by looking at the
tsconfig.json file in the root fo the folder:
# run this ... $ npm run build:ts # or run this ... $ tsc -p ./
NOTE: If you get an error running this command, look at the version of
tscyou are running. If it isn't at least v1.7, you aren't running the most current version. This commonly happens on Windows as the
PATHenvironment variable is likely set to use an order version of the TypeScript compiler. You can check this by inspecting the
PATHvariable by executing
echo %PATH%on the command line. Notice it points to a version other than v1.7. To fix this, change the
pathenvironment variable to point to the correct version.
This article explains the issue in more depth: Which Version of TypeScript is Installed...
Now you can run gulp:
List All Gulp Tasks
Execute All Unit Tests
To execute all unit tests using Karma with the headless browser PhantomJS on the project, execute the following command:
View Code Coverage Reports
Karma always generates a code coverage report showing the percentages & lines of code that were covered by unit tests. To view the report, locate the following file and open it in the browser:
ng-officeuifabric/coverage/PhantomJS 1.9.8 (Mac OS X 0.0.0)/lcov-report/index.html
Build the Library
Build the library in dev mode so you can try one of the examples:
$ gulp build-lib --dev
See a Working Directive
To see a working directive, open the following file in a browser to see the
<uif-icon /> directive in action:
$ open src/components/icon/demo/index.html
TADA!!! Minimal Path to Awesome!