Collection of fast TypeScript loaders.

Made with 🧡 at Hack.bg.

Backends

• [x] @ganesha/oxc: based on Oxc, the Oxidation Compiler. Fast but no source maps yet (see oxc#1045)
• [x] @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)
• [x] @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.

Benchmarks

TODO, contributions welcome.

How to use

Install with:

npm i --save @ganesha/oxc # or @ganesha/esbuild

Use from shell:

node --import @ganesha/oxc ./my-program.ts # or @ganesha/esbuild

Use from script:

await import("@ganesha/oxc") // or @ganesha/esbuild
await import("./my-program") // note that it works with no extension

The TypeScript program in question:

// my-program.ts
import { Foo } from './another-ts-module' // no extension required!
import { Bar } from './a-raw-js-module.js' // import from JS with extension

And it works both ways:

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

Switching between backends

TODO.

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

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 a package, we switch over to Ubik, a complementary tool for publishing well-formed ESM packages from TypeScript while avoiding the nastiness of how tsc chooses to (more like "refuses to") handle extensions of imported modules.

"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)