@runly/ui

This package provides a number of React Hooks that can be used to retrieve data from the Runly Platform API.

This package is intended to provide a base for you to build your own custom UIs. If you want something more streamlined, checkout our other packages.

Setup

Install the package into your project:

npm install @runly/ui

RunlyProvider

The RunlyProvider allows you to access the Runly API in any nested component or hook. Render a RunlyProvider at the root of your React app so that the Runly API is available everywhere you need it. You will need to pass your API key that all child components will use.

import React from "react";
import { RunlyProvider } from "@runly/ui";

const WrapMyApp = ({ children }) => (
	<RunlyProvider accessToken={myPublicApiKey}>{children}</RunlyProvider>
);

export default WrapMyApp;

Props

accessToken: string | Promise<string> | () => string | () => Promise<string>

A public API key or a Promise resolving to an API key or a function that returns the API key or the Promise.

url?: string

Optional Runly API URL that all child components will connect to. This defaults to https://api.runly.io.

useRunlyConfig

useRunlyConfig(): Object

This will return the url and the token configured via the RunlyProvider. This is the base URL and access token that you should use to connect to the Runly API.

import { useEffect, useState } from "react";
import { useRunlyConfig } from "@runly/ui";

const MyOrgComponent = ({ org }) => {
	const { url, token } = useRunlyConfig();
	const [results, setResults] = useState({});

	useEffect(() => {
		if (token) {
			fetch(`${url}/${org}/`, {
				method: "GET",
				headers: {
					Authorization: `Bearer ${token}`
				}
			})
			.then(response => response.json())
			.then(data => setResults(data));
		}
	}, [url, token, org]);

	return <pre>{JSON.stringify(results, null, 2)}</pre>;
};

export default MyOrgComponent;

useFetchOrgAccounts

useFetchOrgAccounts(): FetchResults

This is a thin wrapper around react-fetch-hooks to retrieve organization accounts for the current user.

import React from "react";
import { useFetchOrgAccounts } from "@runly/ui";

const OrgShower = () => {
	const { isFetched, body: orgs } = useFetchOrgAccounts();

	if (!isFetched) {
		return (
			<span>Loading orgs...</span>
		);
	}

	return (
		<ul>
			{orgs.map(({ id, name }) => (
				<li key={id}>{name}</li>
			))}
		</ul>
	);
};

export default OrgShower;

useRequeueRun

useRequeueRun(org: string, runId: string): FetchResults

This is a thin wrapper around a lazy react-fetch-hook to requeue a failed run.

Parameters

org: string

The organization that the run to be requeued belongs to. If the org is null or empty, the hook won’t do anything.

runId: string

The ID of the run to requeue. If the runId is null or empty, the hook won’t do anything.

import React, { useCallback } from "react";
import { useRequeueRun } from "@runly/ui";

const RetryRun = ({ org, runId }) => {
	const {
		fetch: requeue,
		body: newRun,
		isFetching: isQueueing,
		isFetched: isDone,
		error
	} = useRequeueRun(org, runId);

	const handleClick = useCallback(() => requeue(), [requeue]);

	if (isDone) {
		return <span>All done! {newRun.id}</span>;
	}

	if (error) {
		return <span>{error.message}</span>;
	}

	return (
		<button
			type="button"
			onClick={handleClick}
			disabled={isQueueing}
		>
			{isQueueing ? "Doing it..." : "Do it"}
		</button>
	);
};

export default RetryRun;

useRunConnection

useRunConnection(org: string, runId: string): Object

This hook opens a WebSocket connection to the Runly API and will listen for any updates for a particular run. If the browser does not support WebSockets, it will fallback to other techniques to receive the run’s real-time updates. The hook returns the status of the connection and the run as it is updated.

Parameters

org: string

The organization that the run to be monitored belongs to.

runId: string

The ID of the run to monitor.

import React from "react";
import { useRunConnection } from "@runly/ui";

const RunStatus = ({ org, runId }) => {
	const { run } = useRunConnection(org, runId);

	if (!run) {
		return <span>Connecting...</span>;
	}

	return <pre>{JSON.stringify(run, null, 2)}</pre>;
};

export default RunStatus;