Add a new npm package

Before creating a new package as part of the Microsoft Graph Toolkit, make sure you've interacted with the maintainers of the project and have agreed on the package purpose, architecture, name, etc.

To create a new package, you will need to add a new folder in the packages folder with the name of the package, make sure the package.json references the dependencies properly, and ensure a readme has been added. Take a look at how existing packages are structured and try to follow the same structure for your package.

Let's create a new package step by step.

Create the folder

Create a new folder under the packages folder. If the package is a new provider, add it under the packages/providers folder. Name the folder according to your package. For example, if the package will be called @microsoft/mgt-unicorn, name the folder unicorn.

Create the folder structure

Follow the example of the other packages and structure your folder in a similar way.

Tip: you might find it easier to copy the files/folders from an existing package and make the appropriate changes

package.json

Ensure the package.json follows the same format as other packages - below is an example of package.json you can use. Feel free to add other dependencies and scripts (but ensure you keep the base scripts included here).

{
  "name": "@microsoft/mgt-unicorn",
  "version": "2.0.0", // doesn't matter the version, but must follow semantic versioning
  "description": "Clear description",
  "keywords": [
    "microsoft graph",
    "microsoft graph toolkit",
    "my tag"
  ],
  "homepage": "https://github.com/microsoftgraph/microsoft-graph-toolkit",
  "bugs": {
    "url": "https://github.com/microsoftgraph/microsoft-graph-toolkit/issues"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/microsoftgraph/microsoft-graph-toolkit"
  },
  "author": "Microsoft",
  "license": "MIT",
  "main": "./dist/es6/index.js",
  "types": "./dist/es6/index.d.ts",
  "module": "./dist/es6/index.js",
  "files": [
    "dist",
    "src"
  ],
  "scripts": {
    "build": "npm-run-all clean build:compile",
    "build:compile": "npm-run-all sass compile",
    "build:watch": "npm-run-all -p sass:watch compile:watch",
    "clean": "shx rm -rf ./dist && shx rm -rf ./tsconfig.tsbuildinfo",
    "compile": "tsc -b",
    "compile:watch": "tsc -w",
    "lint": "tslint -c ../../tslint.json 'src/**/*.ts'",
    "postpack": "cpx *.tgz ../../artifacts",
    "setLicense": "gulp setLicense --cwd ."
  },
  "dependencies": {
    "@microsoft/mgt-element": "*" // any dependency to other mgt packages should use "*"
  },
  "publishConfig": {
    "directory": "dist"
  }
}

tsconfig.json

Ensure your tsconfig extends our base tsconfig in the root of the repository. In general, you can just use the below as is.

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "dist/es6",
    "sourceRoot": "src",
    "rootDir": "src",
    "composite": true
  },
  "include": ["src"]
}

README.md

The readme will be used as the readme on the npm package - make sure it's descriptive and clear - provide a way for the developer to get started with the package

src folder

Add all of your source in the src folder. Ensure you have an index.ts file in the root of the src folder as the entry point of the package.

Ensure the package can build

Once the new package is added, run the following scripts in the root of the repository:

1. yarn
2. yarn build

Ensure no build errors show up. Navigate to your package folder and ensure the dist folder and js files have been generated.

Add the package to the root README

As part of the PR adding the package, ensure the package has also been added to the list of packages in the root README