{"id":13294,"library":"hermes-estree","title":"hermes-estree","description":"hermes-estree provides Flow type definitions for the ESTree-compatible Abstract Syntax Tree (AST) generated by the `hermes-parser` package. The `hermes-parser` itself is a JavaScript parser derived from the Hermes engine, which is primarily optimized for React Native applications. This package is essential for developers building robust tooling, such as linters, code formatters, or advanced code transformers, on top of the Hermes parser's output. It enables type safety when working with the AST within TypeScript or Flow codebases. Currently at version 0.35.0, the package generally maintains a regular release cadence, often aligning with updates to the Hermes engine and its parser components. Its key differentiator is its direct integration with the Hermes ecosystem, ensuring accurate type representations for ASTs produced specifically by the Hermes parser, making it a foundational component for projects leveraging Hermes for source code analysis and manipulation.","status":"active","version":"0.35.0","language":"javascript","source_language":"en","source_url":"git@github.com:facebook/hermes","tags":["javascript"],"install":[{"cmd":"npm install hermes-estree","lang":"bash","label":"npm"},{"cmd":"yarn add hermes-estree","lang":"bash","label":"yarn"},{"cmd":"pnpm add hermes-estree","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package exports only Flow/TypeScript type definitions. Use `import type`.","wrong":"import { Node } from 'hermes-estree';","symbol":"Node","correct":"import type { Node } from 'hermes-estree';"},{"note":"CommonJS `require` should not be used for type imports, as it will result in runtime errors or undefined values.","wrong":"const { Program } = require('hermes-estree');","symbol":"Program","correct":"import type { Program } from 'hermes-estree';"},{"note":"Import multiple specific AST node types as named type imports for precise type checking.","wrong":"import { ExpressionStatement, Identifier } from 'hermes-estree';","symbol":"ExpressionStatement","correct":"import type { ExpressionStatement, Identifier } from 'hermes-estree';"}],"quickstart":{"code":"import { parse } from 'hermes-parser';\nimport type { Program, ExpressionStatement, StringLiteral } from 'hermes-estree';\n\nconst code = `\n  // @flow\n  const message: string = \"Hello, Hermes ESTree!\";\n  console.log(message);\n`;\n\ntry {\n  const ast = parse(code, { flow: 'all', sourceType: 'module' });\n\n  // Type assertion using hermes-estree types\n  const programNode: Program = ast;\n  console.log('Successfully parsed code into AST.');\n  console.log(`AST type: ${programNode.type}`);\n  console.log(`AST body length: ${programNode.body.length}`);\n\n  // Accessing a specific node with type safety\n  const firstStatement = programNode.body[0];\n  if (firstStatement.type === 'VariableDeclaration') {\n    console.log(`First statement is a VariableDeclaration. Declared variable: ${firstStatement.declarations[0].id.name}`);\n  }\n\n  const secondStatement = programNode.body[1];\n  if (secondStatement.type === 'ExpressionStatement') {\n    const exprStmt: ExpressionStatement = secondStatement;\n    if (exprStmt.expression.type === 'CallExpression') {\n        // Example of traversing a CallExpression\n        // No further specific type assertions here for brevity, but they would follow\n        console.log(`Second statement is a CallExpression to: ${(exprStmt.expression.callee as any).object.name}`);\n    }\n  }\n\n} catch (error) {\n  console.error('Parsing failed:', error);\n}\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always 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.","message":"Direct 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.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"For 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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure `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 });`","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always 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.","message":"While `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.","severity":"gotcha","affected_versions":"<=0.4.8 (hermes-parser)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify 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.","cause":"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`.","error":"TypeError: Cannot read properties of undefined (reading 'type')"},{"fix":"If `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.","cause":"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.","error":"'X' cannot be used as a value because it was imported using 'import type'."},{"fix":"Set `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.","cause":"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).","error":"SyntaxError: 'import' and 'export' may only appear with 'sourceType: \"module\"'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}