Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill
An esbuild plugin to polyfill nodejs builtin modules for the browser.
https://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill
esbuild esbuild-plugin hacktoberfest javascript nodejs polyfill typescript
Last synced: 3 months ago
JSON representation
An esbuild plugin to polyfill nodejs builtin modules for the browser.
- Host: GitHub
- URL: https://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill
- Owner: imranbarbhuiya
- License: mit
- Created: 2022-07-08T15:14:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-19T21:07:41.000Z (6 months ago)
- Last Synced: 2024-05-20T06:31:02.466Z (6 months ago)
- Topics: esbuild, esbuild-plugin, hacktoberfest, javascript, nodejs, polyfill, typescript
- Language: TypeScript
- Homepage:
- Size: 14.5 MB
- Stars: 17
- Watchers: 2
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# esbuild-plugins-node-modules-polyfill
**Polyfills nodejs builtin modules for the browser.**
[](https://github.com/imranbarbhuiya/esbuild-plugins-node-modules-polyfill/blob/main/LICENSE)
[](https://www.npmjs.com/package/esbuild-plugins-node-modules-polyfill)
## Description
Polyfills nodejs builtin modules and globals for the browser.
## Features
- Written In Typescript
- Offers CJS and ESM builds
- Full TypeScript & JavaScript support
- Supports `node:` protocol
- Supports [`browser` field in `package.json`](https://github.com/defunctzombie/package-browser-field-spec)
- Optionally injects globals
- Optionally provides empty fallbacks
## Install
```bash
npm install --save-dev esbuild-plugins-node-modules-polyfill
```
## Usage
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [nodeModulesPolyfillPlugin()],
});
```
### Inject globals when detected:
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
globals: {
process: true,
Buffer: true,
},
}),
],
});
```
> [!Note]
> If you are utilizing the [`modules`](#configure-which-modules-to-polyfill) option, ensure that you include polyfills for the global modules you are using.
### Configure which modules to polyfill:
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
modules: ['crypto'],
}),
],
});
```
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
modules: {
crypto: true,
fs: false,
},
}),
],
});
```
### Provide empty polyfills:
#### Provide empty polyfills for specific modules:
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
modules: {
fs: 'empty',
crypto: true,
},
}),
],
});
```
#### Provide empty fallbacks for any unpolyfilled modules:
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
fallback: 'empty',
}),
],
});
```
#### Provide empty fallbacks for any unconfigured modules:
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
build({
plugins: [
nodeModulesPolyfillPlugin({
fallback: 'empty',
modules: {
crypto: true,
},
}),
],
});
```
### Fail the build when certain modules are used:
> [!Important]
> The `write` option in `esbuild` must be `false` to support this.
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
const buildResult = await build({
write: false,
plugins: [
nodeModulesPolyfillPlugin({
modules: {
crypto: 'error',
path: true,
},
}),
],
});
```
### Fail the build when a module is not polyfilled or configured:
> [!Important]
> The `write` option in `esbuild` must be `false` to support this.
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
const buildResult = await build({
write: false,
plugins: [
nodeModulesPolyfillPlugin({
fallback: 'error',
modules: {
path: true,
},
}),
],
});
```
### Provide a custom error formatter when a module is not polyfilled or configured:
Return an esbuild `PartialMessage` object from the `formatError` function to override any properties of the default error message.
> [!Important]
> The `write` option in `esbuild` must be `false` to support this.
```ts
import { nodeModulesPolyfillPlugin } from 'esbuild-plugins-node-modules-polyfill';
import { build } from 'esbuild';
const buildResult = await build({
write: false,
plugins: [
nodeModulesPolyfillPlugin({
fallback: 'error',
modules: {
path: true,
},
formatError({ moduleName, importer, polyfillExists }) {
return {
text: polyfillExists
? `Polyfill has not been configured for "${moduleName}", imported by "${importer}"`
: `Polyfill does not exist for "${moduleName}", imported by "${importer}"`,
};
},
}),
],
});
```
## Buy me some doughnuts
If you want to support me by donating, you can do so by using any of the following methods. Thank you very much in advance!
## Contributors ✨
Thanks goes to these wonderful people:
