pyongyang
The simplest way to integrate with JS dependencies designed for the Web within React Native.
⚠️ Warning: Pyongyang is super experimental. Don't do anything sensitive or important with it, just have fun. 🙏
🔥 Features
- Execute any standard web dependency within React Native!
- Back-and forth encryption.
- Data is passed back and forth using an encrypted dynamic secret persisted in obfuscated source.
- Every time your hook is amounted, the secret is recycled.
- XSS Resistant
- All input variables are passed through stringification first, turning executable code into safe strings.
- Supports ES6.
- Supports Android, iOS and the Web!
🚀 Getting Started
Using Yarn:
yarn add react-native-webview pyongyang
📚 Guide
1. Hello, world!
In the following example, we show how simple it is to invoke a JavaScript runtime running in a hidden managed WebView
. First, we declare a Pyongyang
Provider at the root of the application; this component manages the instantiation of WebView
s to execute your scripts.
Inside the Hello
component, we make a call to the pyongyang
hook:
;; { pyongyang`alert('hello, world')`; return null;} { return <Pyongyang><Hello /></Pyongyang>;}
Upon load, the defined script is executed by an anonymous WebView, which cannot be seen or interacted with. This is because pyongyang
is designed for pure computation.
2. Variables
Let's make things a little more complicated. This time, using the variables
parameter, we can pass data from the React Native runtime into the target JavaScript engine. These variables can be referenced in supplied code by prefixing the variable name with a $
.
In this instance, the variable name
is referenced using $name
.
;; { ; return null;} { return <Pyongyang><Variables /></Pyongyang>;}
Note: Notice that your code is executed within an
async
block.
3. Callbacks
It's also simple to accept callbacks from pyongyang
. Here, the onMessage
callback is referenced via $onMessage
.
;;; { const onMessage = React; ; return null;} { return <Pyongyang><Callbacks /></Pyongyang>;}
4. Dependencies
Here's where things get interesting. It's possible to pass CDN script references into pyongyang
, which become available in the window object. These external JavaScript resources can be specified using the resources
prop.
In the example below, it's trivial to utilize the Interplanetary File System (IPFS) directly inline, without making any native changes.
; ; { const = ; return null;} { return <Pyongyang><Ipfs /></Pyongyang>;};
5. Futures
It's also possible to execute in pyongyang
after the initial script has been executed. Your script is allowed to return an object of functions which you'd like to expose back to the native runtime. These can be executed asynchronously, and retain the scope of the original function call.
; ; { const loading error futures: myFunction = pyongyang` const myFunction = i => i + 1; return { myFunction };`; React; return null;} { return <Pyongyang><Futures /></Pyongyang>;}
6. Refs
Since the JavaScript code you execute happens inside of a WebView
, rich objects cannot be passed back into React Native; they can only be transported in a way that can be represented using JSON. Therefore, if you wish to hold onto the runtime representation of an object for use later, you need to use a ref, which is basically a reference to an object which can be retained and used later.
To highlight a method as a ref, prefix the method name using a $
.
; ; { const loading error futures = pyongyang` return { $get: msg => { someValue: 5, doSomething: () => alert(msg), }, doSomethingWith: e => e.doSomething(), };`; React; return null;} { return <Pyongyang><Futures /></Pyongyang>;}