Greybel-JS

3.7.12 verified Fri May 01 auth: no javascript

Greybel-JS (v3.7.12) is a CLI and library for transpiling, interpreting, and debugging GreyScript, a scripting language for the Grey Hack game. It provides a parser, lexer, compiler, and interpreter with full GreyScript API support. Key differentiators are its ability to manage imports, minimize scripts (up to 40% size reduction), beautify code, and run GreyScript outside the game environment. The package requires Node >=20.17.0 and has optional peer dependencies on React and Monaco editor for the web UI. It offers advanced features like dependency management, environment variables, a REPL, and a debugging UI. Compared to alternatives, Greybel-JS is the main GreyScript toolchain maintained by the community.

Common errors

error Cannot find module 'greybel-js' ↓

cause Using require() in Node.js with an ESM-only package.

fix

Change to import statement: import { ... } from 'greybel-js'; or use dynamic import: const greybel = await import('greybel-js');

error TypeError: greybel_js__WEBPACK_IMPORTED_MODULE_0__.default is not a function ↓

cause Importing default export instead of named exports.

fix

Use named import: import { Greybel, Transpiler, Interpreter } from 'greybel-js';

error error: unknown option '--no-color' ↓

cause Using deprecated CLI flag removed in v3.

fix

Use environment variable: set NO_COLOR=1 before running the CLI.

Warnings

breaking In Greybel-JS v3, the package switched from CommonJS to ESM-only. Imports using require() will fail with MODULE_NOT_FOUND error. ↓

fix Use import syntax instead of require(). Update tsconfig.json to target ESNext or use dynamic import for CJS projects.

deprecated The export name 'Compiler' is deprecated in v3. It has been renamed to 'Transpiler'. ↓

fix Use 'Transpiler' instead of 'Compiler' when importing.

gotcha The interpreter's mock environment does not include the full Grey Hack API. Some functions (e.g., file I/O, networking) are stubs and will not behave as in-game. ↓

fix Always test scripts in-game before relying on interpreter behavior. Use the 'debugger' for more accurate simulation.

gotcha Minification can break scripts that rely on certain variable names or dynamic property access. Obfuscated names may conflict with reserved keywords. ↓

fix Test minified scripts thoroughly. Use the 'beautify' option to revert minification for debugging.

deprecated The CLI flag '--no-color' has been removed in v3. Use 'NO_COLOR' environment variable instead. ↓

fix Set process.env.NO_COLOR = '1' or use any standard NO_COLOR support.

Install

npm install greybel-js

yarn add greybel-js

pnpm add greybel-js

Imports

Greybel
wrong
```
const greybel = require('greybel-js');
```
correct
```
import { Greybel } from 'greybel-js'
```
The package is ESM-only since v3; CommonJS require() is not supported.
Transpiler
```
import { Transpiler } from 'greybel-js'
```
Named export for transpiling GreyScript into optimized script. Also exported as 'Compiler' in older versions.
Interpreter
wrong
```
import Interpreter from 'greybel-js';
```
correct
```
import { Interpreter } from 'greybel-js'
```
Interpreter is a named export, not a default one. Default import is not available.

Quickstart

Shows how to transpile and interpret GreyScript code using Greybel-JS programmatically.

import { Greybel, Transpiler, Interpreter } from 'greybel-js';

// Example GreyScript source code
const source = `
function main() {
    print("Hello, Grey Hack!");
}
main();
`;

// Compile/transpile
const transpiler = new Transpiler({ source });
const { code, map } = transpiler.transpile();
console.log('Transpiled code:', code);

// Or execute with interpreter
const interpreter = new Interpreter({ source });
interpreter.on('output', (msg) => console.log('Output:', msg));
interpreter.run();

// Or use CLI: npx greybel-js transpile input.gs -o output.gs