FiloSottile / typage

A TypeScript implementation of the age file encryption format, based on libsodium.
BSD 3-Clause "New" or "Revised" License
64 stars 9 forks source link

Support for use in browser #8

Closed scristalli closed 8 months ago

scristalli commented 9 months ago

This pull request is for solving #7.

By changing the import statements, the tests still pass and libsodium also is bundled correctly with esbundle, and the entire age.ts becomes usable inside the browser. I have seen the _sodium import somewhere on StackOverflow, maybe there is a better way to do it, but this works. I also included building instructions and a minimal example.

lgarron commented 8 months ago

I've submitted an alternative fix at https://github.com/FiloSottile/age.ts/pull/11

esbuild is a great tool, but I would suggest to avoid making assumptions about how the code will be used, in favor of publishing a single build of widely compatible ESM code. This also has the benefit that anyone can make their own bundles using esbuild one-liners. I give examples like this for one of my own libraries at: https://github.com/lgarron/clipboard-polyfill#bundling--tree-shaking--minification--commonjs

For example, you can suggest the following in the README for building an old-fashioned library that sets a global variable:

echo 'import age from "age-encryption"; globalThis.age = age' | \
  npx esbuild --format=iife --target=es6 --bundle --minify

This build allows the README examples to be used in the browser by simply removing the import statement.

You can also preface that with an example of how to create a temporary folder to run this, e.g.

mkdir /tmp/build && cd /tmp/build
npm init -y && npm install esbuild age-encryption

(Also, replace globalThis with window to taste, for browsers from before 2020).