Flutter JS Plus

A unified JavaScript runtime for Flutter that works seamlessly across all platforms: Web, Android, iOS, Windows, macOS, and Linux.

Features

• ✅ Cross-platform: Single API works on all Flutter platforms
• ✅ Web Support: Uses browser's native JavaScript engine via dart:js_interop
• ✅ Native Performance: QuickJS on Android/Windows/Linux, JavaScriptCore on iOS/macOS
• ✅ Promise Support: Automatically converts JavaScript Promises to Dart Futures (on web)
• ✅ Type Conversion: Automatic conversion between JavaScript and Dart types
• ✅ Error Handling: Proper exception handling with stack traces
• ✅ Zero Configuration: Works out of the box on all platforms

Installation

Add flutter_js_pro to your pubspec.yaml:

dependencies:
  flutter_js_pro: ^0.0.1

Platform-Specific Setup

Android

Set minimum SDK version to 21 or higher in android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21
    }
}

iOS/macOS

No additional setup required. Uses native JavaScriptCore.

Web

No additional setup required. Uses browser's JavaScript engine.

Windows/Linux

No additional setup required. Uses QuickJS.

Quick Start

Basic Usage

import 'package:flutter_js_pro/js_plus.dart';

void main() async {
  // Create a JavaScript runtime
  final js = JsPlus();
  
  try {
    // Evaluate simple expressions
    final result = await js.evaluate('1 + 2');
    print(result); // 3
    
    // Evaluate with variables
    await js.evaluate('const x = 10;');
    final sum = await js.evaluate('x + 5');
    print(sum); // 15
    
    // Work with objects
    final obj = await js.evaluate('''
      ({ name: "Flutter", version: 3.0 })
    ''');
    print(obj); // {name: Flutter, version: 3.0}
    
    // Work with arrays
    final arr = await js.evaluate('[1, 2, 3, 4, 5]');
    print(arr); // [1, 2, 3, 4, 5]
    
  } catch (e) {
    if (e is JsEvaluationException) {
      print('JavaScript error: ${e.message}');
    }
  } finally {
    // Always dispose when done
    js.dispose();
  }
}

Working with Promises (Web)

On web, JavaScript Promises are automatically converted to Dart Futures:

final js = JsPlus();

// Promise automatically becomes a Future
final result = await js.evaluate('''
  Promise.resolve(42)
''');
print(result); // 42

// Async operations
final data = await js.evaluate('''
  fetch('https://api.example.com/data')
    .then(response => response.json())
''');
print(data); // The JSON data

js.dispose();

Error Handling

final js = JsPlus();

try {
  await js.evaluate('throw new Error("Something went wrong")');
} on JsEvaluationException catch (e) {
  print('Error: ${e.message}');
  print('Stack: ${e.stackTrace}');
} finally {
  js.dispose();
}

Type Conversion

The runtime automatically converts JavaScript types to Dart types:

final js = JsPlus();

// Numbers
final num = await js.evaluate('42');
print(num is int); // true

// Strings
final str = await js.evaluate('"Hello"');
print(str is String); // true

// Booleans
final bool = await js.evaluate('true');
print(bool is bool); // true

// Objects → Maps
final obj = await js.evaluate('{a: 1, b: 2}');
print(obj is Map); // true
print(obj['a']); // 1

// Arrays → Lists
final arr = await js.evaluate('[1, 2, 3]');
print(arr is List); // true
print(arr[0]); // 1

js.dispose();

For advanced type conversion, use the JsTypeConversion utilities:

import 'package:flutter_js_pro/js_plus.dart';

final js = JsPlus();
final jsArray = await js.evaluate('[1, 2, 3]');
final list = JsTypeConversion.jsArrayToList(jsArray);
print(list); // [1, 2, 3]

final jsObj = await js.evaluate('{a: 1}');
final map = JsTypeConversion.jsObjectToMap(jsObj);
print(map); // {a: 1}

js.dispose();

Platform-Specific Behavior

Web

On Flutter Web, flutter_js_pro uses the browser's native JavaScript engine through dart:js_interop. This means:

• Full access to browser APIs (document, window, localStorage, etc.)
• DOM manipulation capabilities
• Native Promise support (automatically converted to Futures)
• No additional JavaScript engine bundled (uses browser's engine)

Example - DOM Manipulation (Web only):

final js = JsPlus();

// Create HTML elements
await js.evaluate('''
  const div = document.createElement('div');
  div.id = 'my-element';
  div.innerHTML = 'Hello from JavaScript!';
  document.body.appendChild(div);
''');

// Modify elements
await js.evaluate('''
  const element = document.getElementById('my-element');
  element.style.color = 'blue';
''');

js.dispose();

Native Platforms

On native platforms (Android, iOS, Windows, macOS, Linux), flutter_js_pro uses:

• Android: QuickJS (default) or JavaScriptCore (if forced)
• iOS/macOS: JavaScriptCore (native to Apple platforms)
• Windows/Linux: QuickJS

Native Configuration:

// Use JavaScriptCore on Android instead of QuickJS
final js = JsPlus(
  forceJavascriptCoreOnAndroid: true,
);

// Configure stack size for QuickJS
final js = JsPlus(
  extraArgs: {'stackSize': 2 * 1024 * 1024}, // 2MB
);

js.dispose();

Advanced Usage

Sharing Data Between Evaluations

final js = JsPlus();

// Set a variable
await js.evaluate('const myVar = "Hello";');

// Use it in another evaluation
final result = await js.evaluate('myVar + " World"');
print(result); // "Hello World"

js.dispose();

Complex JavaScript Code

final js = JsPlus();

final result = await js.evaluate('''
  (function() {
    function factorial(n) {
      return n <= 1 ? 1 : n * factorial(n - 1);
    }
    return factorial(5);
  })()
''');
print(result); // 120

js.dispose();

API Reference

JsPlus

Main class for JavaScript evaluation.

Constructor

JsPlus({
  bool forceJavascriptCoreOnAndroid = false,
  Map<String, dynamic>? extraArgs,
})

• forceJavascriptCoreOnAndroid: Use JavaScriptCore instead of QuickJS on Android
• extraArgs: Additional arguments for native runtime (e.g., {'stackSize': 1024 * 1024})

Methods

• Future<dynamic> evaluate(String code): Evaluate JavaScript code and return the result
• void dispose(): Dispose of the runtime and free resources

JsEvaluationException

Exception thrown when JavaScript evaluation fails.

• String message: Error message
• String? stackTrace: JavaScript stack trace (if available)

JsTypeConversion

Utility class for type conversion between JavaScript and Dart.

• List<dynamic>? jsArrayToList(dynamic value): Convert JS array to Dart List
• Map<String, dynamic>? jsObjectToMap(dynamic value): Convert JS object to Dart Map
• String listToJsArray(List<dynamic> list): Convert Dart List to JS array string
• String mapToJsObject(Map<String, dynamic> map): Convert Dart Map to JS object string

Limitations

Web

• Uses eval() internally, which may be blocked by Content Security Policy (CSP) in some environments
• JavaScript code runs in the global scope (be careful with variable pollution)
• Some browser APIs may not be available depending on the context

Native

• QuickJS has some limitations compared to full JavaScript engines (see QuickJS documentation)
• JavaScriptCore on iOS/macOS is the full engine, but has different performance characteristics than QuickJS

Safety Notes

Using eval() on Web

This package uses JavaScript's eval() function on web platforms. While this is necessary for dynamic code evaluation, be aware that:

• Security: Only evaluate code from trusted sources
• CSP: Some Content Security Policies may block eval()
• Performance: eval() can be slower than pre-compiled code

Memory Management

Always call dispose() when you're done with a JsPlus instance, especially on native platforms:

final js = JsPlus();
try {
  // Use js...
} finally {
  js.dispose(); // Important!
}

Examples

See the example/ directory for complete examples including:

• Basic JavaScript evaluation
• Promise handling
• Type conversion
• Error handling
• DOM manipulation (web)

Migration from Legacy API

If you're using the legacy getJavascriptRuntime() API, you can migrate to the new JsPlus API:

Before:

final runtime = getJavascriptRuntime();
final result = runtime.evaluate('1 + 2');
print(result.stringResult);
runtime.dispose();

After:

final js = JsPlus();
final result = await js.evaluate('1 + 2');
print(result); // Direct value, no need for .stringResult
js.dispose();

The legacy API is still available for backward compatibility.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source under the MIT license.

Acknowledgments

• QuickJS by Fabrice Bellard and Charlie Gordon
• JavaScriptCore bindings from flutter_jscore
• QuickJS FFI bindings inspired by flutter_qjs