ripple-react-wrapper

Ripple React Wrapper

A lightweight wrapper component that enables seamless integration of React components within the Ripple framework.

Overview

The Ripple React Wrapper allows you to embed existing React components into Ripple applications, providing a bridge between the two frameworks. This is particularly useful when migrating from React to Ripple or when you want to reuse existing React components in a Ripple project.

Features

• 🔄 Seamless Integration: Embed React components directly in Ripple
• 🎯 Type Safety: Full TypeScript support with proper type definitions
• 🚀 Performance: Efficient mounting and unmounting of React components
• 📦 Lightweight: Minimal overhead with clean API
• 🔧 Flexible: Pass props and HTML attributes easily

Installation

npm install ripple-react-wrapper
# or
pnpm add ripple-react-wrapper
# or
yarn add ripple-react-wrapper

Requirements

• Node.js >= 20.0.0
• React >= 18.2.0
• Ripple >= 0.2.35

Usage

Basic Example

import { ReactWrapper } from 'ripple-react-wrapper';
import MyReactComponent from './MyReactComponent';

export component MyRippleComponent() {
  <ReactWrapper 
    component={MyReactComponent} 
    $props={{ title: "Hello from Ripple!" }}
    class="my-wrapper"
  />
}

React Component Setup

Important: React components used with this wrapper must include the following import at the top:

import * as React from 'react';

Example React component:

import * as React from 'react'; // Required!
import { useState } from 'react';

interface MyComponentProps {
  title?: string;
  initialCount?: number;
}

export default function MyComponent({ title = "Counter", initialCount = 0 }: MyComponentProps) {
  const [count, setCount] = useState(initialCount);

  return (
    <div>
      <h2>{title}</h2>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </div>
  );
}

Advanced Usage

import { ReactWrapper } from 'ripple-react-wrapper';
import ComplexComponent from './ComplexComponent';

export component AdvancedExample() {
  let componentProps = {
    data: [1, 2, 3, 4, 5],
    onItemClick: (item) => console.log('Clicked:', item),
    theme: 'dark'
  };

  <ReactWrapper 
    component={ComplexComponent}
    $props={componentProps}
    style="border: 1px solid #ccc; padding: 16px;"
    data-testid="react-wrapper"
  />
}

API Reference

ReactWrapper Props

Prop	Type	Required	Description
component	ComponentType<any>	✅	The React component to render
$props	Record<string, any>	❌	Props to pass to the React component
...otherProps	any	❌	Additional HTML attributes for the wrapper div

Types

interface ReactWrapperProps {
  component: ComponentType<any>;
  $props?: Record<string, any>;
  [key: string]: any;
}

type WrappableReactComponent<P = {}> = ComponentType<P>;
type ComponentProps<T> = T extends ComponentType<infer P> ? P : never;

How It Works

The wrapper creates a div element and uses React's createRoot API to mount your React component inside it. The component is properly unmounted when the Ripple component is destroyed, ensuring no memory leaks.

• Mount: When the wrapper mounts, it creates a React root and renders your component
• Props: Component props are passed through the $props attribute
• Cleanup: When unmounting, the React root is properly cleaned up

Known Issues

• React components must include import * as React from 'react'; at the top
• TypeScript may show warnings for .ripple files (this is expected and being worked on)

Development

# Format code
npm run format

# Check formatting
npm run format:check

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.