![\"superjson\"](\"./docs/superjson-banner.png\")
![\"superjson\"](\"./docs/superjson.png\")
\n \n
\n Safely serialize JavaScript expressions to a superset of JSON, which includes Dates, BigInts, and more.\n
\n\n\n \n![\"All](\"https://img.shields.io/badge/all_contributors-31-orange.svg?style=flat-square\"){kind=icon}
\n\n \n ![\"npm\"](\"https://img.shields.io/npm/v/superjson\")
![\"Flightcontrol](\"https://raw.githubusercontent.com/blitz-js/blitz/main/assets/flightcontrol.png\")
](https://www.flightcontrol.dev/?ref=superjson)\n\nSuperjson logo by [NUMI](https://github.com/numi-hq/open-design):\n\n[![\"NUMI](\"https://raw.githubusercontent.com/numi-hq/open-design/main/assets/numi-lockup.png\")
](https://numi.tech/?ref=superjson)\n\n## Getting started\n\nInstall the library with your package manager of choice, e.g.:\n\n```\nyarn add superjson\n```\n\n## Basic Usage\n\nThe easiest way to use Superjson is with its `stringify` and `parse` functions. If you know how to use `JSON.stringify`, you already know Superjson!\n\nEasily stringify any expression youβd like:\n\n```js\nimport superjson from 'superjson';\n\nconst jsonString = superjson.stringify({ date: new Date(0) });\n\n// jsonString === '{\"json\":{\"date\":\"1970-01-01T00:00:00.000Z\"},\"meta\":{\"values\":{date:\"Date\"}}}'\n```\n\nAnd parse your JSON like so:\n\n```js\nconst object = superjson.parse<\n{ date: Date }\n>(jsonString);\n\n// object === { date: new Date(0) }\n```\n\n## Advanced Usage\n\nFor cases where you want lower level access to the `json` and `meta` data in the output, you can use the `serialize` and `deserialize` functions.\n\nOne great use case for this is where you have an API that you want to be JSON compatible for all clients, but you still also want to transmit the meta data so clients can use superjson to fully deserialize it.\n\nFor example:\n\n```js\nconst object = {\n normal: 'string',\n timestamp: new Date(),\n test: /superjson/,\n};\n\nconst { json, meta } = superjson.serialize(object);\n\n/*\njson = {\n normal: 'string',\n timestamp: \"2020-06-20T04:56:50.293Z\",\n test: \"/superjson/\",\n};\n\n// note that `normal` is not included here; `meta` only has special cases\nmeta = {\n values: {\n timestamp: ['Date'],\n test: ['regexp'],\n }\n};\n*/\n```\n\n## Using with Next.js\n\nThe `getServerSideProps`, `getInitialProps`, and `getStaticProps` data hooks provided by Next.js do not allow you to transmit Javascript objects like Dates. It will error unless you convert Dates to strings, etc.\n\nThankfully, Superjson is a perfect tool to bypass that limitation!\n\n### Next.js SWC Plugin (experimental, v13 or above)\n\nNext.js SWC plugins are [experimental](https://nextjs.org/docs/advanced-features/compiler#swc-plugins-experimental), but promise a significant speedup.\nTo use the [SuperJSON SWC plugin](https://github.com/blitz-js/next-superjson-plugin), install it and add it to your `next.config.js`:\n\n```sh\nyarn add next-superjson-plugin\n```\n\n```js\n// next.config.js\nmodule.exports = {\n experimental: {\n swcPlugins: [\n [\n 'next-superjson-plugin',\n {\n excluded: [],\n },\n ],\n ],\n },\n};\n```\n\n### Next.js (stable Babel transform)\n\nInstall the library with your package manager of choice, e.g.:\n\n```sh\nyarn add babel-plugin-superjson-next\n```\n\nAdd the plugin to your .babelrc. If you don't have one, create it.\n\n```js\n{\n \"presets\": [\"next/babel\"],\n \"plugins\": [\n ...\n \"superjson-next\" // ????\n ]\n}\n```\n\nDone! Now you can safely use all JS datatypes in your `getServerSideProps` / etc. .\n\n## API\n\n### serialize\n\nSerializes any JavaScript value into a JSON-compatible object.\n\n#### Examples\n\n```js\nconst object = {\n normal: 'string',\n timestamp: new Date(),\n test: /superjson/,\n};\n\nconst { json, meta } = serialize(object);\n```\n\nReturns **`json` and `meta`, both JSON-compatible values.**\n\n## deserialize\n\nDeserializes the output of Superjson back into your original value.\n\n#### Examples\n\n```js\nconst { json, meta } = serialize(object);\n\ndeserialize({ json, meta }, { inPlace: true });\n```\n\nOptions\n\n- `inPlace: boolean`\n - Default: `false`\n - Mutate the input json object in place instead of returning a deep copy\n - `inPlace: true` will be much more performant on large objects if it's safe to mutate it\n\nReturns **`your original value`**.\n\n### stringify\n\nSerializes and then stringifies your JavaScript value.\n\n#### Examples\n\n```js\nconst object = {\n normal: 'string',\n timestamp: new Date(),\n test: /superjson/,\n};\n\nconst jsonString = stringify(object);\n```\n\nReturns **`string`**.\n\n### parse\n\nParses and then deserializes the JSON string returned by `stringify`.\n\n#### Examples\n\n```js\nconst jsonString = stringify(object);\n\nparse(jsonString);\n```\n\nReturns **`your original value`**.\n\n---\n\nSuperjson supports many extra types which JSON does not. You can serialize all these:\n\n| type | supported by standard JSON? | supported by Superjson? |\n| ----------- | --------------------------- | ----------------------- |\n| `string` | β
| β
|\n| `number` | β
| β
|\n| `boolean` | β
| β
|\n| `null` | β
| β
|\n| `Array` | β
| β
|\n| `Object` | β
| β
|\n| `undefined` | β | β
|\n| `bigint` | β | β
|\n| `Date` | β | β
|\n| `RegExp` | β | β
|\n| `Set` | β | β
|\n| `Map` | β | β
|\n| `Error` | β | β
|\n| `URL` | β | β
|\n\n## Recipes\n\nSuperJSON by default only supports built-in data types to keep bundle-size as low as possible.\nHere are some recipes you can use to extend to non-default data types.\n\nPlace them in some central utility file and make sure they're executed before any other `SuperJSON` calls.\nIn a Next.js project, `_app.ts` would be a good spot for that.\n\n### `Decimal.js` / `Prisma.Decimal`\n\n```ts\nimport { Decimal } from 'decimal.js';\n\nSuperJSON.registerCustom![\"Dylan](\"https://avatars3.githubusercontent.com/u/24858006?v=4?s=100\") Dylan Brookes ???? ???? ???? β οΈ | \n ![\"Simon](\"https://avatars1.githubusercontent.com/u/14912729?v=4?s=100\") Simon Knott ???? ???? β οΈ ???? | \n ![\"Brandon](\"https://avatars3.githubusercontent.com/u/8813276?v=4?s=100\") Brandon Bayer ???? | \n ![\"Jeremy](\"https://avatars3.githubusercontent.com/u/2754163?v=4?s=100\") Jeremy Liberman β οΈ ???? | \n ![\"Joris\"/](\"https://avatars1.githubusercontent.com/u/7545547?v=4?s=100\") Joris ???? | \n ![\"tomhooijenga\"/](\"https://avatars0.githubusercontent.com/u/1853235?v=4?s=100\") tomhooijenga ???? ???? | \n ![\"AdemΓlson](\"https://avatars2.githubusercontent.com/u/5417662?v=4?s=100\") AdemΓlson F. Tonato β οΈ | \n
![\"Piotr](\"https://avatars0.githubusercontent.com/u/15332326?v=4?s=100\") Piotr Monwid-Olechnowicz ???? | \n ![\"Alex](\"https://avatars1.githubusercontent.com/u/459267?v=4?s=100\") Alex Johansson ???? β οΈ | \n ![\"Simon](\"https://avatars.githubusercontent.com/u/2821076?v=4?s=100\") Simon Edelmann ???? ???? ???? | \n ![\"Sam](\"https://avatars.githubusercontent.com/u/6242344?v=4?s=100\") Sam Garson ???? | \n ![\"Mark](\"https://avatars.githubusercontent.com/u/1357323?v=4?s=100\") Mark Hughes ???? | \n ![\"Lxxyx\"/](\"https://avatars.githubusercontent.com/u/13161470?v=4?s=100\") Lxxyx ???? | \n ![\"MΓ‘ximo](\"https://avatars.githubusercontent.com/u/1158253?v=4?s=100\") MΓ‘ximo Mussini ???? | \n
![\"Peter](\"https://avatars.githubusercontent.com/u/425971?v=4?s=100\") Peter Dekkers ???? | \n ![\"Gabe](\"https://avatars.githubusercontent.com/u/16123225?v=4?s=100\") Gabe O'Leary ???? | \n ![\"Benjamin\"/](\"https://avatars.githubusercontent.com/u/15611419?v=4?s=100\") Benjamin ???? | \n ![\"Ionut-Cristian](\"https://avatars.githubusercontent.com/u/581999?v=4?s=100\") Ionut-Cristian Florescu ???? | \n ![\"Chris](\"https://avatars.githubusercontent.com/u/68551954?v=4?s=100\") Chris Johnson ???? | \n ![\"Nicholas](\"https://avatars.githubusercontent.com/u/20798889?v=4?s=100\") Nicholas Chiang ???? ???? | \n ![\"Datner\"/](\"https://avatars.githubusercontent.com/u/22598347?v=4?s=100\") Datner ???? | \n
![\"ruessej\"/](\"https://avatars.githubusercontent.com/u/85690286?v=4?s=100\") ruessej ???? | \n ![\"JH.Lee\"/](\"https://avatars.githubusercontent.com/u/39466936?v=4?s=100\") JH.Lee ???? | \n ![\"narumincho\"/](\"https://avatars.githubusercontent.com/u/16481886?v=4?s=100\") narumincho ???? | \n ![\"Markus](\"https://avatars.githubusercontent.com/u/12430681?v=4?s=100\") Markus Greystone ???? | \n ![\"darthmaim\"/](\"https://avatars.githubusercontent.com/u/2511547?v=4?s=100\") darthmaim ???? | \n ![\"Max](\"https://avatars.githubusercontent.com/u/430872?v=4?s=100\") Max Malm ???? | \n ![\"Tyler](\"https://avatars.githubusercontent.com/u/366538?v=4?s=100\") Tyler Collier ???? | \n
![\"Nick](\"https://avatars.githubusercontent.com/u/884128?v=4?s=100\") Nick Quebbeman ???? | \n ![\"Tom](\"https://avatars.githubusercontent.com/u/32314?v=4?s=100\") Tom MacWright ???? ???? | \n ![\"Peter](\"https://avatars.githubusercontent.com/u/7863452?v=4?s=100\") Peter Budai ???? | \n