Skip to content

consuming-react-components.md

Latest commit

 

History

History
253 lines (170 loc) · 6.72 KB

consuming-react-components.md

File metadata and controls

253 lines (170 loc) · 6.72 KB

Consuming Our Future Health React Components

This guide explains how to consume the @ourfuturehealth/react-components package in your React applications.

Prerequisites

  1. Node.js 20.19.0 or higher (Node.js 24 LTS recommended)
  2. pnpm (recommended) or npm as package manager
  3. A React application (React 19+ required)

Installation

Note: As of v4.0.0, this repository is a monorepo. The React components package is located in packages/react-components/.

Currently, the React components are not published to npm registry. Install directly from GitHub:

Using pnpm (recommended)

pnpm add @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components

Using npm

npm install @ourfuturehealth/react-components@github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components

Version Pinning

  • Production: Use specific version tags (e.g., #react-v0.4.0)
  • Development: You can use #main:packages/react-components but ensure your lockfile pins a specific commit

package.json example:

{
  "dependencies": {
    "@ourfuturehealth/react-components": "github:ourfuturehealth/design-system-toolkit#react-v0.4.0:packages/react-components",
    "react": "^19.2.4",
    "react-dom": "^19.2.4"
  }
}

Usage Example

Import components and styles in your React application:

import React from 'react';
import { Button, TextInput } from '@ourfuturehealth/react-components';
import '@ourfuturehealth/react-components/styles/participant';

function App() {
  return (
    <div>
      <TextInput
        label="Your name"
        hint="Enter your full name"
        onChange={(e) => console.log(e.target.value)}
      />
      <Button onClick={() => console.log('Clicked')}>Submit</Button>
    </div>
  );
}

export default App;

Import Styles

Import the stylesheet once in your app's entry point:

// main.tsx or App.tsx
import '@ourfuturehealth/react-components/styles/participant';

The styles are based on the Our Future Health design system toolkit and include all component styles.

Theme Selection

Each application should use one theme. Current theme bundles are:

  • participant
  • research

Squad C (React) using participant

Use the participant styles export:

import '@ourfuturehealth/react-components/styles/participant';

Squad C (React) using research

Use the matching themed styles export:

import '@ourfuturehealth/react-components/styles/research';

For backward compatibility, @ourfuturehealth/react-components/styles remains available and maps to participant.

To add a new custom React theme stylesheet export, follow docs/theming/adding-a-new-theme.md.

Available Components

The React components package currently provides the following components:

  • Button - Call-to-action buttons and links
  • TextInput - Text input fields with hint and error support
  • ErrorSummary - Page-level validation summaries with linked errors
  • Card - Content presentation cards for summaries, status, and next steps
  • CardCallout - Feedback-style callout cards for informational, warning, success, and error messages
  • CardDoDont - Positive and negative recommendation lists

For complete component documentation and live examples, run Storybook:

pnpm storybook

Or see the example consumer app for usage demonstrations.

TypeScript Support

The package includes full TypeScript definitions. No additional @types/ packages needed.

import type { ButtonProps } from '@ourfuturehealth/react-components';

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Build Configuration

Vite

The React components work out of the box with Vite. No additional configuration needed.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});

Webpack

If using Webpack, ensure you have appropriate loaders for CSS:

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
};

Troubleshooting

Package not found during installation

Error: fatal: Could not read from remote repository

Solution: Ensure you have access to the GitHub repository. If it's a private repository, you may need to configure Git with your credentials or SSH key.

Module not found

Error: Cannot find module '@ourfuturehealth/react-components'

Solution:

  • Verify the package is installed: ls node_modules/@ourfuturehealth/react-components
  • Run pnpm install or npm install again
  • Check your package.json has the correct syntax with :packages/react-components suffix

Styles not loading

Error: Components appear unstyled

Solution: Ensure you import the styles:

import '@ourfuturehealth/react-components/styles/participant';

Import this in your app's entry point (e.g., main.tsx or App.tsx).

React version mismatch

Error: Warning: Invalid hook call or peer dependency warnings

Solution: The React components require React 19+. Update your React version:

pnpm add react@^19.2.4 react-dom@^19.2.4

TypeScript errors

Error: Type definitions not found

Solution:

  • Ensure "moduleResolution": "bundler" or "moduleResolution": "node" is set in your tsconfig.json
  • Run pnpm install to ensure type definitions are properly linked

Development and Contributing

For development and contributing to the React components:

  1. Clone the repository
  2. Install dependencies: pnpm install
  3. Run Storybook: pnpm storybook
  4. Make changes in packages/react-components/
  5. Run tests: pnpm test:react-components
  6. Lint code: pnpm lint:react-components
  7. Build all packages: pnpm build

See the main README.md for detailed setup instructions and the contributing guide for guidelines.

Example Consumer App

The monorepo includes an example consumer app demonstrating usage:

# Run the example app
pnpm dev:react-consumer

The example app is located in packages/example-react-consumer-app/ and shows how to consume the React components in a real application.

Need Help?

  1. Check the Storybook for component examples
  2. Review the example consumer app
  3. Read the upgrade guide for migration instructions
  4. Open an issue on GitHub