mm-react-tools

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

Table of Contents

• [Upgrading to 3.x] (#upgrading-to-3.x)
• Install
• Getting Started
• Client ID and Secret
• 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

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:

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.

Sign-in uses the OAuth authorization-code flow with PKCE (S256). There is no clientSecret prop: a browser app is a public client and must not ship a secret. If you are upgrading from v4, delete clientSecret from your config and rotate that secret — it has been in every build that included it.

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}
    releaseStage={process.env.REACT_APP_RELEASE_STAGE}
    scope={'reporting'}
  >
    <App />
  </MMProvider>,
  document.getElementById('root'),
);

releaseStage is one of production, govcloud, staging or development and selects the login, app, API, GraphQL, NATS and custom data service hosts, available to your app as useMMAuth().urls. Pass urls to override any of them. The development stage has no customDataUrl.

Protect a Route

Use the ProtectedRoute to kick off the login flow.

// 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.

// 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;

Widget Settings

useMMAppSetting(name, config, stateTriggers) declares a dashboard widget setting; the host draws the form and delivers the value as useMMAppContext()[name]. config.type is one of input, select, radio, thresholds, custom or dateRange, and the MMAppSettingConfig type lists the options each one takes. validate returns true or an error message.

A dateRange setting offers presets from DATE_RANGE_PRESETS (DEFAULT_DATE_RANGE_PRESETS when options is omitted). The host resolves the chosen preset with the company's time zone and shop-day start, keeps it current as shop days roll over, and delivers a DateRangeValue. It is undefined until the host sends it. The setting needs a host that supports it: a dashboard on the Dashboard and ui releases that add the type, and mmdev-cli 1.1.0 or later for the playground. Release an app that declares one only once those are available to its users.

useMMAppSetting('range', {
  type: 'dateRange',
  label: 'Date range',
  options: ['today', 'yesterday', 'last7Days'],
  default: 'today',
  acceptGlobalOverride: 'dateRange',
});

const { range } = useMMAppContext();
// { preset: 'today', start: '2026-03-10T11:00:00.000Z', end: '2026-03-11T11:00:00.000Z',
//   startDay: '2026-03-10', endDay: '2026-03-10' }

start and end are ISO instants on shop-day boundaries, with end exclusive. startDay and endDay are inclusive yyyy-MM-dd shop days. With acceptGlobalOverride: 'dateRange' the widget follows the dashboard's date filter. Avoid naming the setting dateRange, which collides with a native widget prop. default must be one of options; otherwise the host uses the first offered preset. With acceptGlobalOverride, a dashboard filter set to a custom range, or to a preset the setting doesn't offer, replaces the widget with "Not available for …". The names src, id, type, title, filter and dateRangeSettings are reserved and can't be used as setting names, and the host ignores date range settings named __proto__, constructor or prototype. A widget can have at most 20 date range settings. See the developer hub's Date Range page for the full behavior.

Client ID and Secret

Contact [email protected] for a Client ID and Secret.

License

MIT © MachineMetrics