Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including json-ref-escodegen with all npm packages installed. Try it out:

var jsonRefEscodegen = require("json-ref-escodegen")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

json-ref-escodegen v0.0.0

Performant, lean and bare-simple JSON Schema $ref resolver


This is not yet another JSON Schema $ref resolver. See key differences and how does it work? to learn more.


yarn add json-ref-escodegen

or if npm is package manager of your choice

npm install json-ref-escodegen --save

Key differences

  • generates JS code instead of object literal supposed to be eventually serialized back to JSON / YAML / any other text format
  • highly scalable - it's expected to work on projects rather than single files
  • very performant - one of the quickest (if not the quickest) $ref resolver
  • excellent long-term caching possibilities - each $ref is as a separate module (file)
  • first-class support for all kinds of circularity
  • truly environment agnostic - does not depend on any fs module or browser global
  • no concept of resolvers - you are in charge of the whole reading & path parsing process
  • no parser included - bring your own!
  • no CLI


import path from 'path';
import fs from 'fs';
import { fileURLToPath } from 'url';
import generate, { Dependencies, ModuleRegistry } from 'json-ref-escodegen';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const source = path.join(__dirname, 'src/__fixtures__/root.json');
const dist = path.join(__dirname, 'dist/output');

const module = await generate(
    module: 'esm',
    fs: {
      read: async (src) => JSON.parse(await fs.promises.readFile(src, 'utf8')),
      write: (target, content) => fs.promises.writeFile(path.join(dist, target), content),
    dependencies: new Dependencies(),
    moduleRegistry: new ModuleRegistry(),

const { default: dereferenced } = await import(path.join(dist, `${}.mjs`));


How does it work?

json-ref-escodegen generates valid JS code for each processed document. Each $ref is a getter pointing at external referenced module, or the same module if it's an internal ref.

How do I serialize my crap back to other text format, such as JSON or YAML?

It's as simple as importing the generated module and running JSON.stringify or YAML counterpart. I strongly recommend usage of YAML due to anchors, or a safe JSON stringifer.


Apache License 2.0

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free