Skip to content
Node.js engine for crystal-lang. JS code and npm module executes on crystal-nodejs
C C++ Other
Branch: master
Clone or download

Latest commit

Latest commit 1bf5b0a Mar 15, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

Node.js engine for crystal-lang. JS code and npm module executes on crystal-nodejs, And don't need to install Node.js binary.Explain about architecture, Compiled as a shared object Node.js(i.e: libnodejs) and execute as one process on crystal-lang. So call C execvp() system call through method, execute in this c function. method is low overhead, Compare pure Node.js js code and crystal-nodejs js code, There was no difference in performance(see Benchmark heading about performance detail).

The biggest merit is that over 11,000,000 npm modules can be used in crystal and Will expand the Crystal Lang ecosystem

Using crystal-nodejs can pass through Node.js result of crystal-lang. Happy Crystaling!! 🎉

Architecture image

In the above architecture image, crystal-nodejs provides Node.js, LibC, lib that was created crystal-lang

Supported OS

  • Linux(Ubuntu16.04, 18.04, Arch Linux...Maybe will work other distributions)
  • MacOSX(High Sierra)
  • Windows(Unfortunately yet not supported on crystal-lang...)

Supported Node.js

  • Look at this directory(e.g 10.16.0, 13.10.1) for supported versions.crystal-nodejs will be supported until latest 3 version in Node.js

  • Current Node.js latest version: 13.10.1


  1. Add the dependency to your shard.yml:
       github: fukaoi/crystal-nodejs
  1. Run shards install

  2. libnodejs install, init js directory make or make all.So created $HOME/.crystal-nodejs/

├── bin        // Use binary in crystal-nodejs
│   ├── node  
│   ├── npm 
│   └── npx
├── js         // Origina JS code, package.json. Enable the subdirectories below js/*/a.js
└── lib        // shared object for Node.js


Bacis usage

Output Hello crystal-nodejs !! on terminal

  • Simple JS code, output 'Hello crystal-nodejs'
require "nodejs"

Nodejs.eval("console.log('Hello crystal-nodejs !!')")

Use setTimeout execute lazy code

  • below code is output 'Hello crystal' after 2sec
require "nodejs"

code = <<-CODE
  let user = {
    sayHi(firstName) {
      console.log(`Hello, ${firstName}!`);
  setTimeout(() => {user.sayHi('crystal')}, 2000);


How to send Node.js result to crystal-lang

  • Use special toCrystal() method.toCrystal() is only function in crystal-nodejs.Can response various type in JS, and all JS type is converted JSON::Any in crystal
require "nodejs"

code = <<-CODE

res = Nodejs.eval(code)

puts res           # {"data" => "spec"}
puts typeof(res)   # JSON::Any

  • The below example, all JS type(Number, Boolean, String) is converted JSON::Any.
require "nodejs"

code = <<-CODE

res = Nodejs.eval(code)

puts res           # 123456
puts typeof(res)   # JSON::Any

Use NPM(node modules)

Node modules is installed in $HOME/.crystal-nodejs/js/

npm install method

  • Use Nodejs::Npm.install('package name') method, can install need package.this below example is for use mathjs module.
require "nodejs"

code = <<-CODE
  const math = require("mathjs"); // Note: JS side require
  toCrystal(math.log(10000, 10));

puts Nodejs.eval(code) # 4


  • a package.json copy to $HOME/.crystal-nodejs/js/ direcotry, and call NodeJs::Npm.install method


"dependencies": {
  "mathjs": "^6.0.2"
require "nodejs"

code = <<-CODE
  const math = require("mathjs"); // Note: JS side require
  toCrystal(math.log(10000, 10));

puts Nodejs.eval(code) # 4

Use existing the JS file

loading JS file and execute

  • existing js file to, use Node Js.file run method, can run on crystal-lang


const fs = require('fs');
fs.readFile('spec/', 'utf8', (err, text) => {
  console.log('text file!');
  toCrystal({text: text});
require "nodejs"
puts Nodejs.file_run("./file_run.js")

Replace parameters in existing JS file

  • Use Nodejs.replace_params() method, can set the customization value to the parameter of the existing js file from crystal-lang. this method merit don't have to modify existing js files and can use on crystal-lang

  • replace parameter type can be only const xxxxx.


const a = 10;
const b = 20;

const calc = (left_side, right_side) => {
  return left_side + right_side;

const res = calc(a, b);
require "nodejs"

code ="./calc.js")
hash = {
  "a" => 100,  # const a = 100
  "b" => 200   # const b = 200

replaced_code = Nodejs.replace_params(code, hash)
Nodejs.eval(replaced_code)  # 300

Catch JS Exception

throw errors directly

  • throw Error in JS, it is converted as JSSideExceptin in crystal-lang. So can catch JSSIDEExcetpion in crystal-lang.
require "nodejs"

code = <<-CODE
  throw new Error('Error raise!');

Error: Error raise!
    at [eval]:10:9
    at Script.runInThisContext (vm.js:122:20)
    at Object.runInThisContext (vm.js:329:38)
    at Object.<anonymous> ([eval]-wrapper:6:22)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at evalScript (internal/bootstrap/node.js:589:27)
    at startup (internal/bootstrap/node.js:265:9)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)

Error object throw after catch the JS Error with try catch

  • can pass an error object to crystal-lang by using a specific toCrystalErr method.
require "nodejs"

code = <<-CODE
  try {
    throw new Error('Error raise!');
  } catch(e) {

Error: Error raise!
    at [eval]:10:8
    at Script.runInThisContext (vm.js:122:20)
    at Object.runInThisContext (vm.js:329:38)
    at Object.<anonymous> ([eval]-wrapper:6:22)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at evalScript (internal/bootstrap/node.js:589:27)
    at startup (internal/bootstrap/node.js:265:9)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:622:3)

More usages look at spec/nodejs/npm/


This benchmark is fibonacci and binary-search results, As can see from the result, crystal-nodejs is high performance.below at bar chart is response average time that executes 5 times fibonacci and binary-search. benchmark source code detail is can see from URL link

  • Machine spec:
    • cpu: Intel(R) Core(TM) i7-7820HK CPU @ 2.90GHz 4core
    • memory: 16Gbyte

Raw data(Benchmark result)

  • fibonacci
- Node.js crystal-nodejs
1 real 2m26.968s real 2m27.337s
2 real 2m27.230s real 2m27.263s
3 real 2m26.987s real 2m28.058s
4 real 2m27.582s real 2m26.672s
5 real 2m27.262s real 2m26.831s
  • binary-search
- Node.js crystal-nodejs
1 real 1m35.699s real 1m35.962s
2 real 1m35.082s real 1m32.018s
3 real 1m33.309s real 1m35.212s
4 real 1m34.423s real 1m33.830s
5 real 1m32.050s real 1m33.530s


Extension directory tree

├──     // main function for
├──   // script for rewrite node path of npm
├── obj            // shared object of Linux, Mac OSX
│   └── 10.16.0
└── 10.16.0        // shared object dependency file and directory
    ├── bin
    ├── include
    └── lib

Create json class

May want to convert crystal-lang json mapper type because response parameter from Nodejs.eval() method is all JSON::Any type. So the recommended tool is jsontocr, very simple and easy.


  • CrystalSideException ... Be thrown error in crystal-lang code
  • JSSideException ... Be thrown error in JS code

Make tasks

  • make build ... build libnode and deploy $HOME/.crystal-nodejs/
  • make install ... using package.json, npm install of dependency modules
  • make nodejs ... git clone Node.js and build
  • make (all) ... Same task make build && make install
  • make clean ... delete $HOME/.crystal-nodejs/ and temporaty directory
  • make audit ... do static analysis for JS

Raw JS

If will do mixing crystal-lang code and JS code, Debug is hard. But crystal-nodejs can export Raw JS, Can easily see the JS code that is actually executed.

this function is enable below

RAW_JS=true crystal run(or spec)

RAW_JS=true best timing is when execute spec, because must call Nodejs.eval() method.Export of most Raw JS if coverage of spec code is high. To see exported the code, /tmp/raw_js/

├── 0cc6107a79be7b828321e57a81a5f828.js
├── 124d1032b2bc7c02cd59430dd8d1ba65.js
├── 170fa95978969d76eca70d2947da4e2f.js
├── 31df5239bef6b4510b8b6e3840627a58.js
├── eaaa61190908871f1571bc5eca89b87a.js
├── ff3c96e301d7d34c34c4a86fef92e09b.js
└── ff4d0b01de3d93d612bb5a09ed381711.js


Scan for vulnerabilities when build project. If be found vulnerabilities, build is supposed to fail.this logic execute npm audit command in Makefile.execute npm audit --fix command and build continue

use make audit, export raw JS to /tmp/raw_js/ and do static analysis with eslint-plugin-security

Case study

Now writting...


  1. Fork it (
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


  • fukaoi - creator and maintainer
You can’t perform that action at this time.