| id | language-features |
|---|---|
| title | Language Features |
Hermes is a JavaScript engine optimized for fast start-up. It executes JavaScript using a combination of ahead-of-time (AOT) compilation to bytecode and runtime interpretation.
Hermes aims to support the latest ECMAScript specification, prioritizing language features over new library functions. However, some features are intentionally excluded or de-prioritized if they conflict with Hermes' design goals of performance, low memory use, and efficient AOT compilation.
Hermes provides broad support for ECMAScript features, including:
-
Full support for ES2015 (ES6) Language Features:
letandconstdeclarations (Temporal Dead Zone checks and per-iteration bindings are supported but off by default, see "Known Deviations")- Arrow Functions (
=>) - Classes (Basic syntax:
class,extends,staticmethods,super,constructor) - Enhanced Object Literals (shorthand properties, computed names, methods)
- Template Literals (tagged and untagged)
- Destructuring Assignment (arrays and objects, including rest
...) - Default, Rest, and Spread (
...) operators - Iterators and Generators (
Symbol.iterator,for..of,function*) - Symbols (primitive type,
Symbol(), well-known symbols) - And all other ES2015 language constructs (unless listed below).
-
Key Post-ES2015 Language Features:
async/await(ES2017)- Object Rest/Spread Properties (ES2018)
- RegExp Named Capture Groups (ES2018)
- Optional Chaining (
?.) (ES2020) - Nullish Coalescing (
??) (ES2020) BigInt(ES2020)- Class Fields & Static Blocks (ES2022):
- Public and Private Instance Fields (property declarations and initializers, e.g.,
myField = 1;,#privateField = 2;) - Public and Private Static Fields (e.g.,
static staticField = 3;,static #privateStatic = 4;) - Static Initialization Blocks (
static {}) - Private Methods, Private Static Methods and Private Accessors
- Private Brand Checks (
#x in obj)
- Public and Private Instance Fields (property declarations and initializers, e.g.,
- RegExp Match Indices (
/dflag) (ES2022) - Logical Assignment Operators (
??=,||=,&&=) (ES2021) for await...ofandSymbol.asyncIterator(ES2018)- Async Generators (ES2018), behind the
-Xasync-generatorscompiler flag. Off by default; without it the compiler reports "async generators are unsupported".
-
Key Library Features:
- ES2015 standard built-ins (
Promise,Set,Map,WeakSet,WeakMap, TypedArrays,Reflect,Proxy, updated methods onArray,String,Object, etc.) - Extended
PromiseAPI (see "Known Deviations" for the limits ofSymbol.speciesand microtask timing):Promise.prototype.finally(ES2018)Promise.allSettled(ES2020)Promise.any(ES2021)Promise.withResolvers(ES2024)Promise.try(ES2025)
Symbol.prototype.description(ES2019)WeakRefandFinalizationRegistry(ES2021).WeakRef,WeakMapandWeakSetalso accept symbols as targets (ES2023).Object.hasOwn(ES2022),Array.prototype.at/findLast(ES2022),Array.prototype.toSorted/toReversed/with/toSpliced(ES2023)String.prototype.isWellFormed/toWellFormed(ES2024)- Iterator Helpers (ES2025):
Iteratorwithmap,filter,take,drop,flatMap,reduce,toArray,forEach,some,every,find, plusIterator.fromandIterator.concat - Array grouping (ES2024):
Object.groupByandMap.groupBy Setmethods (ES2025):union,intersection,difference,symmetricDifference,isSubsetOf,isSupersetOf,isDisjointFromRegExp.escape(ES2025),Math.sumPrecise(ES2026),Error.isError(ES2026)ArrayBuffer.prototype.detached(ES2024),Float16Array(ES2025),Uint8Array.fromBase64(ES2026),Map.prototype.getOrInsert/WeakMap.prototype.getOrInsert(ES2026)TextEncoderandTextDecoder(WHATWG, not ECMAScript)- Note: Support for the latest standard library features may lag behind language feature support.
- ES2015 standard built-ins (
Features Hermes intends to support in the future. Active development or implementation hasn't started or completed yet.
withStatements: Support is planned. See "Intentionally Excluded" for the current state.- ES Modules (
import/export): A module system is planned. See "Intentionally Excluded" for the current state. - Other Standard Library Features: Newer library additions are considered but may be lower priority. Currently absent: RegExp
/v(unicodeSets) flag,ArrayBuffer.prototype.transferand resizable buffers,SharedArrayBufferandAtomics,Array.fromAsync, explicit resource management (using,Symbol.dispose,Symbol.asyncDispose),Temporal.
These features are not supported, often due to incompatibility with Hermes' AOT compilation strategy, performance concerns, limited utility, or complexity costs.
- Local
eval():eval()cannot access or modify local variables in the surrounding lexical scope (neither in strict nor non-strict mode). This restriction is fundamental to Hermes' AOT compilation and optimization strategy; supporting localevalwould severely degrade performance across the engine. Use ofevalis strongly discouraged. Every direct call toeval()produces the compiler warning "Direct call to eval(), but lexical scope is not supported". The precise behavior:- Reading a local from inside
evalthrowsReferenceError, in both strict and loose mode. - Writing a local from inside
evalthrowsReferenceErrorin strict mode. In loose mode it fails silently: the local is left unchanged and a global of that name is created or overwritten instead. evalsees the global scope, but onlyvarand function declarations and properties of the global object. Top-levellet,constandclassdeclarations of the running script are not visible to it.
- Reading a local from inside
withStatements: Not supported yet. When source is compiled ahead of time this is a compile-time error ("with statement is not supported") which fails the build, not a runtime exception. When the VM compiles source lazily (-lazy), it surfaces as a thrownSyntaxErrorthe first time the enclosing function is called, and the same happens when it is reached througheval()ornew Function().withhinders performance and optimization and is disallowed in strict mode. This is a current limitation rather than a permanent exclusion: support is planned.- ES Modules (
import/export): Hermes does not currently provide a runtime ES module loader. The parser accepts the full module syntax and builds the corresponding AST, but semantic analysis rejects it ("'import' statement requires module mode"), and dynamicimport()is not supported. An earlier implementation was removed because the React Native ecosystem relies on bundlers such as Metro, which provide their own module systems. An ES module system is planned. Symbol.species: Not supported. The well-known symbol itself does not exist (Symbol.speciesisundefined), and no built-in exposes an@@speciesaccessor. Hermes does not commit to supporting the pattern, due to its complexity and performance overhead for an AOT-focused engine. Note that the consequences reach beyond@@speciesoverrides: subclass propagation is missing outright, soclass Sub extends Array {}followed bynew Sub().map(f)yields a plainArrayrather than aSub. The same applies to TypedArray methods such assubarray.Promiseis the exception, because its polyfill dispatches onthis.constructor; see "Known Deviations".- Non-Strict
argumentsObject Behavior: See "Known Deviations" for details on how Hermes deviates from the spec regarding parameter syncing, assignment, andvarshadowing for theargumentsobject in non-strict mode. These deviations simplify implementation and improve performance. IntlAPI: Not supported. A partial implementation exists for Android, which calls into Java platform APIs, and for Apple platforms, which use Foundation. It is not built by default (HERMES_ENABLE_INTLisOFF), so in a default buildIntlisundefined. Even where it is enabled, coverage is incomplete:RelativeTimeFormat,PluralRulesandformatRangeare missing or partial, and using them can throw. The underlying platform APIs are inadequate, there is no public ICU4C on mobile, and bundling ICU4C would cost tens of megabytes. Meta does not useIntlinternally and cannot invest in it, so the implementation is expected to move toextensions/contribor a separate community-maintained repository. Use a polyfill such as FormatJS instead, accepting its start-up cost. See discussion #1211.Symbol.unscopables: Not supported.Symbol.unscopablesandArray.prototype[Symbol.unscopables]are bothundefined. Its main purpose is tied towith, which is also unsupported, but the absence is observable to any code that reflects on the built-in prototypes.
Specific behaviors where Hermes differs from the ECMAScript specification or has notable implementation characteristics. These deviations are often deliberate choices prioritizing performance, simplicity, or compatibility with Hermes' AOT compilation model, especially concerning rarely used or complex legacy features. SpecIncompat.md discusses some of them in more detail.
-
Temporal Dead Zone (TDZ) Checks: Reading a
letorconstbinding before its initializer has run should throw aReferenceError. Hermes implements these checks, but they are off by default, because they impose a cost on every access to a lexical variable. By default such a read producesundefinedinstead of throwing. Pass-Xenable-tdztohermesorshermesto enable them:function f() { var get = function () { return v; }; get(); // undefined by default; ReferenceError with -Xenable-tdz let v = 1; }
With the flag on, a violation the compiler can prove statically becomes a compile-time error rather than a runtime throw. Class declarations follow the same rule: by default a class binding reads as
undefinedbefore its declaration, sotypeof Cyields"undefined"andnew C()throws aTypeError(not aReferenceError). -
Block Scoping of Captured Bindings: A
let,constorclassbinding declared in a block or a loop head should be created anew each time the block is entered or the loop iterates. By default Hermes creates it once per function call instead. Name resolution and shadowing are unaffected; the difference shows only when closures capture the binding, because closures created in different iterations then share one variable. Pass-Xes6-block-scopingtohermesorshermesto get spec behavior:var fns = []; for (let i = 0; i < 3; i++) fns.push(() => i); fns.map(f => f()); // [3, 3, 3] by default; [0, 1, 2] with -Xes6-block-scoping
-
argumentsObject Behavior (Non-Strict Mode): Hermes simplifiesargumentsobject handling in non-strict ("loose") mode compared to the specification:- No Parameter Syncing: Assigning to indices of the
argumentsobject does not dynamically update the corresponding named parameters, and vice-versa (e.g., settingarguments[0] = xdoes not change the value of the first named parameter). This matches strict mode behavior. (Motivation: High cost and complexity for a rare feature). - Assignment Forbidden: Direct assignment to the
argumentsidentifier itself (e.g.,arguments = ...;) is disallowed, unlike in spec-compliant loose mode. (Motivation: Rare, complex, little practical benefit). var argumentsShadows: Declaringvar arguments;inside a function creates a new variable that shadows the arguments object (likelet arguments;) rather than aliasing it. (Motivation: Extremely rare, no known practical uses).- These
argumentsdeviations are considered very low priority to align with the spec due to the reasons mentioned.
- No Parameter Syncing: Assigning to indices of the
-
Function Declaration Hoisting (Non-Strict Mode Blocks): Most of the scoped function promotion semantics are implemented, but some corner cases in non-strict mode differ from the spec: a function declared in an inner block can overwrite one declared in an outer block at the function scope level.
function g() { { function f() { return 1; } { function f() { return 2; } } } print(f()); // spec requires 1, Hermes prints 2 }
(Motivation: Affects rare edge cases primarily in non-strict mode; other major engines behave the same way in quick testing. Low priority to fix).
-
Function.prototype.toString(): Because functions are compiled ahead of time, this method does not normally return the original JavaScript source. It returns a synthesized declaration whose body is a placeholder and whose parameters are renamed:function foo(a, b) {} // "function foo(a0, a1) { [bytecode] }" async function bar() {} // "async function bar() { [bytecode] }" Math.max // "function max() { [native code] }"
The result is the same whether the function was compiled from source or loaded from precompiled bytecode. A function can opt out with a source visibility directive in its body:
'show source'makestoString()return the real source text, while'hide source'and'sensitive'make it report[native code]. -
PromiseImplementation: Promises are implemented using an internally bundled JavaScript polyfill rather than as a native intrinsic. It is compiled to bytecode by default, or compiled natively when the engine is built withHERMESVM_INTERNAL_JAVASCRIPT_NATIVE=ON. The polyfill covers the full ES2025 surface (then,catch,finally,all,allSettled,any,race,resolve,reject,try,withResolvers,Symbol.toStringTag), but the following corners differ from the spec:- No
Symbol.speciesdispatch. Per spec, the prototype methodsPromise.prototype.then,Promise.prototype.catch, andPromise.prototype.finallyuseSpeciesConstructor(this, %Promise%)to determine the constructor of the chained promise. The polyfill substitutesthis.constructor(and takes the built-inPromisedirectly on the common-casethis.constructor === Promisefast path), so a subclass that overridesSymbol.specieswill not see its override applied (consistent with the engine-wide "Symbol.species not supported" stance noted above). The static methods (all,allSettled,any,race,resolve,reject) usethisviaNewPromiseCapabilityper spec —Symbol.speciesis not involved there. - Extra microtask hop on subclass
.then. Whenthis.constructor !== Promise, the polyfill bridges the user's reaction to the subclass capability through an intermediate corePromise, costing one additional microtask hop compared to spec'sPerformPromiseThen, which attaches the reaction directly to the capability. The fast path (this.constructor === Promise) is unaffected. Promise.all1-microtask fast path (non-spec, default). When an input is an already-fulfilled corePromise, the polyfill synchronously invokes the resolve element and collapses the spec-mandatedPerformPromiseAllstep 8.e microtask hop. This is a deliberate performance default; the spec-compliant.then-only dispatch is enabled under the--test262runtime flag.- Microtask timing in
await. Hermes'async functionmachinery lowers to a generator wrapped with the polyfill'sthen, and a few test262 tick-counting tests (e.g.await-non-promise-thenable, thefor-await-of/ticks-with-…-constructor-lookupfamily) observe a different microtask sequence than spec because the polyfill does one fewer.constructorread on each await hop. - See the polyfill source.
- No