@swmansion/popcorn 0.4.0-next.6 → 0.4.0-next.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -77
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,11 +1,7 @@
|
|
|
1
|
-
# Popcorn
|
|
1
|
+
# Popcorn JavaScript
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
Start with the
|
|
7
|
-
[versioned Popcorn guide](https://popcorn.hexdocs.pm/0.4.0-next.6/introduction.html).
|
|
8
|
-
It includes a complete Mix and Vite tutorial.
|
|
3
|
+
JavaScript API and bundler plugins for running Elixir and Erlang applications
|
|
4
|
+
in the browser with Popcorn's WebAssembly runtime.
|
|
9
5
|
|
|
10
6
|
## Install
|
|
11
7
|
|
|
@@ -13,97 +9,53 @@ It includes a complete Mix and Vite tutorial.
|
|
|
13
9
|
npm install @swmansion/popcorn@next
|
|
14
10
|
```
|
|
15
11
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
standard-library code.
|
|
12
|
+
Use the matching Elixir package version. See the
|
|
13
|
+
[Elixir package README](https://github.com/software-mansion/popcorn/blob/main/popcorn/elixir/README.md)
|
|
14
|
+
for application setup, toolchain requirements, and packaging configuration.
|
|
20
15
|
|
|
21
|
-
|
|
22
|
-
The packager checks host OTP compatibility against the selected runtime's manifest.
|
|
16
|
+
## Bundler setup
|
|
23
17
|
|
|
24
|
-
|
|
18
|
+
For Vite:
|
|
25
19
|
|
|
26
20
|
```ts
|
|
27
21
|
import { defineConfig } from "vite";
|
|
28
22
|
import { popcorn } from "@swmansion/popcorn/vite";
|
|
29
23
|
|
|
30
24
|
export default defineConfig({
|
|
31
|
-
plugins: [
|
|
32
|
-
popcorn({
|
|
33
|
-
rootDir: "../",
|
|
34
|
-
}),
|
|
35
|
-
],
|
|
25
|
+
plugins: [popcorn({ rootDir: "../" })],
|
|
36
26
|
});
|
|
37
27
|
```
|
|
38
28
|
|
|
39
|
-
Set `rootDir` to the Mix project directory. The
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
```elixir
|
|
43
|
-
import Config
|
|
44
|
-
|
|
45
|
-
config :popcorn,
|
|
46
|
-
extra_apps: [:eex],
|
|
47
|
-
treeshake: [preserved_apps: [:eex]]
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Set `app: :other_app` to select another OTP application, or `app: nil` to
|
|
51
|
-
package the base runtime without starting an application. Cooking settings
|
|
52
|
-
belong exclusively to Elixir config; the JS plugins accept only `rootDir`.
|
|
53
|
-
See `mix help popcorn.cook` for all settings.
|
|
54
|
-
|
|
55
|
-
The npm package contains two variants:
|
|
56
|
-
|
|
57
|
-
- `core`: without native crypto support.
|
|
58
|
-
- `crypto`: includes native crypto and ASN.1 support for applications that depend on crypto, public_key, or ssl.
|
|
59
|
-
|
|
60
|
-
The plugin emits only the selected variant. The browser does not download both.
|
|
61
|
-
Both variants share one JavaScript API and one Hex package.
|
|
62
|
-
The cook task selects `crypto` when the application's dependencies or configured `extra_apps` require it; otherwise it selects `core`.
|
|
63
|
-
Set `runtime_variant: :core` or `runtime_variant: :crypto` in Elixir config to override this choice.
|
|
64
|
-
An explicit `"core"` selection produces a build error if the application requires crypto.
|
|
29
|
+
Set `rootDir` to the Mix project directory. The plugin compiles and packages
|
|
30
|
+
the application and runtime assets.
|
|
65
31
|
|
|
66
|
-
Rollup and esbuild plugins
|
|
67
|
-
Use ESM output
|
|
32
|
+
Rollup and esbuild plugins use the same option, imported from
|
|
33
|
+
`@swmansion/popcorn/rollup` and `@swmansion/popcorn/esbuild`. Use ESM output.
|
|
68
34
|
|
|
69
|
-
##
|
|
35
|
+
## JavaScript API
|
|
70
36
|
|
|
71
37
|
```ts
|
|
72
38
|
import { Popcorn } from "@swmansion/popcorn";
|
|
73
39
|
|
|
74
40
|
const vm = await Popcorn.init();
|
|
41
|
+
|
|
42
|
+
vm.onEvent((event) => console.log(event));
|
|
43
|
+
const count = await vm.call("counter", ["add", 1]);
|
|
44
|
+
console.log(count);
|
|
45
|
+
|
|
75
46
|
// Stop the runtime when the application no longer needs it.
|
|
76
47
|
vm.deinit();
|
|
77
48
|
```
|
|
78
49
|
|
|
79
|
-
`Popcorn.init()` waits for the
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
Methods throw or reject on failure. Only `send`, `call`, and `cast` also have
|
|
84
|
-
`trySend`, `tryCall`, and `tryCast` variants that return `Result` objects.
|
|
85
|
-
|
|
86
|
-
Each VM starts with 64 MiB of Wasm linear memory and can grow to 256 MiB on
|
|
87
|
-
phones/tablets or 2 GiB on desktop. Device detection uses the browser's user
|
|
88
|
-
agent and touch support. Configure the limits with
|
|
89
|
-
`Popcorn.init({ beam: { maxMemory: { mobile: "256M", desktop: "2G" } } })`.
|
|
90
|
-
Omit `maxMemory` to keep these defaults, or override either key separately.
|
|
91
|
-
Only `M` and `G` suffixes are supported; they mean MiB and GiB.
|
|
92
|
-
The limit must be a multiple of 64 KiB between 64 MiB and 2 GiB; JavaScript and
|
|
93
|
-
filesystem memory are additional.
|
|
94
|
-
|
|
95
|
-
## Serve in production
|
|
96
|
-
|
|
97
|
-
Serve over HTTPS or localhost. Set these headers on the application and runtime responses:
|
|
98
|
-
|
|
99
|
-
```text
|
|
100
|
-
Cross-Origin-Opener-Policy: same-origin
|
|
101
|
-
Cross-Origin-Embedder-Policy: require-corp
|
|
102
|
-
```
|
|
50
|
+
`Popcorn.init()` waits for the application's supervision tree to start.
|
|
51
|
+
This example assumes the application starts a GenServer registered as `:counter`
|
|
52
|
+
that handles `["add", amount]` requests.
|
|
103
53
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
54
|
+
Use `send()` for process messages, `call()` and `cast()` for GenServer requests,
|
|
55
|
+
and `onEvent()` for events from Elixir. Methods throw or reject on failure;
|
|
56
|
+
`trySend()`, `tryCall()`, and `tryCast()` return result objects instead.
|
|
107
57
|
|
|
108
|
-
|
|
109
|
-
|
|
58
|
+
See the [JavaScript API reference](https://hexdocs.pm/popcorn/JSLib.Popcorn.html)
|
|
59
|
+
for options, terminal IO, and memory limits. Follow the
|
|
60
|
+
[deployment guide](https://hexdocs.pm/popcorn/deployment.html)
|
|
61
|
+
for required response headers and Content Security Policy settings.
|