superjson

Superjson is a thin, framework-agnostic wrapper around JSON.stringify and JSON.parse that safely round-trips JavaScript values plain JSON cannot represent — Date, Map, Set, BigInt, RegExp, Error, URL, undefined, and NaN — without any manual pre- or post-processing.

It works by emitting a standard JSON payload alongside a small meta annotation describing which values need special reconstruction, so output stays fully JSON-compatible for any consumer while superjson-aware clients get the original types back. Widely adopted through tRPC and Next.js data hooks, it adds type safety with autocompletion and a negligible runtime footprint.

What You Get

• Drop-in stringify/parse functions that mirror the native JSON API
• Lower-level serialize/deserialize that expose the json and meta parts separately
• Faithful round-tripping of Date, Map, Set, BigInt, RegExp, Error, URL, undefined, and NaN
• Full TypeScript typings with generic inference on parse/deserialize
• Extensibility hooks: registerClass, registerSymbol, and registerCustom for your own types

Common Use Cases

• Passing Dates and other rich types through Next.js getServerSideProps/getStaticProps
• End-to-end type-safe payloads in tRPC APIs
• Persisting Maps, Sets, and BigInts to storage or caches and reading them back intact
• Serializing Prisma.Decimal or other custom domain types via a registered transformer

Under The Hood

Architecture — The public surface in src/index.ts is a single SuperJSON class whose serialize walks the input via walker in src/plainer.ts, splitting each value into a plain transformedValue (the json) and annotations (the meta.values) while a Map of identities feeds generateReferentialEqualityAnnotations for optional dedupe; deserialize reverses this by applying value and referential-equality annotations, and stringify/parse simply wrap these with native JSON. Type handling flows through src/transformer.ts, backed by three pluggable registries — ClassRegistry, symbol Registry, and CustomTransformerRegistry. Tech Stack — Written in TypeScript (tsc build, ESM type: module) targeting Node >=16, with exactly one runtime dependency, copy-anything, used for safe deep copies during out-of-place deserialization. Dev tooling is Vitest for tests and tsdx/prettier for build and formatting. Code Quality — Testing is thorough: a 34KB index.test.ts plus focused suites for is, plainer, transformer, registry, pathstringifier, and accessDeep. Code is small, cohesive, and strongly typed — src/is.ts is a comprehensive set of typed guard functions (isDate, isMap, isBigint, isTypedArray, etc.) with narrowing predicates, and modules are cleanly separated by responsibility. API Design — Ergonomics are a headline feature: stringify/parse are exact analogues of the native JSON methods, both static (SuperJSON.parse) and instance forms are provided, generics infer the restored type, and extension is a one-call registerCustom/registerClass. Getting started requires no configuration, and the README documents the full type-support matrix and framework recipes.