use-nodecg

This package is a collection custom hooks of React Hooks for NodeCG API.

🚨 This package is in alpha state. But feel free to try out and file an issue for suggestion/bugs!

Install

npm install use-nodecg
# or
yarn add use-nodecg
# or
pnpm add use-nodecg

About React Hooks

(This section comes from when React hooks was just introduced as an alpha feature, but is still useful to keep as an introduction.)

The React Hooks are a new way of sharing code between components, introduced in version 16.8.

Please read the documentation of React Hooks thoroughly before using them.

It also helps to learn the background mechanism of React Hooks. React hooks: not magic, just arrays

Recommendation

Use eslint-plugin-react-hooks in your project. It is 100% smarter than you to detect violation of the Rules of Hooks.

Usage

`useReplicant`

Subscribes to specified replicant and returns the value as state.
Allows you to use replicant values in function component.

import {useReplicant} from 'use-nodecg';

// This component will re-render when the `counter replicant value changes
export function RunnerName() {
	const [count, setCount] = useReplicant('counter');
	return (
		<div>
			<div>{count}</div>
			<button onClick={() => setCount(count + 1)} />
		</div>
	);
}

`useReplicantOnce`

Reads specified replicant value once, without subscribing to it.
Uses readReplicant internally.
Returns single value that will be updated once when it reads the value
Does NOT subscribe to replicant value changes

import {useReplicantOnce} from 'use-nodecg';

// Only reads the replicant value once and doesn't update
export function RunnerName() {
	const count = useReplicantOnce('counter');
	return <div>{count}</div>;
}

`useListenFor`

Subscribes messages with listenFor, and unlistens on unmount.
Combining with other hooks enables powerful stateful features with function component

import {useListenFor} from 'use-nodecg';

// Shows modal for 1 second when NodeCG receives 'errorHappened' message from the server
export function AlertOnMessage() {
	const [showAlert, setShowAlert] = useState(false);
	useListenFor('errorHappened', () => {
		setShowAlert(true);
	});
	useEffect(() => {
		if (!showAlert) {
			return;
		}
		// Disappear alert 1 second after
		const timer = setTimeout(() => {
			setShowAlert(false);
		}, 1000);
		// Make sure to return cleanup function
		return () => {
			clearTimeout(timer);
		};
	}, [showAlert]);

	return <Modal show={showAlert} />;
}

ericthelemur / use-nodecg