mirror of
https://github.com/flutter/samples.git
synced 2025-11-08 22:09:06 +00:00
Publish web_embedding (#1777)
## Pre-launch Checklist - [x] I read the [Flutter Style Guide] _recently_, and have followed its advice. - [x] I signed the [CLA]. - [x] I read the [Contributors Guide]. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-devrel channel on [Discord]. <!-- Links --> [Flutter Style Guide]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo [CLA]: https://cla.developers.google.com/ [Discord]: https://github.com/flutter/flutter/wiki/Chat [Contributors Guide]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md Co-authored-by: Mark Thompson <2554588+MarkTechson@users.noreply.github.com> Co-authored-by: David Iglesias <ditman@gmail.com> Co-authored-by: Mark Thompson <2554588+MarkTechson@users.noreply.github.com> Co-authored-by: David Iglesias <ditman@gmail.com>
This commit is contained in:
Brett Morgan
GitHub
178
web_embedding/ng-flutter/README.md
Normal file
178
web_embedding/ng-flutter/README.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# ng-flutter
|
||||
|
||||
This Angular project is a simple example of how Angular and Flutter
|
||||
web apps could be integrated, and have them interop.
|
||||
|
||||
## Points of Interest
|
||||
|
||||
### Angular
|
||||
|
||||
This repository is a quite standard Angular app. The following changes were made
|
||||
to be able to use (and interop) with a Flutter web application:
|
||||
|
||||
* `package.json` has a custom `prebuild` script that builds the
|
||||
Flutter web app, so Angular can find it later.
|
||||
* `flutter.js` is added as a `"scripts"` entry in `angular.json`.
|
||||
Angular takes care of minimizing and injecting it as any other script.
|
||||
* The rest of the flutter app `flutter/build/web/` is registered
|
||||
as an `"assets"` entry in `angular.json`, and moved to `/flutter`.
|
||||
* The `ng-flutter` component takes care of embedding Flutter web, and yielding
|
||||
control to Angular through an `appLoaded` `EventEmitter`. The object yielded
|
||||
by this emitter is a state controller exposed by flutter via a JS custom
|
||||
event!
|
||||
|
||||
### Flutter
|
||||
|
||||
The embedded Flutter application lives in the `flutter` directory of this repo.
|
||||
That application is a standard web app, that doesn't need to be aware that it's
|
||||
going to be embedded in another framework.
|
||||
|
||||
* Flutter uses new `@staticInterop` methods to allow certain Dart functions to
|
||||
be called from JavaScript.
|
||||
* Look at how `createDartExport` and `broadcastAppEvent` work together to make
|
||||
the `_state` controller of the Flutter app available to Angular!
|
||||
|
||||
## How to build the app
|
||||
|
||||
### Requirements
|
||||
|
||||
If you want to build and run this demo on your machine, you'll need
|
||||
a moderately recent version of Angular:
|
||||
|
||||
```console
|
||||
$ ng version
|
||||
|
||||
Angular CLI: 15.2.4
|
||||
Node: 18.13.0
|
||||
Package Manager: npm 9.4.2
|
||||
OS: linux x64
|
||||
```
|
||||
|
||||
And Flutter:
|
||||
|
||||
```
|
||||
$ flutter --version
|
||||
|
||||
Flutter 3.10.0-12.0.pre.38 • channel master
|
||||
Framework • revision 1a51dc2131 (8 days ago) • 2023-04-24 12:25:21 -0700
|
||||
Engine • revision 5fbde6c0fc
|
||||
Tools • Dart 3.1.0 (build 3.1.0-35.0.dev) • DevTools 2.23.1
|
||||
```
|
||||
|
||||
**Ensure `npm`, `ng` and `flutter` are present in your `$PATH`.**
|
||||
|
||||
### Building the app
|
||||
|
||||
This repository is a moderately standard Angular app. It integrates
|
||||
Flutter web by making it part of the Angular `assets`.
|
||||
|
||||
In order to build this app, first fetch its `npm` dependencies:
|
||||
|
||||
```console
|
||||
$ npm install
|
||||
|
||||
npm WARN deprecated @npmcli/move-file@2.0.1: This functionality has been moved to @npmcli/fs
|
||||
|
||||
added 963 packages, and audited 964 packages in 17s
|
||||
|
||||
93 packages are looking for funding
|
||||
run `npm fund` for details
|
||||
|
||||
found 0 vulnerabilities
|
||||
```
|
||||
|
||||
Then run the `build` script. It'll take care of building Flutter
|
||||
automatically:
|
||||
|
||||
```console
|
||||
$ npm run build
|
||||
|
||||
> ng-flutter@0.0.0 prebuild
|
||||
|
||||
... Flutter web build output ...
|
||||
|
||||
Compiling lib/main.dart for the Web...
|
||||
|
||||
> ng-flutter@0.0.0 build
|
||||
> ng build
|
||||
|
||||
... Angular build output ...
|
||||
|
||||
✔ Browser application bundle generation complete.
|
||||
✔ Copying assets complete.
|
||||
✔ Index html generation complete.
|
||||
```
|
||||
|
||||
### Local Angular development
|
||||
|
||||
Once you've reached this point, you should be able to work with
|
||||
your Angular application normally, for example to run a local web
|
||||
server:
|
||||
|
||||
```console
|
||||
$ npm run start
|
||||
|
||||
> ng-flutter@0.0.0 start
|
||||
> ng serve
|
||||
|
||||
✔ Browser application bundle generation complete.
|
||||
|
||||
Initial Chunk Files | Names | Raw Size
|
||||
vendor.js | vendor | 4.38 MB |
|
||||
|
||||
... Angular build output...
|
||||
|
||||
** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **
|
||||
|
||||
|
||||
✔ Compiled successfully.
|
||||
```
|
||||
|
||||
Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of its Angular source files.
|
||||
|
||||
### Local Flutter web development
|
||||
|
||||
The Flutter app lives inside the `flutter` directory, and can be
|
||||
developed independently. Just do any changes on Flutter web as you'd
|
||||
normally do. It even includes a small `web/index.html` so you can see
|
||||
changes to your app without running the whole Angular setup.
|
||||
|
||||
> **Note**
|
||||
> For now, Angular does _not_ auto-detect changes to your Flutter web
|
||||
app, so once you're happy with your Flutter web app, make sure to
|
||||
call `npm run build` so everything rebuilds and gets placed into its
|
||||
correct location.
|
||||
|
||||
### Deploying the app
|
||||
|
||||
After `npm run build`, you should have a deployable Angular + Flutter
|
||||
web app in the `dist` directory of this Angular project.
|
||||
|
||||
Your built app can can be deployed anywhere, but do check
|
||||
[Firebase hosting](https://firebase.google.com/docs/hosting) for a
|
||||
super-easy deployment experience!
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Flutter
|
||||
|
||||
Ensure your flutter app is properly rebuilt after any changes.
|
||||
|
||||
* Run `npm run build` to re-build the Flutter app.
|
||||
|
||||
If you encounter error messages like:
|
||||
|
||||
```
|
||||
Error: Can't resolve 'flutter/build/web/flutter.js' in '/my/checkout/of/ng-flutter'
|
||||
```
|
||||
|
||||
You definitely need to run `npm run build`!
|
||||
|
||||
## Reach out to the team(s)!
|
||||
|
||||
Have you had any problem not covered in this README? Do you want
|
||||
to see other embedding examples?
|
||||
|
||||
Let us know by [creating an issue](https://github.com/flutter/samples/issues/new) or opening a new pull request.
|
||||
|
||||
Thanks!
|
||||
Reference in New Issue
Block a user