Getting Started

Solid Relay provides SolidJS bindings for Relay, enabling you to use GraphQL with Solid's fine-grained reactivity. This guide will walk you through setting up Solid Relay in different project configurations.

Prerequisites

Before getting started, make sure you have:

• A GraphQL schema and server
• Watchman installed (required for Relay compiler in watch mode)
• Node.js and your preferred package manager (npm, pnpm, or yarn)

Installation

Install the required packages:

npm i solid-relay relay-runtime

pnpm add solid-relay relay-runtime

yarn add solid-relay relay-runtime

bun add solid-relay relay-runtime

Install development dependencies:

npm i relay-compiler @types/relay-runtime vite-plugin-relay-lite vite-plugin-cjs-interop -D

pnpm add relay-compiler @types/relay-runtime vite-plugin-relay-lite vite-plugin-cjs-interop -D

yarn add relay-compiler @types/relay-runtime vite-plugin-relay-lite vite-plugin-cjs-interop -D

bun add relay-compiler @types/relay-runtime vite-plugin-relay-lite vite-plugin-cjs-interop -d

Project Setup

SolidStart

For SolidStart applications, configure your app.config.ts:

import { defineConfig } from "@solidjs/start/config";
import relay from "vite-plugin-relay-lite";
import { cjsInterop } from "vite-plugin-cjs-interop";

export default defineConfig({
  vite: () => ({
    plugins: [
      relay(),
      // required since Relay only gets published in CJS
      cjsInterop({ dependencies: ["relay-runtime"] }),
    ],
  }),
});

Vite

For Vite-based applications, configure your vite.config.ts:

import { defineConfig } from 'vite';
import solid from 'vite-plugin-solid';
import relay from 'vite-plugin-relay-lite';
import { cjsInterop } from 'vite-plugin-cjs-interop';

export default defineConfig({
  plugins: [
    solid(),
    relay(),
    // required since Relay only gets published in CJS
    cjsInterop({ dependencies: ["relay-runtime"] }),
  ],
});

Relay Configuration

Create a relay.config.json file in your project root:

{
  "src": "./src",
  "schema": "./schema.graphql",
  "exclude": ["**/node_modules/**", "**/__generated__/**"],
  "language": "typescript",
  "eagerEsModules": true
}

Setting Up Relay Environment

Create a Relay environment to configure your GraphQL client:

import { Environment, type FetchFunction, Network, RecordSource, Store } from 'relay-runtime';

// Define your fetch function
const fetchFn: FetchFunction = async (params, variables) => {
  const response = await fetch('/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: params.text,
      variables,
    }),
  });

  return await response.json();
}

export function createRelayEnvironment() {
  // Create Relay environment
  return new Environment({
    network: Network.create(fetchFn),
    store: new Store(new RecordSource()),
  });
}

Provider Setup

Wrap your app with the Relay Environment Provider:

import { RelayEnvironmentProvider } from 'solid-relay';
import { createRelayEnvironment } from './RelayEnvironment';

function App() {
  const environment = createRelayEnvironment();

  return (
    <RelayEnvironmentProvider environment={environment}>
      {/* Your app components */}
    </RelayEnvironmentProvider>
  );
}

export default App;

Next Steps

Now that you have Solid Relay set up, you can start using its features:

• Querying Data - Learn how to fetch data with GraphQL queries
• Fragments - Understand fragment composition and masking
• Mutations - Handle data modifications
• Pagination - Implement efficient list pagination
• Subscriptions - Work with real-time data

Important Notes

Relay Documentation Compatibility

Solid Relay only replaces the React-specific parts of Relay (equivalent to react-relay). This means you can use most of the official Relay documentation for:

• Relay Compiler: Schema definitions, GraphQL syntax, and compilation
• Relay Runtime: Store management, network layer, and core concepts
• GraphQL: All GraphQL features and best practices

The main difference is in the component-level APIs, which Solid Relay provides as SolidJS primitives instead of React hooks.

Plugin Choice

This guide uses vite-plugin-relay-lite instead of vite-plugin-relay. The lite version is recommended as it provides:

• Better bundler performance
• Smaller install size
• Better integration with modern build tools
• Automatic codegen with Relay Compiler

If you need additional features not available in the lite version, you can switch to vite-plugin-relay, but vite-plugin-relay-lite covers most use cases effectively.