Registry / web-framework / react-aptor

react-aptor

JSON →
library2.0.0jsnpmunverified

React Aptor is a minimal API connector for React applications, currently at version 2.0.0. It provides a structured and opinionated way to integrate vanilla JavaScript third-party libraries, especially those that interact directly with the DOM, into React components. The library addresses common integration challenges such as finding DOM nodes, preventing excessive re-renders, and managing API lifecycles without relying on global scope or introducing unnecessary abstraction layers. Emphasizing a "zero-dependency," "tree-shakeable," and "side-effect free" design, React Aptor boasts a minimal bundle size (less than 1 kilobyte). While a strict release cadence is not specified, recent updates, including the significant v2.0.0 release, indicate active development focused on improving the build process, testing infrastructure, and project consistency. Its core differentiator is empowering developers with full control over their API definitions and their connection to React, aiming to be anti-pattern-free within the React ecosystem.

npm install react-aptor
INSTALL
IMPORT
SIG · REACT-APTOR
R
react-aptor
web-frameworkjavascriptv2.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

useAptor
import { useAptor } from 'react-aptor'
const { useAptor } = require('react-aptor')
Primary hook for connecting third-party APIs. React Aptor is an ESM-first package.
AptorInstance
import type { AptorInstance } from 'react-aptor'
TypeScript type for the instance returned by your `instantiate` function.
AptorAPI
import type { AptorAPI } from 'react-aptor'
TypeScript type for the API object returned by your `getAPI` function.

Demonstrates connecting a custom 'CounterLib' third-party library to a React component using `useAptor` by defining `instantiateCounter` and `getCounterAPI` functions, then consuming the exposed API.

import React, { useRef, useEffect, useState } from 'react'; import { useAptor } from 'react-aptor'; // 1. Define the instantiate function for a dummy third-party library // Let's imagine a simple counter library that updates a DOM element. class CounterLib { private count: number = 0; private displayElement: HTMLElement; constructor(node: HTMLElement, initialCount: number = 0) { this.displayElement = node; this.count = initialCount; this.render(); } increment = () => { this.count++; this.render(); }; decrement = () => { this.count--; this.render(); }; getCount = () => this.count; destroy = () => { this.displayElement.innerHTML = ''; // Clean up DOM console.log('CounterLib destroyed'); }; private render = () => { this.displayElement.innerHTML = `Current count: ${this.count}`; }; } const instantiateCounter = (node: HTMLElement, initialCount: number) => { return new CounterLib(node, initialCount); }; // 2. Define the get API function const getCounterAPI = (instance: CounterLib) => ({ increment: instance.increment, decrement: instance.decrement, getCount: instance.getCount, }); // 3. Connect API to react by useAptor function CounterComponent() { const containerRef = useRef<HTMLDivElement>(null); const { api: counterApi, instance: counterInstance, isReady } = useAptor( instantiateCounter, getCounterAPI, containerRef, // The node for the third-party lib [0] // params for instantiateCounter: initialCount ); useEffect(() => { if (isReady && counterApi) { console.log('Counter API is ready, current count:', counterApi.getCount()); } }, [isReady, counterApi]); return ( <div style={{ padding: '20px', border: '1px solid #ccc' }}> <h2>React Aptor Counter Example</h2> <div ref={containerRef} style={{ marginBottom: '10px' }}> {/* CounterLib will render here */} </div> {isReady && counterApi ? ( <div> <button onClick={counterApi.increment} style={{ marginRight: '10px' }}>Increment</button> <button onClick={counterApi.decrement}>Decrement</button> <p>Count from React state: {counterApi.getCount()}</p> </div> ) : ( <p>Loading Counter...</p> )} </div> ); } // Example usage in an App component const App = () => <CounterComponent />; export default App;
Debug
Known issues
breakingThe `destroy` function, if provided in your `instantiate` function's return, became optional in `v1.2.1`. While not strictly a breaking change for existing valid implementations, types might have changed, and relying on its mandatory presence might require adjustment.
fix
Ensure your `instantiate` function's return type correctly reflects the `destroy` function as optional if it's not always present.
affects: >=1.2.1
breakingReact `Ref` types were updated to align with `forwardedRef` in `v1.2.0`. This internal change could subtly affect how refs are processed or typed if you are passing complex ref objects to `useAptor` or relying on specific ref behaviors.
fix
Review components that pass refs to `useAptor`-managed elements. Ensure ref handling aligns with modern React `forwardedRef` patterns, especially if you encountered TypeScript errors related to refs.
affects: >=1.2.0
gotchaDirectly using `ReactDOM.findDOMNode` within your React components is an anti-pattern that `react-aptor` aims to circumvent. While `react-aptor` helps integrate third-party libraries that *do* manipulate the DOM, you should avoid `findDOMNode` in your own React code.
fix
Pass a `useRef` hook's current value (e.g., `containerRef.current`) as the node argument to your `instantiate` function via `useAptor`, rather than using `ReactDOM.findDOMNode` to locate the DOM element.
affects: >=1.0.0
gotchaThe `v2.0.0` release is described as the 'most significant' to date, primarily focusing on build process improvements, testing, and tooling (e.g., SWC, esbuild, Rollup configurations). While API breaking changes are not explicitly detailed in the provided release notes, it's advisable to thoroughly review the full changelog on GitHub if migrating from `v1.x` to check for any subtle behavioral changes or undocumented API adjustments.
fix
Consult the official `react-aptor` GitHub repository's changelog for a comprehensive list of changes when upgrading to v2.0.0 or later to identify potential API-level breaking changes.
affects: >=2.0.0
Errors
Common errors & fixes
Error: Invalid hook call. Hooks can only be called inside of the body of a function component.
The `useAptor` hook is being called outside of a React function component or a custom React hook.
fix
Ensure `useAptor` is only called at the top level of a React function component or another custom React hook (e.g., not inside loops, conditions, or nested functions).
TypeError: aptorAPI.someMethod is not a function
The `getAPI` function provided to `useAptor` is not correctly returning an object that includes `someMethod`, or `someMethod` does not exist on the underlying third-party instance.
fix
Verify that your `getAPI` function correctly accesses and exposes all desired methods from the `instance` argument. Debug the `instance` object within `getAPI` to confirm the availability of methods.
TypeError: Cannot read properties of null (reading 'current') when trying to pass ref to instantiate function
The `useRef` hook used for the DOM element has not yet been attached to an actual DOM element when `useAptor` attempts to access its `.current` property, or the component has unmounted.
fix
Ensure the `useRef` is properly initialized with `null` and then attached to a real DOM element (e.g., `<div ref={containerRef}></div>`). The `useAptor` hook internally handles the lifecycle, so just ensure the ref is placed correctly.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies
reactrequiredRequired peer dependency for React hooks functionality.
Agent activity
4 hits · last 30 days
node
4
Resources