Merge pull request #686 from ethereum/web-worker-example

Add web worker example in README
ethereum · May 8, 2023 · f9c411e · f9c411e
2 parents c572d36 + bd7a86f
commit f9c411e
Showing 1 changed file with 31 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -318,64 +318,47 @@ var output = translate.prettyPrintLegacyAssemblyJSON(assemblyJSON, sourceCode)
 
 ## Browser Usage
 
-Add the version of `solc` you want to use into `index.html`:
+Compilation is generally a long-running and resource intensive task that cannot reasonably be performed in the main thread of the browser.
+Some browsers even dissallow synchronous compilation on the main thread if the module is larger than 4KB.
+Thus, the only supported way to use `solc` in a web browser is through a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers).
 
-```html
-<script
-  type="text/javascript"
-  src="https://binaries.soliditylang.org/bin/{{ SOLC_VERSION }}.js"
-  integrity="sha256-{{ BASE64_ENCODED_HASH_OF_SOLC_VERSION  }}"
-  crossorigin="anonymous"
-></script>
-```
+### Loading solc with web workers
 
-This will load `solc` into the global variable `window.Module`.
-Alternatively, use `soljson-latest.js` as `{{ SOLC_VERSION }}.js` in the code snippet above to load the latest version.
+Web Workers allow you to run javascript in the background in the browser, letting the browser's main thread free to do whatever it needs to do.
+Please, see the minimal example of how to use `solc` with web workers below or check out this [repository](https://github.com/r0qs/solcjs-webworker-example) for a full demo.
 
-It is recommended that you check the integrity of the resource being fetched before using it in your application.
-For that, you can use the [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) feature.
-Adding SRI configuration to your HTML script tag ensures that the resource will only be loaded by the browser if the cryptographic hashes match.
+* index.html
+```html
+<!DOCTYPE html>
+<html>
 
-You can generate the SRI hash yourself based on the base64-encoded version of the sha256 hash of the release.
-For example, after downloading version `v0.8.16+commit.07a7930e`, run:
-```bash
-node -e "console.log(crypto.createHash('sha256').update(fs.readFileSync('./soljson-v0.8.16+commit.07a7930e.js', 'utf8')).digest('base64'))"
-```
-```
-J7KCDvk4BaZcdreUWklDJYLTBv0XoomFcJpR5kA2d8I=
-```
+<head>
+	<meta charset="utf-8" />
+</head>
 
-And update your `index.html` to:
-```html
-<script
-  type="text/javascript"
-  src="https://binaries.soliditylang.org/bin/soljson-v0.8.16+commit.07a7930e.js"
-  integrity="sha256-J7KCDvk4BaZcdreUWklDJYLTBv0XoomFcJpR5kA2d8I="
-  crossorigin="anonymous"
-></script>
-```
+<body>
+	<script>
+		var worker = new Worker('./dist/bundle.js');
+		worker.addEventListener('message', function (e) {
+			console.log(e.data.version)
+		}, false);
 
-Then use this inside JavaScript as:
+		worker.postMessage({})
+	</script>
+</body>
 
-```javascript
-var wrapper = require('solc/wrapper');
-var solc = wrapper(window.Module);
+</html>
 ```
 
-Or in ES6 syntax:
-
+* worker.js:
 ```javascript
+importScripts('https://binaries.soliditylang.org/bin/soljson-v0.8.19+commit.7dd6d404.js')
 import wrapper from 'solc/wrapper';
-const solc = wrapper(window.Module);
-```
 
-Alternatively, to iterate the releases, one can load `list.js` from `solc-bin`:
-
-```html
-<script
-  type="text/javascript"
-  src="https://binaries.soliditylang.org/bin/list.js"
-></script>
+self.addEventListener('message', () => {
+	const compiler = wrapper(self.Module)
+	self.postMessage({
+		version: compiler.version()
+	})
+}, false)
 ```
-
-This will result in two global variables, `window.soljsonReleases` listing all releases and `window.soljsonSources` listing all nightly builds and releases.