Microsoft Graph Toolkit

Web Components powered by Microsoft Graph

The Microsoft Graph Toolkit is a collection of web components powered by Microsoft Graph. The components are functional, working automatically with Microsoft Graph, and work with any web framework and on all modern browsers.

Components & Documentation • Getting Started • Running the Samples • Contribute • Feedback & Requests
• License • Code of Conduct

Components & Documentation

You can explore components and samples with the playground powered by storybook.

The Toolkit currently includes the following components:

The components work best when used with a provider. The provider handles authentication and the requests to the Microsoft Graph APIs used by the components. The Toolkit contains the following providers:

You can also create your own providers by extending the IProvider abstract class.

View the full documentation

Getting Started

The following guides are available to help you get started with the Toolkit:

You can use the components by referencing the loader directly (via unpkg), or installing the npm package

Use via mgt-loader:

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>

You can then start using the components in your html page. Here is a full working example with the Msal provider:

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal-provider client-id="[CLIENT-ID]"></mgt-msal-provider>
<mgt-login></mgt-login>

<!-- <script>
    // alternatively, you can set the provider in code and provide more options
    mgt.Providers.globalProvider = new mgt.MsalProvider({clientId: '[CLIENT-ID]'});
</script> -->

NOTE: MSAL requires the page to be hosted in a web server for the authentication redirects. If you are just getting started and want to play around, the quickest way is to use something like live server in vscode.

Use via NPM:

The benefits of using MGT through NPM is that you have full control of the bundling process and you can bundle only the code you need for your site. First, add the npm package:

npm install @microsoft/mgt

Now you can reference all components at the page you are using:

<script src="node_modules/@microsoft/mgt/dist/es6/components.js"></script>

Or, just reference the component you need and avoid loading everything else:

<script src="node_modules/@microsoft/mgt/dist/es6/components/mgt-login/mgt-login.js"></script>

Similarly, to add a provider, you can add it as a component:

<script src="node_modules/@microsoft/mgt/dist/es6/components/providers/mgt-msal-provider.js"></script>

<mgt-msal-provider client-id="[CLIENT-ID]"></mgt-msal-provider>

or, add it in your code:

<script type="module">
  import { Providers, MsalProvider } from '@microsoft/mgt';

  Providers.globalProvider = new MsalProvider({ clientId: '[CLIENT-ID]' });
</script>

or, if you already use MSAL.js and have a UserAgentApplication, you can use it:

<script type="module">
  import { Providers, MsalProvider } from '@microsoft/mgt';

  const app = new UserAgentApplication({ auth: { clientId: '[CLIENT-ID]' } });

  Providers.globalProvider = new MsalProvider({ userAgentApplication: app });
</script>

Running the samples

Some of our samples are coupled to use the locally built mgt packages instead of the published version from npm. Becuase of this, it's helpful to build the monorepo before attempting to run any of the samples.

# Starting at the root
yarn
yarn build
# Now you can run the React sample using the local packages
cd ./samples/react-app/
yarn start

This also means that running the samples in isolation may fail if there are breaking changes between the published version of mgt and the local copy. To workaround this, use samples that are known to be compatible with a specific release by checking out the appropriate branch or tag first.

Contribute

We enthusiastically welcome contributions and feedback. Please read the contributing guide before you begin.

Code Contribution Challenge

There are many exciting new features or interesting bugs that have been left behind because our team is small with limited capacity. We would love your help! We have tagged these issues with 'help wanted' and/or 'good first issue'. We added them into project board Community Love for easy tracking. If you see anything you would like to contribute to, you can reach out to [email protected] or tag one of us (Beth, Elise, Nick, Nikola, and Shane) in the issue for help or further discussion. By submitting a PR to solve an issue mentioned above, you can enter to win some exciting prizes! We have some cool socks and t-shirts waiting for you. Check out the official rules for Code Contribution Challenge. The contest will continue until March 2021 where prizes are awarded every month from now on.

Feedback and Requests

For general questions and support, please use Stack Overflow where questions should be tagged with microsoft-graph-toolkit

Please use GitHub Issues for bug reports and feature requests. We highly recommend you browse existing issues before opening new issues.

License

All files in this GitHub repository are subject to the MIT license. This project also references fonts and icons from a CDN, which are subject to a separate asset license.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

isabella232 / microsoft-graph-toolkit Goto Github PK