Server-Driven UI and GraphQL

schema-design server-driven-ui

Server-Driven UI (SDUI) reduces client-side logic and provides consistency across client platforms (web/iOS/Android/etc) by returning UI data from an API instead of domain data. This approach is geared toward use cases where collaboration between front-end and back-end teams is possible and there is a strong desire to build a cohesive experience across multiple teams and organizations.

When building a graph with server-driven UI, it’s often desirable to converge the schema with the design language being used by client teams. In practice, this requires a definitive design system and a well-defined collection of components to use on the front end to render views.

The primary need for SDUI comes from mobile native-app development. These platforms require shipping versions of your client-side app to a store that usually has a lengthy review process before a new version gets published. Then, even after a new version of the app is released, users have to update their versions from the store to start using or experiencing the new features.

Instead, if your API returned exactly what was displayed on the screen you could control when different UI elements or text are displayed. Changes can also be made to the inputs sent to the API without requiring any app updates.

SDUI is not a framework to be implemented but a design pattern that can be implemented in many different ways while still following the same core principles. You could have just a few parts of the app controlled from the server, like text or if certain elements should be hidden. It could then advance to more parts like changing theming or component features from the API, all the way to having a generic layout that could render any UI component in any order.

Take for example this mock ecommerce schema which allows us to display a list of featured products:

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String
4
  # other product fields...
5
}
6

7
type ProductsCarousel {
8
  products: [Product]
9
  count: Int
10
}
11

12
type ProductsList {
13
  products: [Product]
14
  count: Int
15
}
16

17
type ProductsError {
18
  message: String!
19
}
20

21
union FeaturedProductsResponse = ProductsList | ProductsCarousel | ProductsError
22

23
type Query {
24
  featuredProducts: FeaturedProductsResponse
25
}

While querying Query.featuredProducts the client can now render multiple specific experiences depending on the query result. We can use the returned __typename value to determine if a collection of products should be rendered, or show the user an error message.

1
fragment productFields on Product {
2
  id
3
  name
4
  price
5
}
6

7
query FeaturedProductsCollection {
8
  featuredProducts {
9
    __typename
10
    ... on ProductsList {
11
      products {
12
        ...productFields
13
      }
14
    }
15
    ... on ProductsCarousel {
16
      products {
17
        ...productFields
18
      }
19
    }
20
    ... on ProductsError {
21
      message
22
    }
23
  }
24
}

Clients can then have a collection of types mapped to which UI component they should use for their specific platform and render it with the correct data.

1
const { data } = useQuery(FeaturedProductsCollection);
2

3
// Maps GraphQL __typename to UI component
4
const TYPE_COMPONENTS = {
5
  ProductList: ListComponent,
6
  ProductCarousel: CarouselComponent,
7
  ProductError: ErrorComponent
8
};
9

10
const component = TYPE_COMPONENTS[data.featuredProducts.__typename];
11
if (!component) { throw new Error('Unknown Type Returned!'); }
12

13
renderComponet(component, data);

This means that from the API response you can dynamically choose when to render different components or start displaying different components based on any of our API inputs, including headers or user information.

Home