flightcontrolhq

superjson: Safely Serialize JavaScript Values Beyond JSON

Superjson is a TypeScript library that wraps JSON serialization to preserve JavaScript values such as Dates, BigInts, Maps, and Sets. It suits applications that need JSON-compatible data while retaining types across serialization, including Next.js data hooks.

Stars
5.3k
Forks
134
Stars, last 30 days
+3
Last commit
4 months ago
Contributors
39

Our take

Quietno commits in the last 90 days and no release in a year

Health score

31/100

How it is scored
Activity
19
Community
64
Issues
21
Pull requests
20

+3 stars in the last 30 days

Superjson is a focused, MIT-licensed solution for preserving common JavaScript types across JSON boundaries, though its recent release and maintenance activity is quiet.

Good fit if

  • Your JavaScript or TypeScript app needs reliable round trips for built-in values that plain JSON does not support.
  • You use Next.js data hooks and want to avoid manually converting supported values.
  • You can accommodate a Node.js 16 or newer runtime and prefer a small, framework-agnostic library.

Look elsewhere if

  • Your data must be consumed as plain JSON without transmitting or interpreting Superjson metadata, and type restoration is not needed.
  • You need an actively maintained project with recent commits or releases, since the repository is marked quiet with no commits in the last 90 days and no release in a year.
  • Your important value types are not built in and you cannot register and maintain custom handlers.
All health signals
Last commit2026-06-18 (4 months ago)
Commits, last 90 days0
Releases, last 12 months0 (latest v2.2.5, 2025-10-28)
Contributors39 (top contributor: 52% of commits)
Issues closed, last 90 days0
Pull requests merged, last 90 days0
Project age11 years

Checked on 2026-10-31 with the GitHub API.

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

5,289

Forks

139

Change since Nov 18, 2026: 0 stars·+1 forks

Overview

Superjson is a TypeScript library that adds metadata to JSON serialization so JavaScript values that plain JSON.stringify cannot represent faithfully can be restored after parsing. It is designed for JavaScript and TypeScript applications that need to pass values such as Dates or BigInts through JSON-compatible boundaries without manually converting them first.

The project is framework agnostic, with documented Next.js integrations for its data hooks. Its serialize and deserialize APIs also allow teams to send ordinary JSON data alongside type metadata to clients that opt into Superjson.

Key Features

  • stringify and parse provide a familiar, JSON-style round trip.
  • serialize and deserialize expose JSON-compatible data and metadata separately.
  • Handles built-in values beyond standard JSON, including Date, BigInt, Map, Set, RegExp, Error, URL, and undefined.
  • TypeScript typing supports typed use and editor autocompletion.
  • Custom value handlers can be registered for types such as Decimal.js or Prisma.Decimal.
  • Offers documented Babel and experimental SWC plugin integrations for Next.js.
  • Deserialization can mutate the input object in place when that is safe and useful.

Use Cases

  • Next.js developers passing Dates or other supported values through server-side or static data hooks.
  • TypeScript application teams sending structured values between services or clients while preserving supported JavaScript types.
  • API developers who want JSON-compatible payloads but can also transmit Superjson metadata for richer deserialization.
  • Applications that use custom value objects and can define explicit serialization and deserialization handlers.

What you need

Detected in the repository

  • Node.js >=16 (from package.json)
  • Automated checks on GitHub Actions

License in plain words

MITpermissive

  • Commercial use: yes
  • Modify and redistribute: yes
  • You must keep: the copyright and license notice
  • Share your changes: no

A summary, not legal advice: the LICENSE file is what applies.

Getting Started

Install with a package manager:

yarn add superjson

See the README for API details, custom type recipes, and Next.js setup.

Considerations

  • The repository is not archived, but its health is marked quiet: there have been no commits in the last 90 days and no release in a year. The latest listed release is v2.2.5.
  • The project has contributors across the repository, and contribution is not assessed as concentrated around one person. Recent issue and pull request activity is also absent in the measured period.
  • Node.js 16 or newer is listed as a runtime requirement. The supplied requirements do not specify Docker or a database.
  • Built-in support is limited to the listed types; other types need custom registrations, which must run before Superjson calls.
  • The MIT license permits broad use, subject to its license terms.

Found this useful?

Share it with someone who would like superjson.