JSPM

How to use

Install @hackbg/ganesha and use the ganesha-run command to run a Node.js process with Ganesha support. Requires Node 16.12+.

npm i -g @hackbg/ganesha
ganesha-run my-typescript-program.ts
ganesha-run my-literate-program.ts.md

What it does

Compile TypeScript on demand

Having to run tsc on every change is a speed bump. Ganesha allows Node.js to load TypeScript files, compiling them on demand to the appropriate JavaScript module format.

// hello.ts
export const hello = (what: string) => console.log('hello', what)

// main.ts
import { hello } from './hello'
hello('world')

• package.json:

{
  "type": "module",
  "exports": {
    "ganesha": "./main.ts",
    "default": "./dist/main.js"
  },
  "devDependencies": {
    "@hackbg/ganesha": "^2",
    "typescript":      "^5"
  },
  "scripts": {
    "prepublishOnly": "tsc",
    "start": "ganesha-run ./hello.ts"
  }
}

npm start # no need to run tsc unless you're publishing to NPM!

Run code that is embedded in Markdown

Automatically generated documentation is often insufficient, and when your code and docs live in different places, it's easy to overlook writing high-level documentation.

Ganesha allows Node.js to load Markdown files by extracting the contents of fenced code blocks. This is an implementation of Don Knuth's literate programming concept, using the tools of the Web age - Markdown and JS/TS.

# My literate program

The text will be ignored
and the code will be executed:

```typescript
console.log("Hello world!")
```

Frontend bundling of literate modules

Ganesha provides a Rollup plugin that can be used in Rollup or Vite to compile literate modules for the browser.

<!-- index.html -->
<script type="module" src="./script"></script>

<!-- script.ts.md -->
This is an example literate frontend script:
```typescript
console.log('Hello, world!')
```

// vite.config.js
import { defineConfig } from 'vite'
import ganesha from '@ganesha/rollup'
export default defineConfig({ plugins: [ ganesha() ] })

Type checking of literate modules

Use ganesha-tsc to type check literate modules. A VSCode plugin and LSP server are currently in development (help wanted, VSCode and LSP are hell!)

Comparison with alternatives

The very day I was born I made my first mistake, and by that path have I sought wisdom ever since. - William Buck