Docs / BuckleScript / EmbedRawJavascript

Embed Raw JavaScript

We're introducing this last-resort escape hatch first, in case you're ever stuck trying the other more legitimate APIs and wanna move on. Here's how you can drop a chunk of JavaScript right into your BuckleScript file:

RE
let add = [%raw {| function(a, b) { console.log("hello from raw JavaScript!"); return a + b } |}]; Js.log(add(1, 2));

The {|foo|} syntax stands for OCaml/BuckleScript/Reason's multi-line, "quoted string" syntax. Think of them as the equivalent of JavaScript's template literals. No escaping is needed inside that string.

Careful with the OCaml/Reason syntax here. [%raw foo] allows you to embed an expression. For top-level declarations in OCaml/Reason, use [%%raw foo] (two %):

RE
[%%raw "var a = 1"]; let f = [%raw "function() {return 1}"];

Debugger

You can also drop a [%debugger] expression in a body:

RE
let f = (x, y) => { [%debugger]; x + y };

Output:

JS
function f (x,y) { debugger; // JavaScript developer tools will set an breakpoint and stop here x + y; }

Detect Global Variables

BuckleScript provides a relatively type safe approach for such use case: external. [%external a_single_identifier] is a value of type option. Example:

RE
switch ([%external __DEV__]) { | Some(_) => Js.log("dev mode") | None => Js.log("production mode") };

Output:

JS
var match = typeof (__DEV__) === "undefined" ? undefined : (__DEV__); if (match !== undefined) { console.log("dev mode"); } else { console.log("production mode"); }

Another example:

RE
switch ([%external __filename]) { | Some(f) => Js.log(f) | None => Js.log("non-node environment") };

Output:

JS
var match = typeof (__filename) === "undefined" ? undefined : (__filename); if (match !== undefined) { console.log(match); } else { console.log("non-node environment"); }

Tips & Tricks

Embedding raw JS snippets is discouraged, though also highly useful if you're just starting out. As a matter of fact, the first few Reason BuckleScript projects were converted through:

  • pasting raw JS snippets inside a file

  • examining the JS output (identical)

  • gradually extract a few values and functions and making sure the output still looks OK

At the end, we get a fully safe, converted Reason BuckleScript file whose JS output is clean enough that we can confidently assert that no new bug has been introduced during the conversion process.

We have a small guide on this iteration here. Feel free to peruse it later.