graphql-scalars

graphql-scalars is a collection of custom GraphQL scalar types that plug directly into any GraphQL.js-based schema, replacing loosely-typed String and Int fields with scalars that validate real-world formats — email addresses, ISO dates, UUIDs, phone numbers, currency codes, hex colors, IBANs, and dozens more. Each scalar implements the full GraphQLScalarType contract (serialize, parseValue, parseLiteral) so invalid input is rejected at the GraphQL layer itself, before it ever reaches resolver logic.

Maintained by The Guild (the team behind GraphQL Tools, GraphQL Mesh, and GraphQL Yoga), the library ships matching type definitions, resolver maps, and mock values for every scalar, plus optional JSON Schema and codegen-scalar metadata so tools like GraphQL Code Generator can infer the right TypeScript type automatically. It supports both graphql@16 and graphql@17 and is published as a dual ESM/CJS package.

What You Get

• 70+ prebuilt GraphQL scalar types covering dates/times, network addresses, financial identifiers, geodata, and more
• Matching typeDefs, mocks, and resolver maps exported per-scalar for drop-in use with any schema
• A GeoJSON scalar with full type validation for Point, LineString, Polygon and other geometry types
• JSON Schema and codegen-scalar metadata attached to scalars for GraphQL Code Generator integration
• Dual ESM/CJS build with TypeScript typings, compatible with graphql@16 and graphql@17

Common Use Cases

• Enforcing email/phone/URL format at the schema boundary instead of in every resolver
• Representing dates and times precisely (Date, DateTime, LocalTime, Duration, Timestamp) across timezones
• Validating financial and identity fields — IBAN, currency codes, SSNs, patents, ISBNs — in fintech and commerce APIs
• Accepting arbitrary JSON payloads via the JSON/JSONObject scalars for flexible or legacy data
• Generating mock data and TypeScript types automatically via GraphQL Code Generator’s codegen-scalar support

Under The Hood

Architecture The library is organized as a flat collection of independent scalar modules under src/scalars/, each built from a shared serialize/parseValue/parseLiteral triplet, plus a base RegularExpression class (src/RegularExpression.ts) that many scalars extend for regex-based validation, and a shared createGraphQLError helper (src/error.ts) that shims between graphql v16 and v17 error constructors. Subdirectories (GeoJSON/, iso-date/, json/, library/, patent/, ssn/) group related scalars needing dedicated validators or formatters. All scalars, plus their generated mocks (src/mocks.ts) and SDL typeDefs (src/typeDefs.ts), are re-exported through a single src/index.ts barrel file, so the architecture is a flat, additive registry rather than a layered runtime — there’s no central dispatch, and each scalar file is fully self-contained and independently testable. Changing the shared error helper or RegularExpression base class is the only thing that ripples across the package; adding a new scalar is a pure addition needing no coordination elsewhere.

Tech Stack Written in TypeScript, targeting the graphql package as a peer dependency (^16.0.0 || ^17.0.0) with runtime code depending only on tslib. Built with bob-the-bundler into dual ESM and CJS outputs plus separate typings, matching the package.json exports map. Tests run on Vitest with a graphql-16/graphql-17 matrix, linting via ESLint with typescript-eslint and import/n/promise plugins, formatting via Prettier and The Guild’s shared config, with pre-commit enforcement via Husky and lint-staged. Releases are managed with Changesets, publishing to npm with provenance. A companion Next.js documentation site (graphql-scalars.dev) is built and deployed separately. CI runs on GitHub Actions using The Guild’s shared reusable workflows across multiple Node versions.

Code Quality Virtually every scalar has a matching test file exercising serialize/parseValue/parseLiteral for both valid and invalid inputs, plus dedicated common and snapshot tests. Error handling is explicit and typed: invalid input always throws via the shared createGraphQLError helper with a descriptive message, never swallowed or silently coerced. TypeScript is used throughout with real generic type parameters on scalar configs, and naming is consistent (GraphQL<Name> for the scalar instance, GraphQL<Name>Config for its config object). ESLint, Prettier, and a pre-commit hook enforce style, and CI runs the full test matrix across Node versions and both supported graphql major versions before merge.

API Design The core value isn’t a novel algorithm but disciplined API design: every scalar is exported multiple ways (the scalar instance, a resolver alias, a mock value, and an SDL type definition) so consumers can cherry-pick just the piece they need — a resolver map for schema stitching, a mock for testing, or an SDL string for schema-first tooling — without pulling in the whole package. The codegenScalarType and jsonSchema extensions on each scalar are a genuinely useful developer-experience touch: they let GraphQL Code Generator and JSON-Schema-consuming tools infer the correct underlying type automatically instead of requiring manual per-scalar config. Getting started requires no boilerplate — import the named scalar and attach it to a resolver map. The tradeoff is breadth over depth: scalars are intentionally simple format validators rather than configurable systems, which keeps the API predictable but means custom validation logic still requires wrapping.