use-nodecg

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

🚨 This package is in alpha state, as well as the React Hooks API itself. Do not use in production. But feel free to try out and file an issue for suggestion/bugs!

Install

npm install use-nodecg@next
# or
yarn add use-nodecg@next

About React Hooks

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.

• Video introduction
• The Motivation
• Rules
• Hooks API reference
• FAQ

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 = useReplicant('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} />;
}

License

MIT © Keiichiro Amemiya (Hoishin)