Package selection guidance compiled from public package information, community data, and project usage.
jsf is a high-performance JavaScript engine integrated directly into Flutter, enabling seamless execution of JavaScript code across multiple platforms. Designed for efficiency and ease of use, it allows developers to run JavaScript within Flutter apps without external dependencies. The engine supports full JavaScript interoperability, making it ideal for embedding scripts, executing dynamic logic, or integrating with existing JavaScript libraries. It's particularly useful in scenarios requiring real-time script evaluation or cross-platform compatibility. With support for Android, iOS, Web, macOS, Windows, and Linux, jsf ensures consistent behavior across environments.
Use cases
Running dynamic JavaScript code in Flutter apps
Integrating legacy JavaScript libraries
Enabling scriptable UI components
Real-time code evaluation
Cross-platform JavaScript execution
Key features
High performance JavaScript engine
Native Flutter integration
Multi-platform support (Android, iOS, Web, macOS, Windows, Linux)
Seamless JavaScript interop
Lightweight and fast startup
Suitable for
Developers needing JavaScript runtime in Flutter
Apps requiring dynamic scripting
Projects using existing JS libraries
Cross-platform applications
Performance-sensitive environments
Considerations
Requires careful handling of JavaScript security risks
May increase app size slightly
Limited debugging tools compared to native JS environments
Not suitable for heavy server-side JavaScript workloads
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
Owned JsValue handles must be disposed. Handles received inside registerHandleFunction are borrowed and only valid for the callback duration. Call duplicate() if you need to keep one.
Dart Calls JavaScript
final add = js.evalValue('(function(a, b) { return a + b; })');
try {
final result = js.callValue(add, [20, 22]);
try {
print(result.toDart()); // 42
} finally {
result.dispose();
}
} finally {
add.dispose();
}
Use registerFunction() to expose a Dart function on the JavaScript global
object. JavaScript calls it like a normal function. Arguments are converted to
Dart values, and the return value is converted back to JavaScript:
js.registerFunction('dartSum', (args) {
return args.cast<num>().reduce((a, b) => a + b);
});
print(js.eval('dartSum(4, 5, 6)')); // 15
Callbacks can receive multiple arguments and return convertible values such as
Map, List, BigInt, and DateTime:
js.registerFunction('receiveMessage', (args) {
final name = args[0] asString;
final payload = args[1] asMap;
return {
'ok': true,
'message': '$name:${payload['count']}',
};
});
print(js.eval('receiveMessage("counter", {count: 3}).message')); // counter:3
Callbacks may return Future; JavaScript receives a Promise, so JS can use
await or .then() directly:
js.registerFunction('loadUser', (args) async {
return {'id': 1, 'name': 'Ada'};
});
final user = await js.evalAsync('loadUser().then((user) => user.name)');
With JavaScript async/await:
final name = await js.evalAsync('''
(async () => {
const user = await loadUser();
return user.name;
})()
''');
print(name); // Ada
registerFunction() converts JavaScript objects into Dart snapshots. Use
registerHandleFunction() when you need to preserve JavaScript object identity
or work with functions, class instances, circular objects, or host objects. It
passes arguments to Dart as JsValue handles:
js.registerHandleFunction('readModel', (args) {
final model = args.first;
final count = model.getPropertyValue('count');
try {
return count.toDart();
} finally {
count.dispose();
}
});
Arguments received by registerHandleFunction() are borrowed handles and are
only valid for the callback duration. Call duplicate() if you need to keep one
outside the callback, and dispose the owned handle when finished.
Promise
When JavaScript returns a Promise, evalAsync() gives you the resolved Dart
value:
final value = await js.evalAsync('Promise.resolve({ok: true})');
print(value); // {'ok': true}
evalAsync() is also the normal way to call async function:
final result = await js.evalAsync('''
async function compute() {
const value = await Promise.resolve(21);
return value * 2;
}
compute()
''');
print(result); // 42
Native platforms use the QuickJS module loader. Web includes JSF's registry
loader behind the same Dart API and supports in-memory modules, import maps,
relative resolution, module caching, static import, named/default/namespace
exports, re-exports, and literal dynamic import("module").
evalAsync(..., module: true) and dynamic import() on Web use the browser's
native ES Module/Blob loader, so browser-supported ESM syntax works, including
export * from, export { x } from, export * as ns from, and top-level
await. The in-memory module loader is intended for application scripts and
Flutter asset modules; it does not fetch network module URLs.
A JsRuntime owns one QuickJS runtime and one context.
Use a runtime from the same Dart isolate that created it.
Dispose every runtime with dispose().
Dispose owned JsValue handles when you are done.
Do not use handles after their runtime is disposed.
Disposing a runtime also releases owned JsValue handles still registered under that runtime, but explicit dispose() remains recommended to control memory peaks.
Testing
Integration tests live in example/integration_test:
cd example
flutter drive --driver=integration_test/driver.dart --target=integration_test/js_runtime_test.dart -d macos
The test suite covers primitive conversion, BigInt, object/array conversion, handle calls, Dart callbacks, promise waiting, module loading, exceptions, timeouts, Unicode, typed arrays, circular objects, and multiple runtimes.