Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jsep
✓ import jsep from 'jsep';
✗ const jsep = require('jsep');
The primary parsing function is the default export. For CommonJS, explicitly access `.default`.
Jsep
✓ import { Jsep } from 'jsep';
✗ import Jsep from 'jsep';
The `Jsep` object provides static methods for parsing and configuration, distinct from the default `jsep` function. This is a named export.
jsep.plugins.register
✓ import jsep from 'jsep';
import ternary from '@jsep-plugin/ternary';
jsep.plugins.register(ternary);
✗ import { Jsep } from 'jsep'; Jsep.plugins.register(myPlugin);
Plugin registration happens on the default `jsep` export. Plugins themselves are often default exports of their respective packages.
jsep.addBinaryOp
✓ import jsep from 'jsep';
jsep.addBinaryOp('^', 10);
✗ import { Jsep } from 'jsep'; Jsep.addBinaryOp('^', 10);
Custom operator methods are available directly on the `jsep` default export (the parsing function) as well as static methods on the `Jsep` named export.
This quickstart demonstrates importing `jsep`, registering an optional plugin (like ternary), adding a custom binary operator, and parsing various JavaScript expressions to observe their Abstract Syntax Tree (AST) output.
import jsep from 'jsep';
import ternary from '@jsep-plugin/ternary';
// Register a built-in plugin (ternary is default but shown for illustration)
jsep.plugins.register(ternary);
// Add a custom operator (e.g., bitwise XOR)
jsep.addBinaryOp('^', 10);
// Parse a simple expression
const simpleAst = jsep('1 + 2 * 3');
console.log('Simple AST:', JSON.stringify(simpleAst, null, 2));
// Parse an expression with a custom operator
const customOpAst = jsep('5 ^ 3');
console.log('Custom Operator AST:', JSON.stringify(customOpAst, null, 2));
// Parse a complex expression with ternary operator
const complexAst = jsep('a > b ? a : b');
console.log('Complex AST (ternary):', JSON.stringify(complexAst, null, 2));
// Demonstrate AST structure for a nullish coalescing operator (introduced in v1.4.0)
const nullishCoalescingAst = jsep('value ?? defaultValue');
console.log('Nullish Coalescing AST:', JSON.stringify(nullishCoalescingAst, null, 2));
Debug
Known issues
gotchajsep is strictly an 'expression parser' and cannot parse full JavaScript statements (e.g., `if`, `for`, `var`). Attempting to parse statements will result in syntax errors.fixEnsure input strings are valid JavaScript expressions. For full JavaScript parsing, consider alternatives like Esprima or Acorn.
affects: >=1.0.0
gotchaMany common JavaScript features (like object literals, arrow functions, `new` expressions, async/await, regex literals) are implemented as separate `@jsep-plugin/*` packages and are not included by default. These plugins must be explicitly installed and registered.fixInstall the relevant `@jsep-plugin/*` packages from npm and register them using `jsep.plugins.register(plugin)` before parsing expressions that use those features.
affects: >=1.0.0
breakingMajor version upgrades (e.g., from v0.x to v1.x) historically introduced breaking changes, particularly in the structure of the generated Abstract Syntax Tree (AST) and the API for developing custom plugins. Always consult the migration guide when upgrading major versions.fixReview the official changelog and migration guides for your specific version upgrade path to understand and adapt to AST structure changes or API modifications. Test thoroughly.
affects: <1.0.0 to >=1.0.0
gotchaWhen defining custom operators, incorrect precedence or associativity can lead to unexpected parsing results. Precedence is numerical (higher = tighter binding); associativity (left-to-right or right-to-left) is crucial for operators like exponentiation.fixCarefully define `precedence` and `rightToLeft` parameters for `addBinaryOp` and `addUnaryOp`. Consult standard JavaScript operator precedence for guidance.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: jsep is not a function
In CommonJS environments, `require('jsep')` returns the module object, not the default parsing function directly. The parsing function is available via `.default`.
fixChange `const jsep = require('jsep');` to `const jsep = require('jsep').default;` SyntaxError: Unexpected token
Attempting to parse a JavaScript statement (e.g., variable declarations, control flow) or an unsupported expression feature (like object literals, arrow functions) without the corresponding plugin registered.
fixEnsure the input is a valid JavaScript expression. If using advanced syntax, verify that the necessary `@jsep-plugin/*` packages are installed and registered via `jsep.plugins.register()`.
TypeError: Cannot read properties of undefined (reading 'register')
Attempting to call `jsep.plugins.register` before `jsep` has been imported, or if `jsep` was imported incorrectly (e.g., `import { Jsep } from 'jsep';` and then trying `Jsep.plugins.register`).
fixEnsure `jsep` is correctly imported as the default export (e.g., `import jsep from 'jsep';` for ESM or `const jsep = require('jsep').default;` for CJS) before attempting to access its `plugins` property. Audit
Dependencies
No dependency data recorded yet.