MDK by Tether

Step-by-step walkthrough — set up the MDK React UI Kit and render your first component, with explanations, alternatives, and troubleshooting

This tutorial walks you through adding the MDK UI Kit to your own React app, with the reasoning behind each step. If you only want to evaluate MDK first, start with the Quickstart.

Prerequisites

Node.js 20+
pnpm 10+

This project uses pnpm as the package manager. Pick the path that fits your goal:

Recommended for ongoing use. Enable corepack (built into Node.js) once, then pnpm is on your PATH:

# Enable corepack (comes with Node.js)
corepack enable

# Verify pnpm is available
pnpm --version

MDK splits into two sub-trees: core/ (npm-based) and ui-client/ (pnpm-based). All UI Kit work happens inside ui-client/, which is the pnpm workspace root. The repo root (mdk/) has no package.json by design. Your app will live in ui-client/apps/ alongside the packages.

1.1 Clone the repository

git clone https://github.com/tetherto/mdk.git
cd mdk/ui-client

1.2 Install and build

pnpm install
pnpm build

This builds @tetherto/mdk-core-ui, @tetherto/mdk-foundation-ui, and @tetherto/mdk-fonts-ui.

Create your app

2.1 Scaffold a Vite React app

Create a new React app in the apps/ folder:

cd apps
pnpm create vite my-app --template react-ts --no-immediate
cd my-app

2.2 Add MDK to `package.json`

Open package.json and replace the dependencies block with these four entries:

    "@tetherto/mdk-core-ui": "workspace:*",
    "@tetherto/mdk-foundation-ui": "workspace:*",
    "react": "catalog:",
    "react-dom": "catalog:"

2.3 Install from the workspace root

cd ../..    # from apps/my-app back up to ui-client
pnpm install

Import styles

Import the MDK stylesheets in your app's entry point (typically src/main.tsx). Both @tetherto/mdk-core-ui and @tetherto/mdk-foundation-ui ship their own stylesheet, and you'll use components from both:

import '@tetherto/mdk-core-ui/styles.css'
import '@tetherto/mdk-foundation-ui/styles.css'

Render your first component

Replace App.tsx with a single mining metric tile that toggles between a normal and an alarmed state, then start the dev server.

4.1 Replace `App.tsx` with the demo

This pulls a button from @tetherto/mdk-core-ui and a domain component (SingleStatCard) from @tetherto/mdk-foundation-ui:

import { useState } from 'react'
import { Button } from '@tetherto/mdk-core-ui'
import { SingleStatCard } from '@tetherto/mdk-foundation-ui'

function App() {
  const [overheating, setOverheating] = useState(false)

  return (
    <div style={{ padding: '2rem', display: 'grid', gap: '1rem', maxWidth: 320 }}>
      <h1>Miner status</h1>
      <SingleStatCard
        name="Inlet temperature"
        value={overheating ? 78 : 28}
        unit="°C"
        variant={overheating ? 'tertiary' : 'primary'}
        color="red"
        flash={overheating}
      />
      <Button onClick={() => setOverheating((on) => !on)}>
        {overheating ? 'Cool down' : 'Simulate overheat'}
      </Button>
    </div>
  )
}

export default App

4.2 Run your app

From the workspace root:

pnpm --filter my-app dev

You should see a card showing Inlet temperature 28 °C with a "Simulate overheat" button below it. Click the button — the card flips into an alarm state: red border, red text, value jumps to 78 °C, and the whole card pulses. Click "Cool down" to reset.

That's @tetherto/mdk-core-ui (the Button) and @tetherto/mdk-foundation-ui (the SingleStatCard) working together: generic primitives plus mining-domain components, in one app.

Troubleshooting

React 19 vs. runtime React 18

If @types/react and @types/react-dom in your devDependencies are 19.x, pin them to ^18.3.1 to match the runtime — otherwise TypeScript will offer React-19 APIs (use(), etc.) that throw at runtime.

Pin versions

Before 1.0, the React UI Kit packages (@tetherto/mdk-core-ui and @tetherto/mdk-foundation-ui) will be renamed to React-specific names to make room for Vue, Svelte, and Web Components. Imports will need updating when the new packages ship — pin your current version if you want to avoid an unexpected upgrade.

Next steps

Now that you have MDK working, explore the packages:

@tetherto/mdk-core-ui: base UI components such as buttons, inputs, tables, dialogs, and charts
@tetherto/mdk-foundation-ui: mining-domain components such as the operations centre, vendor containers, and settings

Run the demo app

The monorepo includes a comprehensive demo showcasing all components:

pnpm dev:demo

Open http://localhost:5173 to browse examples.

Use domain components

For mining-specific features, use @tetherto/mdk-foundation-ui:

import { FeatureFlagsSettings } from '@tetherto/mdk-foundation-ui'

function SettingsPage() {
  return (
    <FeatureFlagsSettings
      isEditingEnabled={true}
      featureFlags={{ darkMode: true, betaFeatures: false }}
      onSave={(flags) => console.log('Saved:', flags)}
    />
  )
}

See the Settings components documentation for more examples.

Tutorial