DOCSEARCHbyAlgolia
Submit Docs

RescriptRelay Documentation

website·Indexed 29 days ago

https://rescript-relay-documentation.vercel.app/docs/getting-started

Documentation for RescriptRelay, a ReScript implementation of the Relay GraphQL client. It includes guides on queries, fragments, mutations, and the Relay compiler, as well as a tutorial adapted from the official Relay tutorial. The library provides tools like rescript-relay-cli and a dedicated VSCode extension to improve developer experience and codebase health.

Tokens
42K
Snippets
188
Records
264
Agent score
74%

What's inside RescriptRelay

  1. Overview of the @codesplit directive

    The @codesplit directive in RescriptRelay automatically codesplits fragment components. Unlike React.lazy, which starts downloading code only when the component renders, @codesplit triggers the download as soon as the server response indicates the component is needed. This prevents waterfalls and is fully client-side, requiring no special server-side configuration (unlike Relay's '3D' data-driven dependencies).

  2. Overview of RescriptRelay

    RescriptRelay is a GraphQL client that integrates the capabilities of Relay with the ReScript programming language. It is designed for building maintainable and scalable frontend applications, leveraging ReScript's sound type system to provide specialized tooling for codebase health and scalability.

  3. Overview of Refetchable Fragments in Relay

    Refetchable fragments allow developers to fetch new data for a specific fragment using different variables, independently of the larger query the fragment is spread into. This prevents the need to refetch an entire page query when only a small subset of data (like a filtered list) needs to change. The Relay compiler achieves this by generating a separate, synthetic query specifically for the refetch operation.

  4. Understand RescriptRelay design philosophy and scope

    RescriptRelay is an opinionated binding to Relay designed to integrate with ReScript's type system. Instead of providing a 1-to-1 mapping of the entire Relay API, it focuses on:

    1. Relay Hooks: The library binds Relay's hooks rather than higher-order components (HOCs).
    2. Developer Utilities: It provides tools to simplify common Relay patterns, such as updating the store and managing connections.

    Because of this focus, some parts of the original Relay API surface are not covered, though these typically represent alternative ways of achieving the same functionality already provided by the hooks and utilities.

  5. Understand Relay Fragment fundamentals

    Fragments are the primary way Relay manages data dependencies. Every component that displays data and cares about its semantics should use a GraphQL fragment to declare its data needs. This approach ensures scalability: data dependencies can be updated in a single place regardless of how many times a component is reused across an application.

    Key concepts include:

    • Reading Data: Fragment data is accessed using the use hook specific to that fragment.
    • Fragment Keys: The use hook requires a fragment key, which identifies the specific location in the GraphQL response where the fragment was spread.
    • Fragment Arguments: Fragments can define arguments that are provided at the point where the fragment is spread, allowing the component's data to be tailored to different contexts.

  6. Automate Relay compilation and GraphQL tooling in VSCode

    The RescriptRelay VSCode extension provides several integrated developer experience features:

    • Automated Compilation: Runs the Relay compiler in the background and reports errors directly within the editor.
    • GraphQL Editor Support: Provides Prettier formatting, syntax highlighting, and autocomplete based on the GraphQL schema.
    • Codegen & Refactoring: Allows developers to generate operations (queries, mutations, subscriptions) and fragments via VSCode commands, extract selections into fragment components, and perform GraphQL refactors such as setting up pagination or adding @argumentDefinitions.

  9. Understand the Relay Compiler's role in GraphQL query management

    The Relay Compiler solves the tradeoff between performance (single request per page) and maintainability (component decoupling). Instead of writing large, screen-wide queries, developers define data requirements locally within components using GraphQL Fragments. The compiler scans the ReSCript code, stitches these fragments together into a single optimized top-level query, and automatically deduplicates overlapping data requests to ensure the same field is only requested once.

  10. Use Relay as a Local State Manager

    RescriptRelay 3.0 supports using Relay as a general local state manager via Relay resolvers and client schema extensions. This allows developers to combine local and server data in a type-safe manner with granular re-renders, potentially replacing other state management libraries like Redux or Jotai.

  11. Modify data using GraphQL Mutations and Subscriptions

    Beyond querying data, GraphQL provides two other top-level operations:

    • Mutations: Used to update or modify data on the server (analogous to HTTP POST). The server can return the updated data in the response.
    • Subscriptions: Maintain an open connection to provide real-time updates to the client.

  12. Understand GraphQL core concepts

    GraphQL is a query language for APIs that allows clients to request specific data combinations from a server in a single request, rather than relying on fixed endpoints. It organizes data as a graph consisting of nodes (objects/records) and edges (pointers between nodes).

    Key components include:

    • Scalars: Primitive types like strings, integers, or dates.
    • Objects: Nodes that can contain scalar fields or edges to other nodes.
    • Schema: A definition of all available nodes, their connections, and their fields.
    • Non-nullable fields: Indicated by a ! in the schema (e.g., ID!), meaning the server must return a value or it is considered an error.