I’ve recently been taking advantage of building custom scalars to simplify presentational logic across all my API clients. Before I share with you my favorite scalars, let’s talk about what scalars are and what custom scalars can allow you to do.

What are Scalars?

Scalars are another type and represent leaf values of the GraphQL type system. A good way to look at this is through this graph:

The leaves of this graph are the scalars.

Even if you didn’t know what scalars were, there’s a good chance you have used them in GraphQL development.

String, Int, Boolean, Float are all built-in scalars that you can do a lot with out of the box!

But what really interested me about scalars was this excerpt from the GraphQL specification:

GraphQL provides a number of built‐in scalars, but type systems can add additional scalars with semantic meaning.

The semantic meaning leaves it open to the interpretation of the engineers implementing their system!

Why add custom scalars?

Well the goal of leveraging this customization is to unify how data is transferred between your clients and server.

Let’s take an example where you returned a date to the clients as a Float, and you use a library like moment to format it into a display date. What happens to your iOS or Android applications? For them, they would have to convert it to a date object just to convert it back to a string. 3 different clients doing 3 different things to represent the same thing to the user? Sounds like the job for a custom scalar.

Another use case comes with validation. A GraphQL server’s job is to parse incoming requests, validate them, and execute. With custom scalars you can add some type checking for more product specific use cases. For example, let’s say your input type looks like this

input SocialUrl {

url: String

}

User’s could put any string that may or not be a valid url! A custom scalar for enforcing the shape of this could be useful in your system

input SocialUrl {

url: SocialMediaUrl

}

In the above example, the SocialMediaUrl would enforce a https link and potentially all the social network companies you support in product.

Now that we know what scalars are and what they can do for us, here are 5 scalars I think are super useful when building applications.

1. Date and DateTime

GraphQL ISO Date is a set of RFC 3339 compliant time scalars.

It allows resolvers like this:

To represent data like this in clients:

2. URL

This module from OK GROW! has a lot of cool scalars! I like this URL scalar because it enforces the RFC3986 spec. Now you can ensure you’re getting the right data from your clients!

3. EmailAddress

I like this EmailAddress scalar because now my client’s have extra assurance that the strings they are intending to be emails are actually enforced that way.

4. USCurrency

For my product we use Stripe for handling payments. Since Stripe’s currency is formatted in ‘cents’ we adopted the same approach. We definitely did not want to have all our clients formatting cents into a string in dollars. Thus, we made a scalar to format cents to US Currency!

1000 cents -> $10.00 sent to the clients

5. JSON

This scalar is useful for when you need an escape hatch. Let’s say you are talking to a third party soap api wrapped in GraphQL. Now you could spend your time converting WSDL schemas into GraphQL or you can say F it and leverage the API to just expect JSON. This is convenient for sticky situations, but I wouldn’t make it a habit to use it!

Conclusion

Using custom scalars has helped me sleep a little easier lately. The added type safety surrounding validation scalars really helps lock down your expectations for what kind of requests are made to your GraphQL server. Along with validation, scalars that transform data have helped take simple formatting logic from multiple clients and push them to the GraphQL server. Try incorporating them today!