graphql-scalars

library1.25.0jsnpmunverified

A comprehensive library of custom GraphQL scalar types for precise type-safe schemas. Current stable version is 1.25.0, with regular releases. It provides over 40 scalars (DateTime, JSON, UUID, Email, etc.) not included in base GraphQL, supporting GraphQL v0.8 to v16. Maintained by The Guild, it ships TypeScript definitions and is ESM- and CJS-compatible. Key differentiators: extensive scalar collection, active maintenance, broad GraphQL version support, and detailed documentation on graphql-scalars.dev.

database programming

npm install graphql-scalars

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-SCALARS

graphql-scalars

databasejavascriptv1.25.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DateTime

✓ import { DateTime } from 'graphql-scalars'

✗ const DateTime = require('graphql-scalars').DateTime

Default import pattern works for all named scalars. CommonJS require still works but loses tree-shaking.

JSON

✓ import { JSON } from 'graphql-scalars'

✗ import JSON from 'graphql-scalars'

JSON is a named export, not default. Default export is an object containing all scalars.

GraphQLBigInt

✓ import { GraphQLBigInt } from 'graphql-scalars/esm'

✗ import { GraphQLBigInt } from 'graphql-scalars'

Since v1.15, for ESM in Node.js you must use the /esm subpath to avoid 'require is not defined' errors. For bundlers and CJS, the main import works.

type DateTime

✓ import type { DateTime } from 'graphql-scalars'

✗ import { DateTime } from 'graphql-scalars' (when only using as type)

TypeScript users can import types only to avoid runtime overhead. This is optional but recommended.

Demonstrates importing and using DateTime, EmailAddress, and JSON scalars with @graphql-tools/schema.

import { DateTime, EmailAddress, JSON } from 'graphql-scalars'; import { makeExecutableSchema } from '@graphql-tools/schema'; const typeDefs = ` scalar DateTime scalar EmailAddress scalar JSON type User { id: ID! email: EmailAddress! createdAt: DateTime! metadata: JSON } type Query { user(id: ID!): User } `; const resolvers = { DateTime, EmailAddress, JSON, Query: { user: (_, { id }) => ({ id, email: 'user@example.com', createdAt: new Date().toISOString(), metadata: { role: 'admin' } }) } }; export const schema = makeExecutableSchema({ typeDefs, resolvers });

Debug

Known issues

breakingNamed export 'GraphQLTimestamp' removed in v1.16; use 'Timestamp' instead.

fix

Replace 'GraphQLTimestamp' with 'Timestamp' in imports.

affects: >=1.16.0

breakingScalars that were previously named with 'GraphQL' prefix (e.g. 'GraphQLUUID') renamed to base name ('UUID') in v1.15.

fix

Update imports from 'GraphQL*' to the capitalized scalar name (e.g. 'import { UUID } from ...').

affects: >=1.15.0

deprecatedThe default export (all scalars in one object) is deprecated; prefer named imports for tree-shaking.

fix

Use named imports like `import { DateTime } from 'graphql-scalars'` instead of `import scalars from 'graphql-scalars'`.

affects: >=1.20.0

gotchaWhen using ESM in Node.js (type: module), importing from the main entry point causes 'require is not defined' error.

fix

Import from 'graphql-scalars/esm' instead of 'graphql-scalars'.

affects: >=1.15.0

gotchaScalar regex validations (e.g. EmailAddress) may differ from RFC standards; test edge cases.

fix

Review the validation logic on the documentation site for each scalar.

affects: all

breakingSupport for GraphQL versions below 0.13 dropped in v1.18.

fix

Upgrade GraphQL peer dependency to ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0.

affects: >=1.18.0

Errors

Common errors & fixes

Error: Cannot find module 'graphql-scalars'

Missing package installation or incorrect import path in ESM context.

fix

Run `npm install graphql-scalars` and ensure you are importing correctly. For ESM projects, use `import { ... } from 'graphql-scalars/esm'`.

TypeError: (0 , graphql_scalars__WEBPACK_IMPORTED_MODULE_0__.default) is not a function

Using default import when GraphQL expects a named scalar type.

fix

Use named import: `import { DateTime } from 'graphql-scalars'` instead of `import scalars from 'graphql-scalars'`.

ReferenceError: require is not defined

ESM project attempting to use CommonJS require on the main entry point.

fix

Change import to ESM: `import { DateTime } from 'graphql-scalars/esm'` or use dynamic import.

GraphQLError: Scalar 'DateTime' must have a 'serialize' function.

The scalar resolver object is missing a serialize function (often due to destructuring incorrectly).

fix

Ensure the resolver is set as `DateTime: DateTime` where DateTime is the imported object.

Upgrade

Version history

1.25.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency required for GraphQL type definitions and scalar construction

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/Urigo/graphql-scalars ↗

packagegraphql-scalars ↗

homepagehttps://github.com/Urigo/graphql-scalars#readme ↗