superjson

For stable Next.js support using Babel, follow these steps:

1. Install the Babel plugin:

yarn add babel-plugin-superjson-next

2. Add it to your .babelrc file:

{
  "presets": ["next/babel"],
  "plugins": [
    "superjson-next"
  ]
}

For Next.js v13 or above, you can use the experimental SWC plugin for faster compilation.

1. Install the plugin:

yarn add next-superjson-plugin

2. Add it to your next.config.js:

module.exports = {
  experimental: {
    swcPlugins: [
      [
        'next-superjson-plugin',
        {
          excluded: [],
        },
      ],
    ],
  },
};

Install the superjson library using your preferred package manager.

yarn add superjson

You can extend Superjson to support non-default data types using SuperJSON.registerCustom. This should be executed before any other SuperJSON calls (e.g., in _app.ts for Next.js).

import { Decimal } from 'decimal.js';

SuperJSON.registerCustom<Decimal, string>(
  {
    isApplicable: (v): v is Decimal => Decimal.isDecimal(v),
    serialize: v => v.toJSON(),
    deserialize: v => new Decimal(v),
  },
  'decimal.js'
);

For lower-level access to the split json and meta data, use serialize and deserialize. This is useful for APIs that need to remain JSON-compatible for standard clients while providing metadata for Superjson-enabled clients.

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/",
};

meta = {
  values: {
    timestamp: ['Date'],
    test: ['regexp'],
  }
};
*/

// To restore the object:
deserialize({ json, meta }, { inPlace: true });

The simplest way to use Superjson is via stringify and parse. These functions behave similarly to JSON.stringify and JSON.parse but support complex types like Date automatically.

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"}}}'

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

Deserializes the output of Superjson back into the original value.

deserialize({ json, meta }, { inPlace: true });

Serializes any JavaScript value into a JSON-compatible object containing json and meta keys.

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

Serializes and then stringifies your JavaScript value into a single string.

const jsonString = stringify(object);

Superjson supports several types that standard JSON does not.

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