Superjson: Safely Serialize JavaScript Expressions Beyond JSON

Introduction

Standard JSON has limitations when it comes to serializing complex JavaScript types such as Date, Map, Set, BigInt, and RegExp. Developers often face the hassle of manual conversions to handle these types, leading to boilerplate code and potential errors. Superjson provides an elegant solution by offering a thin wrapper over JSON.stringify and JSON.parse, allowing you to safely serialize these types and more.

Originally developed to address data serialization challenges within the Blitz.js framework, Superjson ensures reliable serialization and deserialization with type safety, autocompletion, and a negligible runtime footprint. It is framework-agnostic and offers a perfect fix for Next.js's serialization limitations in getServerSideProps and getInitialProps.

Installation

To get started with Superjson, install it using your preferred package manager:

yarn add superjson

Examples

The easiest way to use Superjson is with its stringify and parse functions. If you know how to use JSON.stringify, you already know Superjson!

Easily stringify any expression you’d like:

import superjson from 'superjson';

const jsonString = superjson.stringify({ date: new Date(0) });

// jsonString === '{"json":{"date":"1970-01-01T00:00:00.000Z"},"meta":{"values":{date:"Date"}}}'

And parse your JSON like so:

const object = superjson.parse<
{ date: Date }
>(jsonString);

// object === { date: new Date(0) }

For cases where you want lower-level access to the json and meta data in the output, you can use the serialize and deserialize functions:

const object = {
  normal: 'string',
  timestamp: new Date(),
  test: /superjson/,
};

const { json, meta } = superjson.serialize(object);

/*
json = {
  normal: 'string',
  timestamp: "2020-06-20T04:56:50.293Z",
  test: "/superjson/",
};

// note that `normal` is not included here; `meta` only has special cases
meta = {
  values: {
    timestamp: ['Date'],
    test: ['regexp'],
  }
};
*/

Why Use Superjson?

Superjson extends standard JSON capabilities to handle a wide array of JavaScript types, making data transfer and persistence much smoother. Here are some key reasons to integrate Superjson into your projects:

• Reliable Serialization and Deserialization: Ensures data integrity for complex types.
• Type Safety with Autocompletion: Enhances developer experience and reduces errors.
• Negligible Runtime Footprint: Keeps your application lightweight and performant.
• Framework Agnostic: Can be used with any JavaScript framework or library.
• Perfect for Next.js: Solves common serialization issues in getServerSideProps, getInitialProps, and getStaticProps hooks, allowing you to pass complex JavaScript objects directly.

Superjson supports many types that standard JSON does not, including:

type	supported by standard JSON?	supported by Superjson?
string	?	?
number	?	?
boolean	?	?
null	?	?
Array	?	?
Object	?	?
undefined	?	?
bigint	?	?
Date	?	?
RegExp	?	?
Set	?	?
Map	?	?
Error	?	?
URL	?	?

Links

For more detailed information, advanced usage, and to contribute to the project, visit the official Superjson GitHub repository:

• Superjson GitHub Repository