How fluttercandies/fjs works
Project type and purpose
• This is not a typical frontend/backend app but a cross-platform Flutter plugin (“fjs”) that embeds a JavaScript engine into Flutter via Rust and QuickJS.
• It provides a high-performance JS runtime with Dart bindings, built-time tools (cargokit) to compile native libraries for Android, iOS, Linux, macOS, and Windows, and example apps demonstrating usage.
File structure
• Top-level components:
• android, ios, linux, macos, windows — platform-specific plugin code and build configurations
• lib — Dart library exposing JsEngine, JsValue, and API
• libfjs — Rust crate containing the QuickJS binding and engine implementation
• cargokit — CLI/build tool (Dart) to orchestrate cross-platform Rust builds (build_tool, cmake, gradle, pods scripts)
• example — sample Flutter app that integrates the plugin on each platform
• test_driver — integration test harness
• Patterns:
• Plugin pattern: Flutter → Dart API → FFI → native library
• Build orchestration: cargokit’s build_tool drives rustup, cargo, CMake, Gradle, Pod builds
• Key configs:
• pubspec.yaml (plugin meta, Dart deps)
• flutter_rust_bridge.yaml (codegen for FFI bindings)
• build.gradle, CMakeLists.txt, Podspecs (platform packaging)
• analysis_options.yaml, build.yaml (lint and build rules)
README for additional insights
• Confirms architecture: Dart initializes LibFjs, creates JsAsyncRuntime/JsAsyncContext, spins up QuickJS under the hood.
• Describes bridge_call mechanism, built-in modules, memory management, and module loading.
• Emphasizes cross-platform support and advanced use cases.
a. Main components
1. Flutter Application (example or end user app)
2. Dart FJS API Layer (lib/fjs.dart, lib/src)
3. FFI Bridge (generated via flutter_rust_bridge)
4. Native Engine Library (libfjs compiled into .so/.dylib/.dll)
5. QuickJS Core (bundled within libfjs; garbage collector, module loader)
6. Cargokit Build Tool (Dart build_tool + cmake/gradle/pod scripts)
7. Platform-specific package managers (Gradle for Android, CocoaPods for iOS/macOS, CMake for Linux/Windows)
b. Relationships and interactions
• The Flutter app imports the Dart FJS API.
• Dart API calls into the native engine via FFI.
• The native engine uses QuickJS to parse/evaluate JS, manages memory and modules.
• Bridge calls from JS invoke callbacks in Dart via FFI.
• Cargokit orchestrates compilation of libfjs for each target before publishing.
c. Architectural patterns and design principles
• Plugin architecture with clear separation: UI → framework → native.
• FFI boundary with generated bindings for type safety.
• Single-source Rust crate reused across all platforms.
• Build automation tooling (cargokit) to avoid manual multi-platform builds.
d. Key technologies, frameworks, libraries
• Flutter/Dart, flutter_rust_bridge, QuickJS, Rust, Cargo, CMake, Gradle, CocoaPods, shell scripts.
Final advice
• Be highly detailed: capture both runtime invocation and build-time orchestration.