{"id":13996019,"url":"https://github.com/lightpanda-io/zig-js-runtime","last_synced_at":"2025-04-05T08:03:47.138Z","repository":{"id":239924392,"uuid":"537098314","full_name":"lightpanda-io/zig-js-runtime","owner":"lightpanda-io","description":"Add a JS runtime in your Zig project","archived":false,"fork":false,"pushed_at":"2025-04-01T15:20:09.000Z","size":931,"stargazers_count":146,"open_issues_count":41,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-02T04:59:12.323Z","etag":null,"topics":["javascript-runtime","v8","zig"],"latest_commit_sha":null,"homepage":"https://lightpanda.io","language":"Zig","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/lightpanda-io.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":"2022-09-15T15:48:29.000Z","updated_at":"2025-04-01T15:20:13.000Z","dependencies_parsed_at":"2024-05-16T01:50:41.017Z","dependency_job_id":"275e9e0d-73b7-4a77-b3be-d0403196fa25","html_url":"https://github.com/lightpanda-io/zig-js-runtime","commit_stats":null,"previous_names":["lightpanda-io/zig-js-runtime"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightpanda-io%2Fzig-js-runtime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightpanda-io%2Fzig-js-runtime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightpanda-io%2Fzig-js-runtime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lightpanda-io%2Fzig-js-runtime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lightpanda-io","download_url":"https://codeload.github.com/lightpanda-io/zig-js-runtime/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305932,"owners_count":20917208,"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-runtime","v8","zig"],"created_at":"2024-08-09T14:03:44.118Z","updated_at":"2025-04-05T08:03:47.101Z","avatar_url":"https://github.com/lightpanda-io.png","language":"Zig","readme":"# zig-js-runtime\n\nA fast and easy library to add a Javascript runtime into your Zig project.\n\nWith this library you can:\n\n- add Javascript as a scripting language for your Zig project (eg. plugin system, game scripting)\n- build a web browser (this library as been developed for the [Lightpanda headless browser](https://lightpanda.io))\n- build a Javascript runtime (ie. a Node/Bun like)\n\nFeatures:\n\n- [x] Setup and configure the Javascript engine\n- [x] Expose Zig structs as Javascript functions and objects (at compile time)\n- [x] Bi-directional \"link\" between Zig structs and Javascript objects\n- [x] Support for inheritance (on Zig structs) and prototype chain (on Javascript objects)\n- [x] Support for Javascript asynchronous code (I/O event loop)\n\nCurrently only v8 is supported as a Javascript engine, but other engines might be added in the future.\n\nThis library is fully single-threaded to matches the nature of Javascript and avoid any cost of context switching for the Javascript engine.\n\n## Rationale\n\nIntegrate a Javascript engine into a Zig project is not just embeding an external library and making language bindings.\nYou need to handle other stuffs:\n\n- the generation of your Zig structs as Javascript functions and objects (_ObjectTemplate_ and _FunctionTemplate_ in v8)\n- the callbacks of Javascript actions into your Zig functions (constructors, getters, setters, methods)\n- the memory management between the Javascript engine and your Zig code\n- the I/O event loop to support asynchronous Javascript code\n\nThis library takes care of all this, with no overhead thanks to Zig awesome compile time capabilities.\n\n## Getting started\n\nIn your Zig project, let's say you have this basic struct that you want to expose in Javascript:\n\n```zig\nconst Person = struct {\n    first_name: []u8,\n    last_name: []u8,\n    age: u32,\n\n    // Constructor\n    // if there is no 'constructor' defined 'new Person()' will raise a TypeError in JS\n    pub fn constructor(first_name: []u8, last_name: []u8, age: u32) Person {\n        return .{\n            .first_name = first_name,\n            .last_name = last_name,\n            .age = age,\n        };\n    }\n\n    // Getter, 'get_\u003cfield_name\u003e'\n    pub fn get_age(self: Person) u32 {\n        return self.age;\n    }\n\n    // Setter, 'set_\u003cfield_name\u003e'\n    pub fn set_age(self: *Person, age: u32) void {\n        self.age = age;\n    }\n\n    // Method, '_\u003cmethod_name\u003e'\n    pub fn _lastName(self: Person) []u8 {\n        return self.last_name;\n    }\n};\n```\n\nYou can generate the corresponding Javascript functions at comptime with:\n\n```zig\nconst jsruntime = @import(\"jsruntime\");\npub const Types = jsruntime.reflect(.{Person});\n```\n\nAnd then use it in a Javascript script:\n\n```javascript\n// Creating a new instance of Person\nlet p = new Person('John', 'Doe', 40);\n\n// Getter\np.age; // =\u003e 40\n\n// Setter\np.age = 41;\np.age; // =\u003e 41\n\n// Method\np.lastName(); // =\u003e 'Doe'\n```\n\nLet's add some inheritance (ie. prototype chain):\n\n```zig\nconst User = struct {\n    proto: Person,\n    role: u8,\n\n    pub const prototype = *Person;\n\n    pub fn constructor(first_name: []u8, last_name: []u8, age: u32, role: u8) User {\n        const proto = Person.constructor(first_name, last_name, age);\n        return .{ .proto = proto, .role = role };\n    }\n\n    pub fn get_role(self: User) u8 {\n        return self.role;\n    }\n};\n\npub const Types = jsruntime.reflect(.{Person, User});\n```\n\nAnd use it in a Javascript script:\n\n```javascript\n// Creating a new instance of User\nlet u = new User('Jane', 'Smith', 35, 1); // eg. 1 for admin\n\n// we can use the User getters/setters/methods\nu.role; // =\u003e 1\n\n// but also the Person getters/setters/methods\nu.age; // =\u003e 35\nu.age = 36;\nu.age; // =\u003e 36\nu.lastName(); // =\u003e 'Smith'\n\n// checking the prototype chain\nu instanceof User == true;\nu instanceof Person == true;\nUser.prototype.__proto__ === Person.prototype;\n```\n\n### Javascript shell\n\nA Javascript shell is provided as an example in `src/main_shell.zig`.\n\n```sh\n$ make shell\n\nzig-js-runtime - Javascript Shell\nexit with Ctrl+D or \"exit\"\n\n\u003e\n```\n\n## Build\n\n### Prerequisites\n\nzig-js-runtime is written with [Zig](https://ziglang.org/) `0.14.0`. You have to\ninstall it with the right version in order to build the project.\n\nTo be able to build the v8 engine, you have to install some libs:\n\nFor Debian/Ubuntu based Linux:\n```sh\nsudo apt install xz-utils \\\n    python3 ca-certificates git \\\n    pkg-config libglib2.0-dev clang\n```\n\nFor MacOS, you only need Python 3.\n\n### Install and build dependencies\n\nThe project uses git submodule for dependencies.\nThe `make install-submodule` will init and update the submodules in the `vendor/`\ndirectory.\n\n```sh\nmake install-submodule\n```\n\n### Build v8\n\nThe command `make install-v8-dev` uses `zig-v8` dependency to build v8 engine lib.\nBe aware the build task is very long and cpu consuming.\n\nBuild v8 engine for debug/dev version, it creates\n`vendor/v8/$ARCH/debug/libc_v8.a` file.\n\n```sh\nmake install-v8-dev\n```\n\nYou should also build a release vesion of v8 with:\n\n```sh\nmake install-v8\n```\n\n### All in one build\n\nYou can run `make install` and `make install-dev` to install deps all in one.\n\n## Development\n\nSome Javascript features are not supported yet:\n\n- [ ] [Promises](https://github.com/lightpanda-io/zig-js-runtime/issues/73) and [micro-tasks](https://github.com/lightpanda-io/zig-js-runtime/issues/56)\n- [ ] Some Javascript types, including [Arrays](https://github.com/lightpanda-io/zig-js-runtime/issues/52)\n- [ ] [Function overloading](https://github.com/lightpanda-io/zig-js-runtime/issues/54)\n- [ ] [Types static methods](https://github.com/lightpanda-io/zig-js-runtime/issues/127)\n- [ ] [Non-optional nullable types](https://github.com/lightpanda-io/zig-js-runtime/issues/72)\n\n### Test\n\nYou can test the zig-js-runtime library by running `make test`.\n\n## Credits\n\n- [zig-v8](https://github.com/fubark/zig-v8/) for v8 bindings and build\n- [Tigerbeetle](https://github.com/tigerbeetledb/tigerbeetle/tree/main/src/io) for the IO loop based on _io\\_uring_\n- The v8 team for the [v8 Javascript engine](https://v8.dev/)\n- The Zig team for [Zig](https://ziglang.org/)\n","funding_links":[],"categories":["Zig"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightpanda-io%2Fzig-js-runtime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flightpanda-io%2Fzig-js-runtime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flightpanda-io%2Fzig-js-runtime/lists"}