Collection of fast TypeScript loaders.

Made with 🧡 at Hack.bg.

---

How to use

Install

npm i --save @ganesha/esbuild-wasm
# and/or:
npm i --save @ganesha/esbuild

Use from shell

node --import @ganesha/esbuild ./my-program.ts

Use with shebang/hashbang

#!/usr/bin/env -S node --import @ganesha/esbuild

Note that env -S is unavailable in Busybox environments such as Alpine Linux.

Use from JS

await import("@ganesha/esbuild")
await import("./my-program")
// supports extensionless imports, unlike raw Node

And now my-program.ts can look like this:

import { Foo } from './another-ts-module'  // extension optional but preferred
import { Bar } from './a-raw-js-module.ts' // import from TS with extension
import { Bar } from './a-raw-js-module.js' // import from *existing* JS with extension

Conversely a my-program.js running in the same process would also work:

import { Foo } from './another-ts-module.ts' // extension optional but preferred

Caching

For faster loading, Ganesha provides a cache based on cacache. This cache is controlled by the following environment variables:

• GANESHA_CACHE_PATH: path to cache store
• GANESHA_CACHE_OFF: set this to a non-empty value to disable caching

The cache store path defaults to a subdirectory of the user's cache root, as returned by @folder/xdg. For example, on desktop Linux, this would be ~/.cache/ganesha-v5

To disable caching globally (for a given store path), you can write a file in place of the caching directory, e.g.:

rm -rf ~/.cache/ganesha-v5
echo "delete this file to reenable caching" > ~/.cache/ganesha-v5

Available backends

Ganesha can perform type stripping useing one of several available tools:

• @ganesha/oxc: based on Oxc, the Oxidation Compiler. Fast but no source maps yet (see oxc#1045)
• @ganesha/esbuild-wasm: based on esbuild. Slower (~2.5x), but source maps work out of the box. May dump Go stack trace to console (see esbuild#1662 and go#59099)
• @ganesha/esbuild: based on esbuild. Depends on native binary, but unaffected by the above esbuild-wasm issue.
• @ganesha/ezno: possible future support for ezno is under consideration.
• @ganesha/swc: possible future support for swc is under consideration.
• TODO: Use env var to switch between backends?
• TODO: Benchmark various backends
• TODO: Optional load-time type checking?

Troubleshooting

To see what Ganesha is doing:

• GANESHA_DEBUG: set this environment variable to enable logging to stderr.

TODO.

See also

At Hack.bg, we primarily use Ganesha for developing Fadroma, a cross-chain framework for the CosmWasm ecosystem.

When it's time to publish your package, try Ubik, a complementary tool for publishing well-formed isomorphic ESM/CJS packages from TypeScript -- while avoiding all sorts of cruft that tends to accumulate at the interface boundary between JS and TS (the kind of stuff that frontend bundlers shield you from, but raw Node doesn't).

Benchmarks

TODO, contributions welcome.

---

"The very day I was born I made my first mistake,
and by that path have I sought wisdom ever since."
- William Buck's retelling of the Mahabharata
(source)