react-aptor

React Aptor

React API Connector

---

آموزش فارسی

Most packages are developed separately in javascript or typescript for increasing generality to make them us in all libraries and frameworks.

Connecting third parties to react is not a routine task. on the other hand, different teams might develop these packages hence development progress can be one step behind the original or terminated at any time. Also, wrong abstraction or bad design patterns may slow down progress or block it at every new release.

List of some other concerns:

• Finding dom nodes by ReactDOM-findDOMNode
• Extensively usage of memoization to improve performance or prevent extra re-renders
• Large size of the project because of duplication and all API definition in react.
• Rely on a global scope (e.g. window) for package internal setting and making it impossible to have more than one instance.

react-aptor

We strive to solve them all at once

Features

---

• Small
  • Zero-dependency with less than 1 kilobyte size 😱 react-aptor
• Manageable
  • Your used/defined APIs are entirely under your control. Make it possible to define a slice of APIs which you are surely going to use.
• React-ish
  • Developed with lots of care, try to be zero-anti-pattern in react.
• Simple
• Typescript

How to use

Connect your react app to any third party in three-step

1. Define the instantiate function
2. Define the get API function
3. get connected to react by useAptor

---

1. First step

   Define the instantiate function.

// construct.js
import Something from 'your-third-party'
export default function instantiate(node, params) {
  return new Something(node, {...params, ...yourCustomConfig} )
}

This function will return an instance of the third-party package. You have access to node (DOM-node) and params.

The node is passed by react-aptor as a reference to DOM that is occasionally used as a wrapper for embedding UI. Params are optional parameters that are passed by react-aptor and define by you. see the third step.

1. Second step

Define the get API function.

// api.js
export default function getAPI(instance, params) {
  return () => ({
    api_key: () => {
      /* api defenition */
    },
  });
}

react-aptor will pass instance and params to your getAPI function. The instance is your third-party instance which has been defined in the first step.

Params are optional parameters that are passed by react-aptor and define by you. see the third step.

1. Third step

// connector.jsx
import useAptor from "react-aptor";
import getAPI from "./api";
import instantiate from "./construct";

const Connector = (props, ref) => {
  const aptorRef = useAptor(ref, {
    getAPI,
    instantiate,
    /* params: anything */
  });

  return <div ref={aptorRef} />;
};

export default React.forwardRef(Connector);

For the connection phase, you need to define a forwardRef component, grab forwarded-ref and pass that as the first argument ofuseAptor hook. As the configuration argument you need to pass defined instantiate (defined in the first step), getAPI (defined in the second step), and your custom params argument. The useAptor hook will return you a ref (aptorRef) with must be bound to your returned DOM node.

The params will be then passed to your instantiate and getAPI function, as you saw in the first and second steps. The value of params doesn't have any limitation, and it can be any arbitrary type (e.g. undefined, number, string, object). You have full access to props in your component and you can define params value by props too.

Action Step

const Main = () => {
  const ref = createRef();

  const apiKeyHandler = () => ref.current?.api_key();

  return (
    <div>
      <Connector ref={ref} />
      <Button onClick={apiKeyHandler}>api call</Button>
    </div>
  );
};

Pass createRef to the Connector component (made in the third step), and then you can access all of the APIs inside ref.current

Full Typescript support

The project was developed by typescript, see samples for more info.

core

Options

ref ForwardedRef ref required

The react useRef or createRef ref instance to store you api

configuration Object required

• instantiate function(node, params): Instance required

  A function that receives ref for probable bounded-node and params and returns an instance of your third-party.

• getAPI function(Instance, params): ApiObject required

  A function which receives instantiated instance and params and returns a key-value pair object for api handlers.

• params any

  Anything. It can be use props or pre-defined options.

deps Array[any] []

react dependencies array for re-instantiating your third-party-packages by calling instantiate with latest node, params.

Donation

🎨 Designer (BTC): bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl

💻 Developer/Maintainer (BTC): bc1qq8qq63ex7svkkjdjn5axu8angfxytvs83nlujk

Samples

Quill.js + typescript

Quill is a free, open source WYSIWYG editor built for the modern web.

Fabric.js

Fabric.js is a powerful and simple. Javascript HTML5 canvas library.

Rive.js

Create and ship beautiful animations to any platform.

Howler.js

Audio library for the modern web.

Reveal.js

HTML presentation framework create fully featured and beautiful presentations.

⭐ SEE ALL SAMPLES 🌟