Registry / api / relay-runtime

relay-runtime

library21.0.1jsnpmunverified

Relay Runtime is the core runtime library for building GraphQL-driven applications with the Relay framework, developed by Facebook. Current stable version is 21.0.1, released bi-weekly alongside the Relay compiler. It provides client-side GraphQL execution, data fetching, caching with normalized stores, and reactivity. Key differentiators: strong type safety via generated TypeScript types, declarative data fetching with fragments, and optimized batching. Supports React and other JS frameworks. Ships TypeScript definitions natively.

api

npm install relay-runtime

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RELAY-RUNTIME

relay-runtime

apijavascriptv21.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RelayRuntime

✓ import { RelayRuntime } from 'relay-runtime'

✗ import RelayRuntime from 'relay-runtime'

RelayRuntime is a named export, not default. Use object destructuring.

Environment

✓ import { Environment } from 'relay-runtime'

✗ const { Environment } = require('relay-runtime')

Since v11, relay-runtime is ESM-only. Use import syntax; require() fails.

fetchQuery

✓ import { fetchQuery } from 'relay-runtime'

✗ import fetchQuery from 'relay-runtime'

fetchQuery is a named export. Default import yields undefined.

Shows how to create a Relay environment with a network layer and store.

import { Environment, Network, RecordSource, Store } from 'relay-runtime'; const fetchRelay = async (params, variables) => { const response = await fetch('https://api.example.com/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query: params.text, variables, }), }); return response.json(); }; const environment = new Environment({ network: Network.create(fetchRelay), store: new Store(new RecordSource()), }); export default environment;

Debug

Known issues

breakingRelay Environment is no longer a singleton; multiple environments are supported with different caches.

fix

Review data fetching patterns if migrating from <8.0 to avoid stale data.

affects: >=8.0.0

breakingRelayRuntime no longer exports 'Relay' default; use named exports like Environment.

fix

Change `import Relay from 'relay-runtime'` to `import { Environment, ... } from 'relay-runtime'`.

affects: >=11.0.0

deprecatedcommitMutation and requestSubscription are deprecated in favor of useMutation and useSubscription hooks.

fix

Use hooks from 'react-relay' or 'relay-hooks' instead.

affects: >=14.0.0

gotchaImporting from 'relay-runtime/lib/...' is unsupported; internal paths may change without notice.

fix

Import only from the package root: `import { ... } from 'relay-runtime'`.

affects: *

gotchaTypeScript: some types are only available when using relay-compiler-generated files; manual usage may lack types.

fix

Ensure relay-compiler is run before consuming types.

affects: *

Errors

Common errors & fixes

Cannot find module 'relay-runtime' or its corresponding type declarations.

Missing dependency or TypeScript cannot resolve types.

fix

Run `npm install relay-runtime` and ensure tsconfig.json includes `node_modules/@types` or the package ships types (v11+).

TypeError: relay_default is not a function

Incorrect default import of RelayEnvironment.

fix

Use named import: `import { Environment } from 'relay-runtime'`.

Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type.

Webpack/bundler not configured for ESM modules.

fix

Add `type: 'module'` in package.json or configure webpack to handle .mjs files.

Relay: Expected query to be a prepared query, got undefined.

Query is not properly prepared with relay-compiler.

fix

Run `relay-compiler` to generate the query artifacts, then import the generated file.

Upgrade

Version history

21.0.1latest on npm

Audit

Dependencies

graphqlrequiredGraphQL language and type system dependency

relay-compileroptionalGenerates runtime artifacts (e.g., QueryResource, useFragment) often required alongside runtime

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/facebook/relay ↗

packagerelay-runtime ↗

homepagehttps://relay.dev ↗