npm package: @machinemetrics/mm-react-tools
Description: Components, hooks, and helper functions for writing React apps using MachineMetrics APIs.
Author: machinemetrics
Latest version: 4.12.0

# mm-react-tools

Components, hooks, and helper functions for writing React apps using MachineMetrics APIs.

[![NPM](https://img.shields.io/npm/v/mm-react-tools.svg)](https://www.npmjs.com/package/mm-react-tools) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

## Table of Contents

- [Upgrading to 3.x] (#upgrading-to-3.x)
- [Install](#install)
- [Getting Started](#getting-started)
- [Client ID and Secret](#client-id-and-secret)
- [License](#license)

## Upgrading to 3.x

When upgrading to 3.x or newer, there are a few breaking changes that need to be addressed.

- The `domain` property passed to `MMProvider` is no longer used so it can be removed. This information is inferred from the URL being loaded.
- If you pass `<Route>` components to `MMProvider` either directly or in some level more deeply nested within your application, it must be contained within a `<Routes>` component.

## Install

```bash
npm install @machinemetrics/mm-react-tools
```

## Peer Dependencies

Due to how Apollo, React, and other libraries work, there are some additional dependencies that you'll need to include in your project:

```bash
npm install react react-router-dom styled-components @apollo/client
```

## Getting Started

Wrap your application in the `MMProvider` to wire up everything necessary to authenticate against MachineMetrics Cloud with OAuth.

```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import { MMProvider } from '@machinemetrics/mm-react-tools';
import App from './App';

ReactDOM.render(
  <MMProvider
    clientId={process.env.REACT_APP_CLIENT_ID}
    clientSecret={process.env.REACT_APP_CLIENT_SECRET}
    releaseStage={process.env.REACT_APP_RELEASE_STAGE}
    scope={'reporting'}
  >
    <App />
  </MMProvider>,
  document.getElementById('root')
);
```

### Protect a Route

Use the `ProtectedRoute` to kick off the login flow.

```jsx
// App.js
import React from 'react';
import { Route, Routes } from 'react-router-dom';
import { PrivateLayout } from '@machinemetrics/mm-react-tools';
import PublicPage from './PublicPage';
import PrivatePage from './PrivatePage';

function App() {
  return (
    <Routes>
      <Route exact path='/public' element={<PublicPage />} />
      <Route element={<PrivateLayout />}>
        <Route path="/private" element={<PrivatePage />}>
      </Route>
    <Routes>
  );
}

export default App;
```

### GraphQL Hooks

Apollo hooks for GraphQL are available via `useQuery` and `useSubscription`.

```jsx
// PrivatePage.js
import React, { useEffect, useState } from 'react';
import { gql, useQuery } from '@apollo/client';

const PrivatePage = () => {
  const [company, setCompany] = useState();

  const query = gql`
    query {
      companies {
        name
      }
    }
  `;

  const { data, loading, error } = useQuery(query);

  useEffect(() => {
    if (!data || !data.companies || !data.companies.length) {
      return;
    }

    setCompany(data.companies[0].name);
  }, [data]);

  return <div>{company}</div>;
};

export default PrivatePage;
```

## Client ID and Secret

Contact support@machinemetrics.com for a Client ID and Secret.

## License

MIT © [MachineMetrics](https://github.com/machinemetrics)