GraphQL Directives

# CHAPTER 14

GraphQL Directives #

1. Introduction #

2. Learning Objectives #

• Define what a GraphQL Directive is.

• Use the @include directive to conditionally fetch fields.

• Use the @skip directive to conditionally ignore fields.

• Understand how directives interact with GraphQL Variables.

3. Beginner-Friendly Explanation #

In GraphQL, a Directive is that checkbox. It provides instructions to the server *during execution*. Instead of creating two different forms (one for convertibles, one for hardtops), you use one form and attach a Directive.

You tell GraphQL: "Fetch the user's name, and fetch their profile picture, but @skip the profile picture if my $isMobile variable is true." The server reads the directive and adjusts the response on the fly.

4. Real-World Examples #

• Responsive Design: On a desktop UI, you have space to show a user's full biography and recent posts. On a mobile UI, you only have space for their name. You can use @include(if: $isDesktop) to only fetch the heavy data when the app is on a large screen, saving bandwidth on mobile.

• Feature Flags: If you are testing a new "Rewards Points" feature, you can pass a variable $showRewards. If true, the query includes the rewards data; if false, it skips it.

5. Detailed Code Examples #

The @include Directive: Includes the field *only if* the argument is true.

query GetUser($showEmail: Boolean!) {
  user(id: "1") {
    name
    # Email is only fetched if $showEmail is true
    email @include(if: $showEmail)
  }
}

The @skip Directive: Skips the field *if* the argument is true.

query GetArticle($isGuest: Boolean!) {
  article(id: "101") {
    title
    content
    # Comments are excluded if the user is a guest
    comments @skip(if: $isGuest) {
      text
      author
    }
  }
}

6. Using Directives with Fragments #

query FetchDashboard($showAdminPanel: Boolean!) {
  me {
    username
    # Include a massive chunk of fields only if the user is an admin
    ...AdminDetails @include(if: $showAdminPanel)
  }
}

7. How the Response Changes #

{
  "data": {
    "user": {
      "name": "Jane Doe"
      // Notice email is completely missing, not even null!
    }
  }
}

8. Custom Directives (Server-Side) #

Schema Example (Server-side):

directive @uppercase on FIELD_DEFINITION

type User {
  name: String @uppercase
}

*(In this scenario, the PHP backend intercepts the resolver and converts the name to uppercase before returning it).*

9. Best Practices #

• Use variables, not hardcoded booleans: Never write @include(if: true). That defeats the purpose. Always link directives to a GraphQL Variable passed from the frontend.

• Optimize Bandwidth: Use directives heavily in mobile application development to avoid downloading large text fields, high-res image URLs, or deep relationships when on cellular data.

10. Common Mistakes #

• Confusing @skip and @include: They are exact opposites. @skip(if: true) means the data will *not* be returned. @include(if: true) means the data *will* be returned. Think carefully about your logic!

• Using Directives for Security: Do NOT use client-side directives (@skip) as a security measure to hide data from unauthorized users. The user can simply change the variable to true and get the data. Security must be handled on the backend.

11. Mini Exercises #

1. 1. What character is used to prefix a directive in a query?

1. 2. If $hideImages is true, should you use @skip(if: $hideImages) or @include(if: $hideImages) to prevent images from loading?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain a scenario in frontend development where you would use the @include directive.

• Q: Can directives be applied to fragments as well as individual fields?

• Q: What is the difference between a built-in client directive (like @skip) and a custom server-side directive?

15. FAQs #

Q: Do directives affect backend performance? A: Yes! If a field is skipped, the GraphQL engine will not execute the resolver for that field, saving database queries and processing time.

16. Summary #

17. Next Chapter Recommendation #