@upbound/exporter

Jest-compatible CommonJS re-exports for ESM-only libraries that cause parsing errors in Jest.

The Problem

Some npm libraries only ship ESM modules, which Jest cannot parse by default:

Jest encountered an unexpected token
SyntaxError: Unexpected token 'export'

The Solution

This package provides zero-configuration CommonJS re-exports of problematic libraries. Simply import from this package instead of the original library, and Jest will work without any additional setup.

Architecture

@upbound/exporter/
├── index.js              # Main entry point (re-exports all libraries)
├── index.d.ts            # TypeScript definitions (re-exports all types)
├── jsonpath.js           # jsonpath-plus re-export
├── jsonpath.d.ts         # jsonpath-plus types
├── <library>.js          # Future library re-exports
└── <library>.d.ts        # Future library types

Installation

This is a monorepo internal package. It's automatically available after running:

yarn install

Usage

❌ Don't Import Directly

// Don't do this in your apps/packages
import { JSONPath } from '@upbound/exporter';

✅ Import from @upbound/utils

// Do this instead
import { JSONPath } from '@upbound/utils';

NOTE: Or corresponding shared package

📦 For @upbound/utils Maintainers

If you're building functionality in @upbound/utils:

// packages/utils/jsonpath/index.ts
import { JSONPath } from '@upbound/exporter';

export function JSONPath({ path, json }) {
  return JSONPath({
    path,
    json,
    eval: 'safe', // Add your defaults
    wrap: true,
  });
}

Currently Re-exported Libraries

| Library | Exports | CJS Build Path | Version | | --------------- | ---------- | --------------------------------------- | --------- | | jsonpath-plus | JSONPath | jsonpath-plus/dist/index-node-cjs.cjs | ^10.3.0 |

Adding a New Library

Step 1: Install the Library

cd packages/exporter
yarn add your-library

Step 2: Create Library-Specific Files

Create <library-name>.js:

/**
 * Jest-compatible re-export of <library-name>
 */

let SomeExport;

try {
  // Adjust path to the CommonJS build
  SomeExport = require('library-name/dist/index.cjs').SomeExport;
} catch (e) {
  const path = require('path');
  const rootPath = path.join(__dirname, '../../node_modules/library-name/dist/index.cjs');
  SomeExport = require(rootPath).SomeExport;
}

module.exports = {
  SomeExport,
};

Create <library-name>.d.ts:

/**
 * TypeScript definitions for <library-name> re-export
 */

export interface SomeExportOptions {
  // Define options
}

export function SomeExport(options: SomeExportOptions): ReturnType;

Step 3: Update index.js

// Add to index.js
const { JSONPath } = require('./jsonpath');
const { SomeExport } = require('./library-name'); // Add this

module.exports = {
  JSONPath,
  SomeExport, // Export it
};

Step 4: Update index.d.ts

// Add to index.d.ts
export { JSONPath, JSONPathOptions } from './jsonpath';
export { SomeExport, SomeExportOptions } from './library-name'; // Add this

Step 5: Update package.json

Add the new files to the files array and update dependencies:

{
  "dependencies": {
    "jsonpath-plus": "^10.3.0",
    "library-name": "^x.y.z"
  },
  "files": ["index.js", "index.d.ts", "jsonpath.js", "jsonpath.d.ts", "library-name.js", "library-name.d.ts"]
}

Step 6: Update This README

Add the new library to the "Currently Re-exported Libraries" table.

Step 7: Test It

# Test that Jest can import it
cd packages/utils
yarn test

How It Works

Each library has its own file that:

1. Requires the CommonJS build using Node's require()
2. Exports using CommonJS (module.exports)
3. Provides TypeScript definitions in a .d.ts file
4. Handles both local and hoisted node_modules locations

The main index.js re-exports everything, providing a single entry point.

File Organization

exporter/
├── index.js           → Re-exports all libraries
├── index.d.ts         → Re-exports all types
│
├── jsonpath.js        → jsonpath-plus implementation
├── jsonpath.d.ts      → jsonpath-plus types
│
├── future-lib.js      → Future library implementation
├── future-lib.d.ts    → Future library types
│
└── README.md          → This file

Benefits

✅ Zero Configuration - No Jest setup needed anywhere
✅ Scalable - Easy to add new libraries
✅ Organized - One file per library
✅ Type Safe - Full TypeScript support
✅ Maintainable - Clear separation of concerns
✅ Transparent - Works like the original libraries

Example: Using JSONPath

In Your App (via @upbound/utils)

import { JSONPath } from '@upbound/utils';

const data = {
  store: {
    book: [
      { title: 'Book 1', price: 10 },
      { title: 'Book 2', price: 15 },
    ],
  },
};

const titles = JSONPath({
  path: '$.store.book[*].title',
  json: data,
});

console.log(titles); // ['Book 1', 'Book 2']

In Tests (No Configuration Needed)

import { JSONPath } from '@upbound/utils';

describe('My Feature', () => {
  it('should query JSON data', () => {
    const result = JSONPath({
      path: '$.users[0].name',
      json: { users: [{ name: 'Alice' }] },
    });

    expect(result).toEqual(['Alice']);
  });
});

Troubleshooting

"Cannot find module '@upbound/exporter'"

Run from monorepo root:

yarn install

"SyntaxError: Unexpected token 'export'"

You're importing from the original ESM library instead of this wrapper. Change:

// From:
import { JSONPath } from 'jsonpath-plus';

// To:
import { JSONPath } from '@upbound/utils';

TypeScript Can't Find Types

1. Verify the library has a .d.ts file in this package
2. Restart your TypeScript server
3. Run yarn install from monorepo root

Finding the CommonJS Build

Check the library's package.json for:

• "main" field (usually points to CJS)
• "exports" field with "require" condition
• Look in dist/ or lib/ folders for .cjs, .js (without type: module)

Common patterns:

• dist/index.cjs
• dist/index-node-cjs.cjs
• lib/index.js
• cjs/index.js

Best Practices

1. One file per library - Keep implementations separate
2. Include fallback logic - Handle hoisted node_modules
3. Document the CJS path - Make it easy to update versions
4. Test in Jest - Ensure the re-export works
5. Update the table - Keep documentation current