{"id":19225394,"url":"https://github.com/wasmcloud/wasmcloud-js","last_synced_at":"2025-04-21T00:32:12.958Z","repository":{"id":43470441,"uuid":"397730075","full_name":"wasmCloud/wasmcloud-js","owner":"wasmCloud","description":"wasmCloud JavaScript Host Runtime","archived":false,"fork":false,"pushed_at":"2025-03-31T07:45:08.000Z","size":844,"stargazers_count":43,"open_issues_count":17,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T08:30:04.559Z","etag":null,"topics":["javascript","webassembly","webassembly-runtime"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wasmCloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-08-18T20:42:31.000Z","updated_at":"2024-09-23T07:02:38.000Z","dependencies_parsed_at":"2023-01-30T15:15:42.255Z","dependency_job_id":"a6b43fa8-0d8b-4bd8-a47c-5add5591a16d","html_url":"https://github.com/wasmCloud/wasmcloud-js","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wasmCloud%2Fwasmcloud-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wasmCloud%2Fwasmcloud-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wasmCloud%2Fwasmcloud-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wasmCloud%2Fwasmcloud-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wasmCloud","download_url":"https://codeload.github.com/wasmCloud/wasmcloud-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249980357,"owners_count":21355413,"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":["javascript","webassembly","webassembly-runtime"],"created_at":"2024-11-09T15:14:47.030Z","updated_at":"2025-04-21T00:32:12.667Z","avatar_url":"https://github.com/wasmCloud.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e This host is **experimental** and does not implement all features or security settings. As a result, this host should not be used in production. For deploying wasmCloud to production, use the [primary host runtime](https://github.com/wasmCloud/wasmCloud/tree/main/crates/host).\n\n# wasmCloud Host in JavaScript/Browser\n\nThis is the JavaScript implementation of the wasmCloud host for the browser (NodeJS support in progress). The library runs a host inside a web browser/application that connects to a remote lattice via NATS and can run wasmCloud actors in the browser. The host will automatically listen for actor start/stop from NATS and will initialize the actor using `wapcJS`. Any invocations will be handled by the browser actor and returned to the requesting host via NATS. Users can pass callbacks to handle invocation and event data.\n\n## Demonstration Video\n\nIn this demonstration video we will demonstration the following:\n\n* Load an HTTP Server capability into a wasmCloud Host running on a machine\n* Load an the wasmcloud-js host into a web browser\n* Load an 'echo' actor into the web browser\n* **seamlessly** bind the actor to the capability provider through Lattice\n* Access the webserver, which in turn delivers the request to the actor, processes it, and returns it to the requestion client via the capability\n* Unload the actor\n\nhttps://user-images.githubusercontent.com/1530656/130013412-b9a9daa6-fc71-424b-814c-2ca400926794.mp4\n\n\n\n## Prerequisities\n\n* NATS with WebSockets enabled\n\n* wasmCloud lattice (OTP Version)\n\n* (OPTIONAL) Docker Registry with CORS configured\n\n    * If launching actors from remote registries in the browser host, CORS must be configured on the registry server\n\n## Development Prerequisities\n\n* NodeJS, npm \n\n* rust, cargo, wasm-pack \n\n    * Used to port the rust versions of wascap, nkeys to JS\n\n\n## Installation\n\n```sh\n$ npm install @wasmcloud/wasmcloud-js\n```\n\n## Usage\n\nMore examples can be found in the [examples](examples/) directory, including sample `webpack` and `esbuild` configurations \n\n**Browser**\n\n```html\n\u003cscript src=\"https://unpkg.com/@wasmcloud/wasmcloud-js@\u003cVERSION\u003e/dist/wasmcloud.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  (async () =\u003e {\n    // Start the host passing the name, registry tls enabled, a list of nats ws/wss hosts or the natsConnection object, and an optional host heartbeat interval (default is 30 seconds)\n    const host = await wasmcloudjs.startHost(\"default\", false, [\"ws://localhost:4222\"], 30000);\n    // The host will automatically listen for actors start \u0026 stop messages, to manually listen for these messages the following methods are exposed\n    // only call these methods if your host is not listening for actor start/stop\n    // actor invocations are automatically returned to the host. if a user wants to handle the data, they can pass a map of callbacks using the actor ref/wasm file name as the key with a callback(data, result) function. The data contains the invocation data and the result contains the invocation result\n    // (async() =\u003e {\n    //     await host.listenLaunchActor(\n    //         {\n    //             \"localhost:5000/echo:0.2.2\": (data, result) =\u003e console.log(data.operation, result);\n    //         }\n    //     );\n    //     await host.listenStopActor();\n    // })();\n    // To launch an actor manually from the library from a registry, optionally a callback can be passed to handle the invocation results. In addition, a hostCall callback and writer can be passed.\n    // The hostCallback format is as follows:\n    // ```\n    // (binding, namespace, operation, payload) =\u003e {\n    //    return Uint8Array(payload);\n    // })\n    // ```\n    await host.launchActor(\"registry.com/actor:0.1.1\", (data) =\u003e { /* handle data */})\n    // Launch an actor with the hostCallback\n    await host.launchActor(\"registry.com/actor:0.1.1\", (data) =\u003e { /* handle data */}, (binding, namespace, operation, payload) =\u003e {\n        // decode payload via messagepack\n        // const decoded = decode(payload);\n        return new Uint8Array(payload);\n    })\n    // To launch an actrom manually from local disk (note the .wasm is required)\n    await host.launchActor(\"./actor.wasm\");\n    // To listen for events, you can call the subscribeToEvents and pass an optional callback to handle the event data\n    await host.subscribeToEvents((eventData) =\u003e console.log(eventData, eventData.source));\n    // To unsubscribe, call the unsubscribeEvents\n    await host.unsubscribeEvents();\n    // To start \u0026 stop the heartbeat events\n    await host.startHeartbeat();\n    await host.stopHeartbeat();\n    // The host will automatically connect to nats on start. to connect/reconnect to nats\n    await host.connectNATS();\n    // To close/drain all connections from nats, call the disconnectNATS() method\n    await host.disconnectNATS();\n    // Stop the host\n    await host.stopHost();\n    // Restart the host (this only needs to be called if the host is stopped, it is automatically called on the constructor)\n    await host.startHost();\n  })();\n\u003c/script\u003e\n```\n\n**With a bundler**\n\nThere are some caveats to using with a bundler: \n\n* The module contains `.wasm` files that need to be present alongside the final build output. Using `webpack-copy-plugin` (or `fs.copyFile` with other bundlers) can solve this issue.\n\n* If using with `create-react-app`, the webpack config will need to be ejected via `npm run eject` OR an npm library like `react-app-rewired` can handle the config injection.\n\n```javascript\n// as esm -- this will grant you access to the types/params\nimport { startHost } from '@wasmcloud/wasmcloud-js';\n// as cjs\n// const wasmcloudjs = require('@wasmcloud/wasmcloud-js);\n\nasync function cjsHost() {\n    const host = await wasmcloudjs.startHost('default', false, ['ws://localhost:4222'])\n    console.log(host);\n}\n\nasync function esmHost() {\n    const host = await startHost('default', false, ['ws://localhost:4222'])\n    console.log(host);\n}\n\ncjsHost();\nesmHost();\n```\n\n```javascript\n// webpack config, add this to the plugin section\nplugins: [\n    new CopyPlugin({\n        patterns: [\n            {\n                from: 'node_modules/@wasmcloud/wasmcloud-js/dist/wasmcloud-rs-js/pkg/*.wasm',\n                to: '[name].wasm'\n            }\n        ]\n    }),\n]\n```\n\n**Node** \n\n*IN PROGRESS* - NodeJS does not support WebSockets natively (required by nats.ws)\n\n## Contributing\n\n### Running tests\n\n```sh\n$ npm run test\n```\n\n### Building\n\n```sh\n$ npm run build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwasmcloud%2Fwasmcloud-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwasmcloud%2Fwasmcloud-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwasmcloud%2Fwasmcloud-js/lists"}