pkg/dartpad_worker/README.md - sdk - Git at Google

 # DartPad worker

 This package contains a worker intended to be compiled to wasm and run as a
 _Web Worker_ in the browser by `package:dartpad`. This worker environment has
 an in-memory file-system with DDC, LSP and pub client.

 This package is not intended to be published, instead the resulting binaries
 and assets should be published (e.g., to a CDN).

 ## Architecture
 A dartpad-like experience built with `package:dartpad` consists of 3 components:
  * The _editor_, the main application, built using `package:dartpad`. This is
    where the UI, code editor, file browser, etc lives. You may also think of
    this as the main application that orchestrates everything else.
  * The _worker_, a development environment that runs in a _Web Worker_, launched
    using `package:dartpad`. This hosts an in-memory file-system, where you can
    run a `pub get`, start a language server or compile dart files with DDC. You
    can also think of this as your Dart SDK.
  * The _sandbox_, a sandboxed iframe, where dart files compiled in the _worker_
    can be executed, with support for hot-reload, hot-restart and extraction of
    `console.log` and unhandled exceptions.

 Communication between the components above is entirely async, and happens using
 [JSON-RPC 2.0], though the APIs are encapsulated by `package:dartpad`, so users
 do not have to manage RPC messages themselves. A user of `package:dartpad` gets
 an convinient asynchronous API for talking to the worker and sandbox. But to
 spawn a worker or sandbox, a user of `package:dartpad` must provide:
  * `assetBaseUrl`, the location of binaries and assets created from
    `pkg/dartpad_worker`.
  * `sdkLocation`, the location of the _DartPad SDK_ to use, this includes
    SDK files and runtime DDC modules to be used.

 The `assetBaseUrl` should point to a location hosting the files from
 `out/ReleaseX64/dartpad/` built with
 `./tools/build.py -m release -a x64 dartpad`.
 This includes WASM compiled worker, auxiliary JS files for loading into a
 _Web Worker_, DDC module loader, sandbox communication layer.
 But from the perspective of a user of `package:dartpad`, the `assetBaseUrl`
 should simply point to a collection of files built from the Dart SDK repository.
 The Dart team will publish these files as part of the release process for the
 Dart SDK.

 The `sdkLocation` should point to the location of a _DartPad SDK_.
 A _DartPad SDK_ is a folder that contains the following entrypoints:
  * `sdk.tar`, a bundle of files to be loaded into the in-memory filesystem of
    the worker, and,
  * `sdk.js`, a bundle of DDC modules to be loaded into the sandbox before we
    attempt to run anything.

 A _DartPad SDK_ may contain additional assets and resources referenced from
 `sdk.js` or loaded by the running application.

 As of the moment, `out/ReleaseX64/dartpad/` also contains a `dart/` folder that
 works as _DartPad SDK_ (`sdkLocation`) for a Dart-only environment.
 For a Flutter environment a _DartPad SDK_ can be built using
 `pkg/dartpad_worker/setup_local_flutter.dart`.

 From the perspective of a user of `package:dartpad`, the `sdkLocation` should
 simply point to a collection of files built from the Dart or Flutter SDK
 repository.
 Current thinking is that the Dart team will publish these files as part of the
 release process for the Dart and Flutter SDKs.

 It may be possible that in the future, a default value for `assetBaseUrl` is
 hardcoded into `package:dartpad`, along with `sdkLocation` default values for
 Dart and Flutter SDKs. It's also possible that framework authors building on top
 of the Dart or Flutter SDK, may want to publish their own _DartPad SDK_ with
 pre-compiled DDC modules. Exactly, how to keep such an effort maintainable is
 still TBD.

 [JSON-RPC 2.0]: https://www.jsonrpc.org/specification

 ## Testing
 These tests require the assets be built. Build these locally with:

 ```sh
 ./tools/build.py -m release -a x64 dartpad
 ```

 And run tests locally with `dart test`, see `dart_test.yaml` for details on the
 configuration.

 To run Flutter specific tests you also run:
 ```sh
 dart pkg/dartpad_worker/setup_local_flutter.dart
 ```

 This will only work if your flutter installation has the same dill version as
 your Dart SDK checkout. This is arguably not ideal, and these tests do not run
 in CI.
	# DartPad worker

	This package contains a worker intended to be compiled to wasm and run as a
	_Web Worker_ in the browser by `package:dartpad`. This worker environment has
	an in-memory file-system with DDC, LSP and pub client.

	This package is not intended to be published, instead the resulting binaries
	and assets should be published (e.g., to a CDN).

	## Architecture
	A dartpad-like experience built with `package:dartpad` consists of 3 components:
	* The _editor_, the main application, built using `package:dartpad`. This is
	where the UI, code editor, file browser, etc lives. You may also think of
	this as the main application that orchestrates everything else.
	* The _worker_, a development environment that runs in a _Web Worker_, launched
	using `package:dartpad`. This hosts an in-memory file-system, where you can
	run a `pub get`, start a language server or compile dart files with DDC. You
	can also think of this as your Dart SDK.
	* The _sandbox_, a sandboxed iframe, where dart files compiled in the _worker_
	can be executed, with support for hot-reload, hot-restart and extraction of
	`console.log` and unhandled exceptions.

	Communication between the components above is entirely async, and happens using
	[JSON-RPC 2.0], though the APIs are encapsulated by `package:dartpad`, so users
	do not have to manage RPC messages themselves. A user of `package:dartpad` gets
	an convinient asynchronous API for talking to the worker and sandbox. But to
	spawn a worker or sandbox, a user of `package:dartpad` must provide:
	* `assetBaseUrl`, the location of binaries and assets created from
	`pkg/dartpad_worker`.
	* `sdkLocation`, the location of the _DartPad SDK_ to use, this includes
	SDK files and runtime DDC modules to be used.

	The `assetBaseUrl` should point to a location hosting the files from
	`out/ReleaseX64/dartpad/` built with
	`./tools/build.py -m release -a x64 dartpad`.
	This includes WASM compiled worker, auxiliary JS files for loading into a
	_Web Worker_, DDC module loader, sandbox communication layer.
	But from the perspective of a user of `package:dartpad`, the `assetBaseUrl`
	should simply point to a collection of files built from the Dart SDK repository.
	The Dart team will publish these files as part of the release process for the
	Dart SDK.

	The `sdkLocation` should point to the location of a _DartPad SDK_.
	A _DartPad SDK_ is a folder that contains the following entrypoints:
	* `sdk.tar`, a bundle of files to be loaded into the in-memory filesystem of
	the worker, and,
	* `sdk.js`, a bundle of DDC modules to be loaded into the sandbox before we
	attempt to run anything.

	A _DartPad SDK_ may contain additional assets and resources referenced from
	`sdk.js` or loaded by the running application.

	As of the moment, `out/ReleaseX64/dartpad/` also contains a `dart/` folder that
	works as _DartPad SDK_ (`sdkLocation`) for a Dart-only environment.
	For a Flutter environment a _DartPad SDK_ can be built using
	`pkg/dartpad_worker/setup_local_flutter.dart`.

	From the perspective of a user of `package:dartpad`, the `sdkLocation` should
	simply point to a collection of files built from the Dart or Flutter SDK
	repository.
	Current thinking is that the Dart team will publish these files as part of the
	release process for the Dart and Flutter SDKs.

	It may be possible that in the future, a default value for `assetBaseUrl` is
	hardcoded into `package:dartpad`, along with `sdkLocation` default values for
	Dart and Flutter SDKs. It's also possible that framework authors building on top
	of the Dart or Flutter SDK, may want to publish their own _DartPad SDK_ with
	pre-compiled DDC modules. Exactly, how to keep such an effort maintainable is
	still TBD.

	[JSON-RPC 2.0]: https://www.jsonrpc.org/specification

	## Testing
	These tests require the assets be built. Build these locally with:

	```sh
	./tools/build.py -m release -a x64 dartpad
	```

	And run tests locally with `dart test`, see `dart_test.yaml` for details on the
	configuration.

	To run Flutter specific tests you also run:
	```sh
	dart pkg/dartpad_worker/setup_local_flutter.dart
	```

	This will only work if your flutter installation has the same dill version as
	your Dart SDK checkout. This is arguably not ideal, and these tests do not run
	in CI.