export default React.forwardRef(Connector);
`

> name this file connector.jsx as convention ✨
> If you are using react 17 or newer version, you can also name it connector.js

useAptor in one look

`jsx
const aptorRef = useAptor(ref, configuration, deps);
`

ref
For the connection phase, you need to define a forwardRef component. The useAptor hook needs forwarded-ref as the first argument, this is necessary to bind all your defined API to this ref.

configuration
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) which you can bind to your DOM node.

> The params doesn't have any limitation, it can be any arbitrary type e.g. undefined, number, string, or an object containing all of them. The params will be then passed to your instantiate and getAPI function, as you saw in the first and second steps.
> Params is the best place to connect props to your low-level API it means ”No Need” for extra function generation 🥳

deps
Is the same as Dependencies array default value is [] but you can override it as the third and last argument of useAptor. It may be needed in a situation in which you want to force re-instantiate by some prop change. It will use shallow comparison (as react do) for dependency array and will call your instantiate & getAPI in a row.

$3

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

const apiKeyHandler = () => {
if (ref.current) {
ref.current.api_key();
}
};

return (


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

$3

> In case you need ref.current more than one time, it is a good idea to rename it in the first place

`jsx
const apiKeyHandler = () => {
const { current: api } = ref; // store ref.current in api
if (api) {
api.api_key();
}
};
`

$3

Cause the default value for ref can be undefined (in createRef) and null (in useRef) Typescript will complain about possibility for not-existence of apis. see more.
In a normal world react will bind your API to the given ref after the Connector mount

If you're using ref in useEffect or somewhere which is guaranteed to have the ref bounded to values, you can return a proxy object in your getAPI function to bind all api functions simultaneously.

`js
export default function getAPI(thirdParty, params) {
if (!thirdParty)
return () =>
new Proxy(
{},
{
get: (_, prop) => {
// Possible to mock differently for different props
return noop;
},
}
);

return () => ({
api_key() {
// third-party is defined here for sure :)
console.log(thirdParty);
},
});
}
`

$3

> You can access all of your APIs via this keyword

`js
export default function getAPI(sound, params) {
return () => ({
_state() {
return sound.getState();
},

play() {
if (this._state() === 'LOADED') sound.play();
},
});
}
`

> It's better to start the name of these internal functions with _

$3

In a case, you see this keyword usage in third-party API
you must specify this something other than returned API object.
The following examples are for howler integration using react-aptor:

`js
{
// ❌ It doesn't work
state: howler.state,

// 🆗 this is Okay
state: howler.state.bind(howler),
// 🆗 this is also Okay
state: () => howler.state(),
// 🆗 this is also Okay, too
state() {
return howler.state();
}
}
`

$3

You can use something like the follwing:

`ts
export type APITypes = ReturnType>;
`

$3

1. Name your package raptor-something :)
2. Use minimum possible configuration for your API
3. Interact to props change in your component using useEffect and proper deps array
4. Bind another ref to your Connector using the fork-ref idea

For another possible usage see our production ready examples:

- plyr-react
- raptor-howler-example

core

$3

The react useRef or createRef ref instance which has been passed throw react.forwardRef method.
your API will be stored in this ref.

$3

- ### instantiate _required_

> function(node, params): Instance

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

- ### destroy

> function(previousInstance, params): void

A function that receives previously created instances and params. It is useful when you want to perform the cleanup before new instance creation. e.g. remove event listeners, free up allocated memories, destroy internally & etc

- ### getAPI _required_

> function(Instance, params): ApiObject

A function that receives instances of your third-party and params. It then returns a key-value pair object for API handlers.

- ### params any

Params can have any arbitrary type and can be used with props or pre-defined options.

$3

React dependencies array for re-instantiating your third-party packages. It will call instantiate with the latest node, params whenever shallow comparison for with the previous deps array finds inequality.

---

Donation

💻 Developer/Maintainer (BTC):
1KMz71heaNaE6myAssRH54rUKXPdbwZp5j

🎨 Designer (BTC):
bc1q9fahyct3lrdz47pjf4kfxvsyum2dm74v2hv9xl`

Color Palettes

!#c7589e
!#ed5b6e
!#f9b919
!#26abe2
!#129f4d

Samples

NOTE: Add your favorite package to the following list by creating a new issue.

⭐ SEE ALL SAMPLES 🌟