{"id":15505932,"url":"https://github.com/ethanblake4/flutter_eval","last_synced_at":"2025-04-05T13:08:50.693Z","repository":{"id":59255797,"uuid":"356780474","full_name":"ethanblake4/flutter_eval","owner":"ethanblake4","description":"Code push for Flutter, powered by dart_eval","archived":false,"fork":false,"pushed_at":"2024-07-06T05:45:02.000Z","size":858,"stargazers_count":322,"open_issues_count":25,"forks_count":39,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-29T12:07:52.994Z","etag":null,"topics":["bytecode","compiler","dart","flutter"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/flutter_eval","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethanblake4.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-11T06:00:59.000Z","updated_at":"2025-03-12T04:35:33.000Z","dependencies_parsed_at":"2023-10-01T21:22:07.856Z","dependency_job_id":"0ea070a2-0c97-4764-808d-d89f320e643d","html_url":"https://github.com/ethanblake4/flutter_eval","commit_stats":{"total_commits":62,"total_committers":7,"mean_commits":8.857142857142858,"dds":"0.19354838709677424","last_synced_commit":"8456274f0c01c5eb0fae75ae614e588133a78262"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanblake4%2Fflutter_eval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanblake4%2Fflutter_eval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanblake4%2Fflutter_eval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethanblake4%2Fflutter_eval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethanblake4","download_url":"https://codeload.github.com/ethanblake4/flutter_eval/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytecode","compiler","dart","flutter"],"created_at":"2024-10-02T09:24:58.000Z","updated_at":"2025-04-05T13:08:50.660Z","avatar_url":"https://github.com/ethanblake4.png","language":"Dart","readme":"[![Star on Github](https://img.shields.io/github/stars/ethanblake4/flutter_eval?logo=github\u0026colorB=orange\u0026label=stars)](https://github.com/ethanblake4/flutter_eval)\n[![License: BSD-3](https://img.shields.io/badge/license-BSD3-purple.svg)](https://opensource.org/licenses/BSD-3-Clause)\n[![Web example](https://img.shields.io/badge/web-example-blue.svg)](https://ethanblake.xyz/evalpad)\n\n`flutter_eval` is a Flutter bridge library for [dart_eval](https://pub.dev/packages/dart_eval), \nand a solution enabling code-push, dynamic widgets, and runtime evaluation of Flutter code.\nIt can be used to enable hot-swapping parts of your app with an over-the-air update, dynamically loading UI from a server, or evaluating code based on user input such as in a calculator. \nflutter_eval supports all platforms including iOS and is built on dart_eval's\ncustom bytecode interpreter, making it very fast.\n\n| dart_eval    | [![pub package](https://img.shields.io/pub/v/dart_eval.svg?label=dart_eval\u0026color=teal)](https://pub.dev/packages/dart_eval)          |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |\n| flutter_eval | [![pub package](https://img.shields.io/pub/v/flutter_eval.svg?label=flutter_eval\u0026color=blue)](https://pub.dev/packages/flutter_eval) |\n| eval_annotation | [![pub package](https://img.shields.io/pub/v/eval_annotation.svg?label=eval_annotation\u0026color=orange)](https://pub.dev/packages/eval_annotation) |\n\nFor a live example, check out [EvalPad](https://ethanblake.xyz/evalpad).\n\nNote: While flutter_eval supports most Flutter and Dart features, it does not support all of them. Existing code may need modification to work. You can\nsee a list of supported widgets and classes [here](#supported-widgets-and-classes)\nand a list of supported Dart features on the [dart_eval Pub page](https://pub.dev/packages/dart_eval/#language-feature-support-table).\n\nSee: [Quickstart for code push](#quickstart-for-code-push) | [Quickstart for dynamic execution and server-driven UI](#quickstart-for-dynamic-execution-and-server-driven-ui) | [Supported widgets and classes](#supported-widgets-and-classes)\n\n## Quickstart for code push\n\nRun `flutter pub add flutter_eval` to install the package.\n\nAt the root of your app, add a HotSwapLoader widget with a URI \npointing to where you'll host the update file:\n\n```dart\nclass MyApp extends StatelessWidget {\n\n  @override\n  Widget build(BuildContext context) {\n    return HotSwapLoader(\n        uri: 'https://mysite.com/app_update/version_xxx.evc',\n        child: MaterialApp(\n          ...\n```\n\nThen, add HotSwap widgets throughout your app at every location\nyou'd like to be able to dynamically update:\n\n```dart\nclass MyHomePage extends StatelessWidget {\n  \n  @override\n  Widget build(BuildContext context) {\n    return HotSwap(\n      id: '#myHomePage',\n      args: [$BuildContext.wrap(context)],\n      childBuilder: (context) =\u003e Scaffold(\n        ...\n```\n\nNext, create a new Flutter package using `flutter create --template=package`. \nThis can be nested inside your app's folder or located separately. Name it \nsomething appropriate, such as my_app_hot_update. We'll refer to this\nas the \"hot update package\" from now on.\n\nHead over to the flutter_eval [Releases page](https://github.com/ethanblake4/flutter_eval/releases)\nand find the release corresponding to the version of flutter_eval you are using. Under **Assets**,\ndownload `flutter_eval.json`. (Or [click here](https://github.com/ethanblake4/flutter_eval/releases/latest/download/flutter_eval.json) to download the latest version.)\n\nIn the root of the hot update package, create a folder called `.dart_eval` and\na subfolder `bindings`. Place the downloaded `flutter_eval.json` file inside of \nthis folder.\n\nYour project structure should look like this:\n```\n├── .dart_eval\n│   └── bindings\n│       └── flutter_eval.json.\n├── pubspec.yaml\n└── lib\n    └── hot_update.dart\n```\n\nAt the root of the hot update package, run `flutter pub add eval_annotation`.\n\nDelete all the code from main.dart, including the main() function. \nFor every HotSwap widget you'd like to update (you can update all, \nor just a few, or just one), create a top-level function with the \n@RuntimeOverride annotation referencing its ID:\n\n```dart\n@RuntimeOverride('#myHomePage')\nWidget myHomePageUpdate(BuildContext context) {\n  return Scaffold(\n    ...\n  )\n}\n```\nFinally, we'll need to install the dart_eval CLI:\n\n```bash\ndart pub global activate dart_eval\n```\n\nAfter installing, you can run:\n```bash\ndart_eval compile -o version_xxx.evc\n```\n\nIf the steps were performed correctly, you should see the following in the console output:\n\n`Found binding file: .dart_eval\\bindings\\flutter_eval.json`\n\nas well as\n\n`Compiled $x characters Dart to $y bytes EVC in $z ms: version_xxx.evc`\n\nThe resulting `version_xxx.evc` file will be in the root of the project and\nyou can now upload it to the previously referenced server path. \n\nIf you run the app, you should see the contents of the HotSwap widgets\nreplaced with the contents of their corresponding @RuntimeOverride functions.\n\nHotSwap widgets can optionally specify a strategy to use when loading/applying updates, \none of _immediate_, _cache_, or _cacheApplyOnRestart_. By default, HotSwapLoader\nuses immediate in debug/profile mode and cacheApplyOnRestart in release mode. You\ncan also specify a placeholder widget to display when loading from the cache via\nthe _loading_ parameter.\n\nFor a complete example of code push, see \n[examples/code_push_app](https://github.com/ethanblake4/flutter_eval/tree/master/examples/code_push_app)\nand its subfolder [hot_update](https://github.com/ethanblake4/flutter_eval/tree/master/examples/code_push_app/hot_update).\n\n## Quickstart for dynamic execution and server-driven UI\n\nTo create a simple dynamic stateless widget, add and modify the following inside a \nbuild() method or as a child parameter:\n\n```dart\nreturn EvalWidget(packages: {\n  'example': {\n    'main.dart': '''\n    import 'package:flutter/material.dart';\n    \n    class MyWidget extends StatelessWidget {\n      MyWidget(this.name);\n      final String name;\n\n      @override\n      Widget build(BuildContext context) {\n        return Padding(\n          padding: EdgeInsets.all(5.0),\n          child: Column(children: [\n              Container(\n                color: Colors.red,\n                child: Text('The name is ' + name)\n              )\n            ],\n            mainAxisAlignment: MainAxisAlignment.center,\n            crossAxisAlignment: CrossAxisAlignment.center,\n          )\n        );\n      }\n    }''',\n    assetPath: 'assets/program.evc',\n    library: 'package:example/main.dart',\n    function: 'MyWidget.',\n    args: [$String('Example name')]\n  }\n});\n```\n\nInternally, `EvalWidget` automatically switches between two modes:\n- When running in **debug mode**, it will dynamically compile the provided \n  Dart code into EVC bytecode, save it to a file determined by `assetPath`,\n  and run it in the dart_eval VM. This is slower, but allows you to make\n  changes when developing with a hot restart.\n- When running in **release mode**, it will instead ignore the provided Dart\n  code and attempt to load EVC bytecode, either from the assetPath or from\n  a custom file, asset, or network URL specified by the optional `uri`\n  parameter. This enables high performance at runtime, while still letting\n  you dynamically swap out code by providing a new EVC file or URL.\n\nIf you are loading EVC bytecode from the network, you can specify an optional\nloading widget with the `loading` parameter.\n\nflutter_eval includes two other helper Widgets for different use cases:\n- `CompilerWidget` will *always* compile and run provided Dart code,\n   and never attempt to load EVC bytecode, regardless of whether the app \n   is in debug or release mode. This is especially suitable for apps like\n   calculators, 'learn to code' platforms, or user-scriptable automation\n   tools. Though this mode is slower, the dart_eval compiler is very\n   fast and will generally compile simple Flutter programs in ~0.1 second.\n- `RuntimeWidget` will *always* load EVC bytecode and does not provide a\n   parameter to specify Dart code. This is recommended if you're compiling\n   with the CLI - see below.\n   \n### Calling functions and passing arguments\n\nTo instantiate a class with its default constructor, append a '.' to the class name.\n\nWhen calling a dart_eval function or constructor externally, you must specify *all* \narguments - even optional and named ones - in order, using null to indicate the absence\nof an argument (whereas `$null()` indicates a null value).\n\nE.g. for the following class:\n\n```dart\nclass MyApp extends SomeWidget {\n  MyApp(this.name, {Key? key, Color? color}) : super(key: key, color: color);\n\n  final String name;\n}\n```\n\nYou could instantiate it in `RuntimeWidget` with:\n\n```dart\nreturn RuntimeWidget(\n  uri: Uri.parse('asset:assets/program.evc'),\n  library: 'package:example/main.dart',\n  function: 'MyApp.',\n  args: [$String('Jessica'), null, null]\n);\n```\n\nYou can also pass callbacks with `$Function`.\n\n## Security and permissions\n\nflutter_eval inherits dart_eval's \n[secure execution model](https://pub.dev/packages/dart_eval#security-and-permissions)\nwhich restricts access to the filesystem, network, and other sensitive APIs by default.\nflutter_eval extends this with security controls for MethodChannel and related APIs.\nTo allow access to a MethodChannel, add a `MethodChannelPermission` to the `permissions` parameter of `EvalWidget`, `CompilerWidget`, or `RuntimeWidget`.\n\n## Supported widgets and classes\n\nCurrently supported widgets and classes include:\n- Widget, StatelessWidget, StatefulWidget, State;\n- ChangeNotifier, Key, BuildContext;\n- WidgetsApp, Container, Column, Row, Center;\n- Alignment, Align, AspectRatio, Baseline;\n- Radius, BorderRadius, BorderRadiusGeometry, Clip, ClipRRect;\n- SizedBox, FittedBox, FractionallySizedBox, ColoredBox;\n- Stack, Positioned, StackFit;\n- Padding, EdgeInsetsGeometry, EdgeInsets, Axis, Size;\n- Offset, Velocity;\n- MainAxisAlignment, MainAxisSize, CrossAxisAlignment;\n- AlignmentGeometry, Alignment, Constraints, BoxConstraints;\n- Color,  ColorSwatch, Colors, FontWeight, FontStyle;\n- MaterialApp, MaterialColor, MaterialAccentColor;\n- Theme, ThemeData, TextTheme, Directionality;\n- Decoration, BoxDecoration, BoxBorder, Border, BorderSide;\n- IconData, Icons, Icon;\n- Curve, Curves, SawTooth, Interval, Threshold, Cubic;\n- Text, TextStyle, TextEditingController, TextField;\n- TextDirection, VerticalDirection, TextBaseline\n- Scaffold, ScaffoldMessenger, AppBar, SnackBar, FloatingActionButton;\n- InkWell, TextButton, ElevatedButton, IconButton;\n- Card, Drawer, ListView, ListTile, Spacer;\n- Image, ImageProvider, NetworkImage, MemoryImage;\n- Navigator, NavigatorState, Builder;\n- PointerDeviceKind, HitTestBehavior;\n- GestureDetector, TapDownDetails, TapUpDetails;\n- LongPressStartDetails, LongPressMoveUpdateDetails, LongPressEndDetails;\n- DragStartDetails, DragUpdateDetails, DragEndDetails, DragDownDetails;\n\nNote that some of these have only partial support.\n\n## App size measurements\n\n| App              | Initial APK size | with EvalWidget     |\n| ---------------- | ---------------- | ------------------- |\n| Flutter Counter  | 16.5 MB          | 17.9 MB (+ 1.4 MB)  |\n| Flutter Gallery  | 110.2 MB         | 110.6 MB (+ 0.4 MB) |\n\nThese measurements were last updated for flutter_eval v0.4.5. They do not include the size of an EVC\nbytecode file, which is typically 20-100KB (or 6-30KB zipped) and may be downloaded post-install\nrather than packaged with the app.\n\nNote these measurements are for a generated combined APK which includes multiple architectures.\nAPKs downloaded from the Play Store will be about half as large in both APK size and increase.\n\n## Advanced usage\n\nUsing flutter_eval requires two main steps: compiling the Dart code to EVC bytecode, and executing\nthe resultant EVC bytecode. Since you cannot currently expect all existing Flutter/Dart code to \nwork with flutter_eval, it's recommended to run both steps in your app during development:\n\n```dart\nclass ExampleState extends State\u003cExample\u003e {\n  late Runtime runtime;\n\n  @override\n  void initState() {\n    super.initState();\n\n    final compiler = Compiler();\n    compiler.addPlugin(flutterEvalPlugin);\n\n    final program = compiler.compile({\n      'example': { 'main.dart': '''\n          import 'package:flutter/material.dart';\n          \n          class HomePage extends StatelessWidget {\n            HomePage(this.number);\n            final int number;\n            \n            @override\n            Widget build(BuildContext context) {\n              return Padding(\n                padding: EdgeInsets.all(2.3 * 5),\n                child: Container(\n                  color: Colors.green,\n                  child: Text('Current amount: ' + number.toString())\n                )\n              );\n            }\n          }\n        ''' }\n    });\n\n    final file = File('out.evc');\n    file.writeAsBytesSync(program.write());\n    print('Wrote out.evc to: ' + file.absolute.uri);\n    \n    runtime = Runtime.ofProgram(program);\n    runtime.addPlugin(flutterEvalPlugin);\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    return (runtime.executeLib('package:example/main.dart', 'HomePage.', [$int(55)]) as $Value).$value;\n  }\n}\n```\n\nWith this setup you can quickly see any errors in the code. However, we're also continuously writing\nthe EVC bytecode to a file `out.evc`. This file contains the compiled bytecode created from the Dart\nsource and when releasing an app to production, it's all you need. Running the compiler in your production\napp at runtime, while possible, is strongly discouraged as it is much slower than simply using the \ngenerated output. EVC bytecode is platform-agnostic, so you can generate the `out.evc` file using \nFlutter Desktop and use it in a Flutter Mobile app with no issues.\n\nAfter it's generated, you can use it in an app like so:\n\n```dart\nimport 'package:flutter/services.dart' show rootBundle;\n\nclass ExampleState extends State\u003cExample\u003e {\n  Runtime? runtime;\n\n  @override\n  void initState() {\n    super.initState();\n    \n    rootBundle.load('assets/out.evc').then((bytecode) =\u003e setState(() {\n      runtime = Runtime(ByteData.sublistView(bytecode));\n      runtime.addPlugin(flutterEvalPlugin);\n    }));\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    if (runtime == null) return CircularProgressIndicator();\n    return (runtime.executeLib('package:example/main.dart', 'HomePage.', [$int(55)]) as $Value).$value;\n  }\n}\n```\n\nYou can also load `out.evc` over the network. In a large app, you may want to consider gzip compression\nas EVC bytecode compresses very well (around a 4x ratio).\n","funding_links":[],"categories":["Dart"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanblake4%2Fflutter_eval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethanblake4%2Fflutter_eval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethanblake4%2Fflutter_eval/lists"}