Deployment & Usage Guide: JSON-js

1. Prerequisites

Runtime: A modern web browser (for client-side use) or Node.js (for server-side/utility use). json2.js is intended for ES3 environments (e.g., IE8). cycle.js requires ES6+ (due to WeakMap).
Tools (for cycle.js only): A JavaScript minifier. The source recommends JSMin. Alternatives include:
- uglifyjs (npm install -g uglify-js)
- terser (npm install -g terser)
No accounts or API keys are required.

2. Installation

The project is a collection of standalone script files. There is no package.json or npm registry publication.

Option A: Clone the repository

git clone https://github.com/douglascrockford/JSON-js.git
cd JSON-js

Option B: Direct download Download the raw files directly:

Place the files in your project's source directory (e.g., ./vendor/ or ./lib/).

3. Configuration

No environment variables or configuration files are needed.

Important usage notes from the source:

json2.js creates a global JSON object with stringify and parse methods. On ES5+ systems (modern browsers, Node.js v0.12+), this file does nothing because native JSON already exists.
cycle.js extends the global JSON object with decycle and retrocycle methods. It must be loaded after json2.js if you need both features in an ES3 environment.
Security: The license warns: "USE YOUR OWN COPY. IT IS EXTREMELY UNWISE TO LOAD CODE FROM SERVERS YOU DO NOT CONTROL." Always host these files yourself.

4. Build & Run

For `json2.js`

No build step is required. Use the file as-is.

For `cycle.js`

You must minify it before deployment, as stated in the source header.

Minify using JSMin (reference implementation):

Download jsmin.c or jsmin.js from https://www.crockford.com/jsmin.html
Run: java -jar jsmin.jar cycle.js > cycle.min.js (or use the Node/Python version)

Minify using UglifyJS (example):

uglifyjs cycle.js -c -m -o cycle.min.js

Minify using Terser (example):

terser cycle.js -c -m -o cycle.min.js

Running Locally (Development)

Browser: Create an HTML file that includes the scripts:

<!DOCTYPE html>
<html>
<head>
  <script src="path/to/json2.js"></script>
  <script src="path/to/cycle.min.js"></script> <!-- Use minified version -->
</head>
<body>
  <script>
    // Example usage
    var obj = {a: 1, b: {c: 2}};
    var json = JSON.stringify(obj);
    console.log(json); // {"a":1,"b":{"c":2}}

    // Decycle a circular structure
    var a = [];
    a[0] = a;
    var decycled = JSON.decycle(a);
    console.log(JSON.stringify(decycled)); // [{"$ref":"$"}]
  </script>
</body>
</html>

Serve this file with any static web server (e.g., python -m http.server, npx serve).

Node.js:

node
> const JSON = require('./path/to/json2.js'); // Attaches to global.JSON
> const cycle = require('./path/to/cycle.min.js'); // Attaches to global.JSON
> const obj = {a: 1};
> JSON.stringify(obj);
'{"a":1}'

Note: In Node, these files modify the global JSON object. Use require for side-effects only.

5. Deployment

Deploy the minified cycle.min.js and the original json2.js (if supporting ES3) as static assets.

Recommended platforms:

Static Site Hosts: GitHub Pages, Netlify, Vercel, Cloudflare Pages. Upload the .js files and reference them via <script src="...">.
CDN: Serve from your own CDN (e.g., AWS S3 + CloudFront). Do not use third-party CDNs you don't control, per the license warning.
Traditional Web Server: Place files in your web root (e.g., /var/www/html/js/) and include them in HTML pages.

Example HTML snippet for production:

<script src="/js/json2.js"></script> <!-- Only needed for IE8/ES3 support -->
<script src="/js/cycle.min.js"></script>

For modern browsers (ES5+), you can omit json2.js entirely.

6. Troubleshooting

Issue	Solution
`JSON.stringify` is undefined in old browser (IE8)	Ensure `json2.js` is included before any script that uses `JSON`. The file only defines `JSON` if it doesn't already exist.
`JSON.decycle` is not a function	Ensure `cycle.js` (or `cycle.min.js`) is loaded after `json2.js`. Also verify the file is minified and served correctly (check browser console for 404s).
`WeakMap` error in console when loading `cycle.js`	Your environment (browser or Node version) does not support ES6 `WeakMap`. `cycle.js` requires ES6+. Upgrade your runtime or avoid using `decycle`/`retrocycle`.
Minification fails with `Unexpected token`	You are using an unminified source file that contains comments or non-standard syntax. Use the provided `cycle.js` as input; do not preprocess it.
Duplicate `JSON` object or methods	In ES5+ environments, `json2.js` intentionally does nothing. If you see conflicts, you likely have another library redefining `JSON`. Load `json2.js` as early as possible.
`decycle` produces incorrect `$ref` paths	`decycle` uses JSONPath syntax. Ensure you are not modifying the decycled structure before `stringify`-ing it. The `$ref` objects must remain intact for `retrocycle` to work later.
Circular reference causes `TypeError: cyclic object value`	You are trying to `JSON.stringify` a circular structure without first calling `JSON.decycle`. Always decycle: `JSON.stringify(JSON.decycle(obj))`.

Debugging tip: Open the browser's developer console and type JSON to inspect its methods. Verify stringify, parse, decycle, and retrocycle are present as expected.

How to Deploy & Use douglascrockford/JSON-js