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.
Node
✓ import type { Node } from 'hermes-estree';
✗ import { Node } from 'hermes-estree';
This package exports only Flow/TypeScript type definitions. Use `import type`.
Program
✓ import type { Program } from 'hermes-estree';
✗ const { Program } = require('hermes-estree');
CommonJS `require` should not be used for type imports, as it will result in runtime errors or undefined values.
ExpressionStatement
✓ import type { ExpressionStatement, Identifier } from 'hermes-estree';
✗ import { ExpressionStatement, Identifier } from 'hermes-estree';
Import multiple specific AST node types as named type imports for precise type checking.
This quickstart demonstrates how to parse a simple Flow-annotated JavaScript code snippet using `hermes-parser` and then apply `hermes-estree` types to the resulting AST for type-safe manipulation and inspection. It showcases importing specific AST node types and asserting the parsed program's structure.
import { parse } from 'hermes-parser';
import type { Program, ExpressionStatement, StringLiteral } from 'hermes-estree';
const code = `
// @flow
const message: string = "Hello, Hermes ESTree!";
console.log(message);
`;
try {
const ast = parse(code, { flow: 'all', sourceType: 'module' });
// Type assertion using hermes-estree types
const programNode: Program = ast;
console.log('Successfully parsed code into AST.');
console.log(`AST type: ${programNode.type}`);
console.log(`AST body length: ${programNode.body.length}`);
// Accessing a specific node with type safety
const firstStatement = programNode.body[0];
if (firstStatement.type === 'VariableDeclaration') {
console.log(`First statement is a VariableDeclaration. Declared variable: ${firstStatement.declarations[0].id.name}`);
}
const secondStatement = programNode.body[1];
if (secondStatement.type === 'ExpressionStatement') {
const exprStmt: ExpressionStatement = secondStatement;
if (exprStmt.expression.type === 'CallExpression') {
// Example of traversing a CallExpression
// No further specific type assertions here for brevity, but they would follow
console.log(`Second statement is a CallExpression to: ${(exprStmt.expression.callee as any).object.name}`);
}
}
} catch (error) {
console.error('Parsing failed:', error);
}
Debug
Known issues
breakingDirect type compatibility between `hermes-estree` and `hermes-parser` versions is critical. Upgrades to `hermes-parser` may introduce breaking changes to the AST structure (e.g., node properties, type names), which would require a corresponding update to `hermes-estree` to maintain type accuracy. Mismatches can lead to type errors in your build or unexpected runtime behavior if type assertions are bypassed.fixAlways align the versions of `hermes-estree` with the `hermes-parser` package you are using. Refer to the `hermes-parser`'s `package.json` for its `hermes-estree` dependency version or check release notes for compatibility.
affects: >=0.1.0
gotchaWhen consuming `hermes-estree` types within a JavaScript project that uses CommonJS `require()`, directly importing types will result in `undefined` values at runtime, as type-only imports are stripped during transpilation. This package provides only types, not runtime values.fixFor TypeScript or Flow projects, always use `import type { ... } from 'hermes-estree';`. If using plain JavaScript, this package is not directly relevant at runtime, only for static analysis tools. affects: >=0.1.0
gotchaThe `hermes-parser` offers an option to output a Babel-compatible AST (`babel: true`) or an ESTree-compatible AST (`babel: false`, default). `hermes-estree` provides types specifically for the *ESTree-compatible* output. If `hermes-parser` is configured to output Babel AST, the types from `hermes-estree` will not accurately reflect the AST structure, leading to type mismatches.fixEnsure `hermes-parser` is invoked with `babel: false` (which is the default behavior) when expecting the AST to conform to `hermes-estree` types. Example: `parse(code, { babel: false, ...options });` affects: >=0.1.0
gotchaWhile `hermes-estree` provides the official type definitions for `hermes-parser`'s output, minor deviations from the broader ESTree specification or specific proposals (e.g., 'Import Assertions') have occurred. For example, `hermes-parser` historically used `attributes` instead of `assertions` for Import Assertions syntax.fixAlways consult the specific `hermes-parser` version's documentation or test the output AST for edge cases, especially when working with newer JavaScript syntax features or when strict adherence to external ESTree proposals is required. Type definitions in `hermes-estree` will reflect the actual parser output.
affects: <=0.4.8 (hermes-parser)
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'type')
Attempting to access properties of an AST node that doesn't conform to the expected type, often due to an incorrect assumption about the AST structure or a version mismatch with `hermes-parser`.
fixVerify the structure of the AST node at the point of the error by logging the node or inspecting the `hermes-parser` output directly. Ensure `hermes-estree` and `hermes-parser` versions are compatible. Use type guards (`if (node.type === '...')`) or exhaustive `switch` statements for robust AST traversal.
'X' cannot be used as a value because it was imported using 'import type'.
You are attempting to use an imported type (`X`) as a JavaScript value at runtime, but `import type` explicitly indicates it's a type-only import.
fixIf `X` is truly only a type (e.g., an interface or type alias), remove any runtime usage of `X`. If `X` is meant to be a runtime value (e.g., an enum, a class, or a constant), ensure it is exported as such from its source module and imported without the `type` keyword (`import { X } from 'module';`). This specific package (`hermes-estree`) contains only types. SyntaxError: 'import' and 'export' may only appear with 'sourceType: "module"'
The `hermes-parser` was invoked with `sourceType: 'script'` (or 'unambiguous' which resolved to 'script') when the code contained ES module syntax (e.g., `import` or `export` statements).
fixSet `sourceType: 'module'` in the `hermes-parser` options when parsing files that contain ES module syntax: `parse(code, { sourceType: 'module' });`. Alternatively, use `sourceType: 'unambiguous'` if you want the parser to attempt to auto-detect. Audit
Dependencies
No dependency data recorded yet.