esyes

Run your TypeScript files quickly and with more positivity.

esyes transforms your JavaScript and TypeScript files using esbuild-kit. It works seamlessly and requires no configuration to get the job done.

It also translates import.meta.env features on the fly, so you can use JavaScript or TypeScript modules written with import.meta.env directly in Node.

Hat tip to @NullVoxPopuli for the idea, originally implemented in this PR in the Starbeam repository.

Table of Contents

• Install
• Usage: Instead of the node Command
• Usage: As a Loader
• import.meta.env Support
• Advanced: Internals Tracing
• Maintainers
• Contributing
• License

Install

When using esyes to run npm scripts, install via your package manager.

$ pnpm i -D esyes

You can also install esyes globally via your package manager.

$ pnpm i -g esyes

You can also install esyes with volta, which allows you to bind it to a node version.

$ volta install esyes node@20

If you install esyes via volta and you're using it in a project with a pinned version of Node in its package.json, esyes will automatically use that version.

Usage: Instead of the node Command

$ cat hi.ts
const hello = "hello" as const;
console.log(hello);

$ esyes hi.ts
hello

All node flags and environment variables are passed through to node, so it's a true drop-in replacement for the node command.

There's one divergence: node without any arguments will run the Node REPL, while esyes with no arguments prints usage information.

Usage: As a Loader

You can use esyes directly as a Node loader without any experimental warnings.

$ cat hi.ts
const hello = "hello" as const;
console.log(hello);

$ node --import esyes hi.ts
hello

esyes uses Node's new module.register API. This is the API that the warnings you might have seen advise you to use.

import.meta.env Support

esyes will automatically transform many of the import.meta.env features supported by Vite so that you can use them directly in your JavaScript or TypeScript code.

$ cat hi.ts
const hello = "hello" as const;

if (import.meta.env.DEV) {
  console.log(hello);
} else {
  console.log("not in dev mode!");
}

$ node --import esyes hi.ts
hello

$ MODE=prod node --import esyes hi.ts
not in dev mode

This transform applies to all files, including files in your node_modules, which makes using import.meta.env transparent, even if some of the code you're working on is in node_modules (such as when working in monorepos).

The transform is expected to be extremely fast when no import.meta.env is used (it just does a quick check for import.meta.env before doing any other work).

Advanced: Internals Tracing

If the loader isn't doing what you expect, you can enable trace logging to see all of the files that the loader is processing, and the processing steps it's taking.

$ cat hi.ts
const hello = "hello" as const;

if (import.meta.env.DEV) {
  console.log(hello);
} else {
  console.log("not in dev mode!");
}

$ EYES_LOADER_LOG=log.txt node --import esyes hi.ts
hello

$ cat log.txt
load: "file:///.../hi.ts"
search for "import.meta.env" (from 0):
  found at: 23
lookahead for ".":
  found: "38..39"
lookahead for /^(MODE|DEV|PROD|TRACE)/:
  found: "39..42"
replacing:
  range: "23..42"
  with: "true"
search for "import.meta.env": "not found"

Maintainers

The Starbeam team.

Contributing

See the contributing file!

License

MIT © 2023 Yehuda Katz