Enforced Component Contracts

Enforced Component Contracts

Master enforced component contracts with free flashcards and spaced repetition practice. This lesson covers fragment composition patterns, data requirement enforcement, and contract validation—essential concepts for building maintainable Relay applications that prevent data-fetching bugs at compile time.

Welcome to Component Data Contracts 💻

Welcome to one of Relay's most powerful features! In traditional data-fetching approaches, components often make assumptions about what data will be available, leading to runtime errors when those assumptions break. Relay solves this with enforced component contracts—a system that guarantees every component receives exactly the data it declares, verified at build time.

Think of it like TypeScript for your data requirements. Just as TypeScript catches type errors before runtime, Relay catches data requirement mismatches before your code ever runs. This lesson will show you how Relay enforces these contracts and why this enforcement is revolutionary for building reliable applications.

What Are Component Contracts? 🤝

A component contract is a formal declaration of what data a component needs to render correctly. In Relay, every component that needs data declares its requirements using a GraphQL fragment. This fragment becomes a binding contract that Relay enforces throughout your application.

Here's the key insight: You cannot render a component without satisfying its data contract. Relay makes this physically impossible through its compiler and type system.

┌─────────────────────────────────────────────┐
│         TRADITIONAL APPROACH                │
├─────────────────────────────────────────────┤
│  Component expects props.user.email         │
│           ↓                                 │
│  Parent passes incomplete data              │
│           ↓                                 │
│  💥 Runtime error: Cannot read 'email'      │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│         RELAY APPROACH                      │
├─────────────────────────────────────────────┤
│  Component declares fragment                │
│           ↓                                 │
│  Parent MUST include child fragment         │
│           ↓                                 │
│  Relay compiler verifies at build time      │
│           ↓                                 │
│  ✅ Runtime safety guaranteed               │
└─────────────────────────────────────────────┘

The Three Pillars of Enforcement 🏛️

Relay enforces component contracts through three mechanisms working together:

1. Fragment Composition (Compile-Time)

When a parent component renders a child, it must compose the child's fragment into its own query. The Relay compiler verifies this composition is complete.

2. Type System Integration (Development-Time)

Relay generates TypeScript types from your fragments. If you try to render a component without spreading its fragment, TypeScript will show an error before you even run the code.

3. Runtime Validation (Production Safety)

Even if something slips through (rare), Relay includes runtime checks that prevent components from receiving incomplete data.

💡 Pro Tip: These three layers create a "defense in depth" strategy. Most errors are caught at compile time, some at development time, and the rest at runtime—but well before users see broken UI.

Fragment Spreading: The Enforcement Mechanism 📐

The syntax that enforces contracts is fragment spreading. When you write ...UserProfile_user, you're doing more than including fields—you're establishing a formal contract:

fragment ParentComponent_data on Query {
  user {
    id
    ...UserProfile_user    # Contract enforcement point
    ...UserSettings_user   # Another contract
  }
}

What Relay enforces here:

• Completeness: All fragments must be spread
• Correctness: Fragments must be spread on compatible types
• Isolation: Children cannot access parent data without explicit passing

Enforcement Check	What It Prevents	When It Runs
Fragment matching	Spreading fragments on wrong types	Compile time
Missing spreads	Rendering child without its data	TypeScript/Compile
Data masking	Accessing undeclared fields	Runtime
Type compatibility	Type mismatches in fragment refs	TypeScript

How the Compiler Enforces Contracts 🔍

The Relay compiler (relay-compiler) is the primary enforcer. When you run it, here's what happens:

Step 1: Parse all fragments

The compiler scans your codebase and extracts every GraphQL fragment and query.

Step 2: Build a dependency graph

It maps which components depend on which data, creating a complete picture of your data requirements.

Step 3: Verify composition

For every component render, it checks that parent queries include all child fragments.

Step 4: Generate types

It creates TypeScript types that make violations impossible to write.

COMPILER VERIFICATION FLOW

📄 Source Code
     |
     ↓
🔍 Extract Fragments
     |
     ↓
📊 Build Dependency Graph
     |
     ↓
✅ Verify Composition Rules
     |
     ├──→ ❌ Missing Spread → Compilation Error
     ├──→ ❌ Type Mismatch → Compilation Error
     ├──→ ❌ Unused Fragment → Warning
     |
     ↓
📝 Generate TypeScript Types
     |
     ↓
💾 Output Compiled Artifacts

Type-Safe Fragment References 📦

Relay generates a special type for each fragment called a fragment reference (or "fragment ref"). This type is opaque—you cannot inspect its properties directly. You can only pass it to useFragment() to "unwrap" it.

This opacity is intentional enforcement:

// Generated by Relay compiler
type UserProfile_user$key = {
  readonly " $data"?: UserProfile_user$data;
  readonly " $fragmentSpreads": FragmentRefs<"UserProfile_user">;
};

// You cannot do this:
function UserProfile(props: { user: UserProfile_user$key }) {
  const name = props.user.name;  // ❌ TypeScript error!
  // The type is opaque—you can't access fields directly
}

// You must do this:
function UserProfile(props: { user: UserProfile_user$key }) {
  const data = useFragment(graphql`...`, props.user);  // ✅
  const name = data.name;  // Now it works!
}

Why opaque types? They enforce that you cannot access data you didn't declare. This is data masking at the type level.

Contract Violations and Error Messages 🚨

When you violate a contract, Relay gives clear, actionable errors. Let's see common violations:

Violation 1: Forgetting to Spread a Fragment

fragment ParentComponent_data on Query {
  user {
    id
    # Missing: ...UserProfile_user
  }
}

function ParentComponent({ data }) {
  return <UserProfile user={data.user} />;  // ❌
}

Error message:

Type 'User' is not assignable to type 'UserProfile_user$key'.
  Property ' $fragmentSpreads' is missing in type 'User'.

Fix: Add the fragment spread:

fragment ParentComponent_data on Query {
  user {
    id
    ...UserProfile_user  // ✅
  }
}

Violation 2: Spreading on Wrong Type

fragment UserProfile_user on User {
  name
  email
}

fragment ParentComponent_data on Query {
  organization {
    ...UserProfile_user  # ❌ Organization ≠ User
  }
}

Error message:

Fragment 'UserProfile_user' cannot be spread here as objects of type
'Organization' can never be of type 'User'.

Violation 3: Missing useFragment Call

// Trying to use fragment ref directly
function UserProfile({ user }: { user: UserProfile_user$key }) {
  return <div>{user.name}</div>;  // ❌ user is opaque!
}

Error message:

Property 'name' does not exist on type 'UserProfile_user$key'.

Fix: Use the hook:

function UserProfile({ user }: { user: UserProfile_user$key }) {
  const data = useFragment(
    graphql`fragment UserProfile_user on User {
      name
    }`,
    user
  );
  return <div>{data.name}</div>;  // ✅
}

Example 1: Simple Contract Enforcement 📝

Let's build a user profile display with proper contract enforcement:

Child Component (UserAvatar.tsx):

import { graphql, useFragment } from 'react-relay';
import type { UserAvatar_user$key } from './__generated__/UserAvatar_user.graphql';

interface Props {
  user: UserAvatar_user$key;  // Fragment reference type
}

export default function UserAvatar({ user }: Props) {
  const data = useFragment(
    graphql`
      fragment UserAvatar_user on User {
        name
        avatarUrl
      }
    `,
    user
  );

  return (
    <div className="avatar">
      <img src={data.avatarUrl} alt={data.name} />
      <span>{data.name}</span>
    </div>
  );
}

Parent Component (UserProfile.tsx):

import { graphql, useFragment } from 'react-relay';
import UserAvatar from './UserAvatar';
import type { UserProfile_query$key } from './__generated__/UserProfile_query.graphql';

interface Props {
  queryRef: UserProfile_query$key;
}

export default function UserProfile({ queryRef }: Props) {
  const data = useFragment(
    graphql`
      fragment UserProfile_query on Query {
        currentUser {
          id
          email
          ...UserAvatar_user  # ✅ Spreading child's contract
        }
      }
    `,
    queryRef
  );

  return (
    <div>
      <UserAvatar user={data.currentUser} />  {/* ✅ Contract satisfied */}
      <p>Email: {data.currentUser.email}</p>
    </div>
  );
}

What's enforced here:

1. UserProfile MUST spread ...UserAvatar_user to render UserAvatar
2. TypeScript prevents passing data.currentUser without the fragment spread
3. UserAvatar can ONLY access name and avatarUrl (data masking)
4. If UserAvatar adds a field to its fragment, UserProfile automatically includes it

Example 2: Multiple Child Contracts 🔗

Handling multiple children with different data requirements:

Children:

// UserBasicInfo.tsx
function UserBasicInfo({ user }: { user: UserBasicInfo_user$key }) {
  const data = useFragment(
    graphql`
      fragment UserBasicInfo_user on User {
        name
        email
        phoneNumber
      }
    `,
    user
  );
  // ... render basic info
}

// UserPreferences.tsx
function UserPreferences({ user }: { user: UserPreferences_user$key }) {
  const data = useFragment(
    graphql`
      fragment UserPreferences_user on User {
        theme
        language
        notifications {
          email
          push
        }
      }
    `,
    user
  );
  // ... render preferences
}

// UserActivity.tsx
function UserActivity({ user }: { user: UserActivity_user$key }) {
  const data = useFragment(
    graphql`
      fragment UserActivity_user on User {
        lastLogin
        loginCount
        recentActions {
          type
          timestamp
        }
      }
    `,
    user
  );
  // ... render activity
}

Parent:

function UserDashboard({ queryRef }: { queryRef: UserDashboard_query$key }) {
  const data = useFragment(
    graphql`
      fragment UserDashboard_query on Query {
        viewer {
          id
          # All child contracts must be satisfied
          ...UserBasicInfo_user
          ...UserPreferences_user
          ...UserActivity_user
        }
      }
    `,
    queryRef
  );

  return (
    <div className="dashboard">
      <UserBasicInfo user={data.viewer} />
      <UserPreferences user={data.viewer} />
      <UserActivity user={data.viewer} />
    </div>
  );
}

Enforcement guarantee: If you forget even ONE fragment spread, the code won't compile. Try removing ...UserActivity_user and TypeScript will immediately show an error when you try to pass data.viewer to UserActivity.

Example 3: Conditional Rendering with Contracts ⚖️

Contracts work even with conditional rendering:

function UserSettings({ queryRef }: { queryRef: UserSettings_query$key }) {
  const data = useFragment(
    graphql`
      fragment UserSettings_query on Query {
        viewer {
          id
          isPremium
          ...BasicSettings_user
          ...PremiumSettings_user  # Always spread, even if conditional
        }
      }
    `,
    queryRef
  );

  return (
    <div>
      <BasicSettings user={data.viewer} />
      
      {/* Conditional rendering is fine—data is always fetched */}
      {data.viewer.isPremium && (
        <PremiumSettings user={data.viewer} />
      )}
    </div>
  );
}

Key insight: You spread all fragments needed by potentially rendered components. Relay fetches the data upfront, making conditional rendering fast (no loading states).

💡 Pattern: Spread fragments based on what CAN render, not what WILL render. This eliminates loading states from conditional UI.

Example 4: List Rendering with Contracts 📋

Enforcing contracts for collections:

// ListItem component
function TodoItem({ todo }: { todo: TodoItem_todo$key }) {
  const data = useFragment(
    graphql`
      fragment TodoItem_todo on Todo {
        id
        title
        completed
        dueDate
      }
    `,
    todo
  );

  return (
    <li>
      <input type="checkbox" checked={data.completed} />
      <span>{data.title}</span>
      <span>{data.dueDate}</span>
    </li>
  );
}

// List component
function TodoList({ queryRef }: { queryRef: TodoList_query$key }) {
  const data = useFragment(
    graphql`
      fragment TodoList_query on Query {
        todos {
          id
          ...TodoItem_todo  # Spread for each item
        }
      }
    `,
    queryRef
  );

  return (
    <ul>
      {data.todos.map(todo => (
        <TodoItem key={todo.id} todo={todo} />
      ))}
    </ul>
  );
}

Enforcement: Each todo in the array has the fragment spread, so each TodoItem receives valid data. If you forget the spread, TypeScript prevents the entire list from compiling.

The Contract Verification Algorithm 🧮

Here's how Relay verifies contracts (simplified):

FOR each component that calls useFragment(fragment, ref):
  1. Find the parent query/fragment that provides 'ref'
  2. Check if parent spreads 'fragment' on the same object
  3. IF NOT found:
       → Compilation error: Missing fragment spread
  4. IF found on wrong type:
       → Compilation error: Type incompatibility
  5. IF found correctly:
       → Generate type-safe fragment reference
       → Mark contract as satisfied ✅

FOR each fragment spread ...Fragment_name:
  1. Verify Fragment_name exists
  2. Verify spread is on compatible type
  3. Track in dependency graph

FOR each query root:
  1. Build complete dependency tree
  2. Verify all leaf fragments are included
  3. Generate single optimized query

Benefits of Enforced Contracts 🎁

1. No Runtime Data Errors

You cannot access fields you didn't declare. data.user.email either works (because you declared it) or doesn't compile (because you didn't).

2. Refactoring Safety

Change a child's fragment? The compiler tells you every parent that needs updating.

3. Automatic Optimization

Relay deduplicates fields across fragments automatically. Multiple children asking for user.name results in one field in the query.

4. Clear Ownership

Every field in your query is owned by exactly one component. No confusion about who needs what.

5. Documentation as Code

Fragments serve as machine-verified documentation of component dependencies.

Benefit	Traditional Approach	Relay Contracts
Error detection	Runtime (production)	Compile time
Refactoring confidence	Low (manual checks)	High (automated)
Performance optimization	Manual deduplication	Automatic
Documentation accuracy	Often outdated	Always accurate
Onboarding time	High (implicit patterns)	Lower (explicit contracts)

Contract Enforcement vs Data Masking 🎭

These concepts work together:

• Contract Enforcement: Ensures you fetch all required data
• Data Masking: Ensures you only access declared data

Think of them as two sides of the same coin:

         CONTRACT ENFORCEMENT
                  ↓
    ┌─────────────────────────┐
    │  Parent must spread     │
    │  child's fragment       │
    └───────────┬─────────────┘
                ↓
    ┌─────────────────────────┐
    │  Data is fetched        │
    └───────────┬─────────────┘
                ↓
    ┌─────────────────────────┐
    │  Fragment ref passed    │
    │  to child               │
    └───────────┬─────────────┘
                ↓
         DATA MASKING
                ↓
    ┌─────────────────────────┐
    │  Child can only access  │
    │  fields it declared     │
    └─────────────────────────┘

Together they guarantee: Every component gets exactly what it needs, nothing more, nothing less.

Common Mistakes ⚠️

Mistake 1: Trying to Access Raw Data

// ❌ WRONG
function UserProfile({ user }) {
  // Trying to access fields directly from fragment ref
  return <div>{user.name}</div>;  // Error: Property 'name' doesn't exist
}

// ✅ CORRECT
function UserProfile({ user }) {
  const data = useFragment(graphql`...`, user);
  return <div>{data.name}</div>;
}

Why it fails: Fragment references are opaque types. You must unwrap them with useFragment().

Mistake 2: Forgetting to Spread in Conditionals

// ❌ WRONG
fragment Parent_data on Query {
  user {
    isPremium
    # Missing: ...PremiumFeatures_user
  }
}

function Parent({ data }) {
  return data.user.isPremium ? (
    <PremiumFeatures user={data.user} />  // Error!
  ) : null;
}

// ✅ CORRECT
fragment Parent_data on Query {
  user {
    isPremium
    ...PremiumFeatures_user  # Always spread
  }
}

Why it fails: Fragments must be spread even for conditional rendering. The data is fetched upfront.

Mistake 3: Spreading on Wrong Type

// ❌ WRONG
fragment UserDetails_user on User {
  name
}

fragment Parent_data on Query {
  organization {
    ...UserDetails_user  // Error: Organization is not User!
  }
}

// ✅ CORRECT: Create appropriate fragment
fragment OrganizationDetails_org on Organization {
  name
}

Why it fails: Fragments are type-specific. You cannot spread a User fragment on an Organization.

Mistake 4: Circular Fragment Dependencies

// ❌ WRONG
fragment UserProfile_user on User {
  friends {
    ...FriendList_users
  }
}

fragment FriendList_users on User {
  id
  ...UserProfile_user  // Circular!
}

Why it fails: Circular dependencies create infinite queries. Use pagination or separate fragments for different contexts.

Mistake 5: Not Running Relay Compiler

// You write this...
fragment MyComponent_data on User {
  newField  // Just added
}

// But forget to run: relay-compiler
// Result: TypeScript types are outdated, errors appear

Why it fails: Relay generates types at build time. Changes to fragments require rerunning the compiler.

💡 Solution: Set up relay-compiler --watch in development to auto-regenerate types.

Mistake 6: Assuming Parent Can Access Child Fields

// ❌ WRONG ASSUMPTION
fragment Parent_data on Query {
  user {
    ...ChildComponent_user  # Child declares 'email'
  }
}

function Parent({ data }) {
  const childData = useFragment(childFragment, data.user);
  // Parent thinking: "Child fetched email, so I can use it!"
  console.log(data.user.email);  // ❌ undefined! Data masking prevents this
}

// ✅ CORRECT: Declare fields you need
fragment Parent_data on Query {
  user {
    email  # Parent declares its own needs
    ...ChildComponent_user
  }
}

Why it fails: Data masking ensures you can only access fields you explicitly declare, even if children declare them.

Debugging Contract Violations 🔧

When you encounter contract errors, follow this process:

Step 1: Read the Error Message

Relay's errors are specific. They tell you:

• Which fragment is missing
• Where it should be spread
• What type mismatch exists

Step 2: Trace the Component Tree

QueryComponent
  └─> ParentComponent  ← Forgot to spread fragment?
       └─> ChildComponent  ← Error appears here

Step 3: Check the Fragment Spread

Look at the parent's fragment:

fragment ParentComponent_data on Query {
  user {
    # Is ...ChildComponent_user here?
  }
}

Step 4: Verify Type Compatibility

Check that you're spreading on the correct type:

fragment ChildComponent_user on User { ... }  # Expects User

fragment Parent_data on Query {
  user {  # ✅ This is User type
    ...ChildComponent_user
  }
}

Step 5: Regenerate Types

Run relay-compiler to ensure types are current:

npm run relay  # or yarn relay

Advanced Pattern: Fragment Composition Chains 🔗

Fragments can compose other fragments, creating chains:

// Level 3: Leaf component
fragment Avatar_user on User {
  avatarUrl
}

// Level 2: Intermediate component
fragment UserCard_user on User {
  name
  ...Avatar_user  // Composes leaf
}

// Level 1: Parent component
fragment UserList_query on Query {
  users {
    id
    ...UserCard_user  // Composes intermediate
  }
}

// Level 0: Root query
query AppQuery {
  ...UserList_query  // Composes parent
}

What Relay enforces:

• Each level must spread the level below
• The final query includes all leaf fragments
• Changes to leaf propagate through the chain
• Types are verified at each level

Result: One optimized query that includes all fields from all fragments:

query AppQuery {
  users {
    id
    name
    avatarUrl
  }
}

Testing Components with Contracts 🧪

Relay's enforcement extends to testing. Use MockPayloadGenerator to create test data that satisfies contracts:

import { createMockEnvironment, MockPayloadGenerator } from 'relay-test-utils';

test('UserProfile renders correctly', () => {
  const environment = createMockEnvironment();
  
  const { getByText } = render(
    <RelayEnvironmentProvider environment={environment}>
      <UserProfile queryRef={...} />
    </RelayEnvironmentProvider>
  );
  
  // Relay ensures mock data matches fragment contract
  environment.mock.resolveMostRecentOperation(operation =>
    MockPayloadGenerator.generate(operation, {
      User: () => ({
        name: 'Test User',
        email: 'test@example.com',
      }),
    })
  );
  
  expect(getByText('Test User')).toBeInTheDocument();
});

The contract ensures: Mock data structure matches what the component expects. If the fragment changes, tests update automatically.

Key Takeaways 🎯

1. Contract = Fragment Declaration: Every component declares its data needs as a GraphQL fragment, creating a binding contract.

2. Enforcement = Fragment Spreading: Parents must spread child fragments to render children. This is verified at compile time.

3. Three-Layer Defense: Compile-time (Relay compiler), development-time (TypeScript), and runtime (data masking) all enforce contracts.

4. Opaque Fragment Refs: Generated types prevent accessing data without useFragment(), enforcing proper contract usage.

5. Type Safety Throughout: Relay generates TypeScript types that make contract violations impossible to write.

6. Benefits Everywhere: No runtime errors, safe refactoring, automatic optimization, clear ownership, self-documenting code.

7. Always Spread for Conditionals: Even conditionally rendered components need their fragments spread upfront.

8. Data Masking + Contracts: Together they guarantee components receive exactly—and only—what they declare.

📚 Further Study

• Relay Fragment Container Documentation - Official guide to useFragment and fragment composition patterns
• Relay Compiler Architecture - Deep dive into how Relay enforces contracts at build time
• Type-Safe GraphQL with Relay - Understanding Relay's TypeScript integration and generated types