diff --git a/README.md b/README.md index 2e5a47d3da9a..eab11c18d7fa 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,54 @@ High-quality APIs for [Deno](https://deno.com/) and the web. Use fearlessly. - [Contributing guidelines](.github/CONTRIBUTING.md) - [Frequently asked questions (FAQ)](./.github/FAQ.md) +## Using the Standard Library in a browser + +Standard Library packages are published as TypeScript on JSR. Bundle them into +JavaScript before loading them in a browser. For example, create an entry point: + +```ts ignore +// main.ts +import { escape } from "jsr:@std/html@^1.0.4/entities"; + +document.body.innerHTML = escape(""); +``` + +Then bundle it for browsers: + +```sh +deno bundle --platform browser -o dist/main.js main.ts +``` + +For custom esbuild pipelines, use +[`esbuild-deno-loader`](https://jsr.io/@luca/esbuild-deno-loader) so esbuild can +resolve Deno, JSR, and import-map specifiers: + +```ts ignore +// build.ts +import * as esbuild from "npm:esbuild@^0.28.2"; +import { denoPlugins } from "jsr:@luca/esbuild-deno-loader@^0.11.1"; + +await esbuild.build({ + plugins: [...denoPlugins()], + entryPoints: ["main.ts"], + outfile: "dist/main.js", + bundle: true, + format: "esm", +}); + +await esbuild.stop(); +``` + +Then load `dist/main.js` from an HTML module script: + +```html + +``` + +Only use modules whose source contains the +`// This module is browser compatible.` declaration. Other modules may depend on +Deno or Node.js APIs that are unavailable in browsers. + ## Releases Package versions >=1.0.0 follow [Semantic Versioning](https://semver.org/), and