@greenwood/plugin-polyfills
v0.34.0
Published
A Greenwood plugin adding support for Web Component related polyfills like Custom Elements and Shadow DOM.
Maintainers
thescientist13Readme
@greenwood/plugin-polyfills
Overview
A Greenwood plugin adding support for Web Component related polyfills for browsers that need support for part of the Web Component spec like Custom Elements and Shadow DOM. It uses feature detection to determine what polyfills are actually needed based on the user's browser, to ensure only the minimum extra code is loaded. If you are using Lit@2, it also loads the needed polyfill-support.js file.
As of right now, you will likely need this plugin to load additional polyfills if you want to support these browser(s):
- Internet Explorer <= 11
- Mobile Browsers
- Declarative Shadow DOM
For more information and complete docs on Greenwood, please visit our website.
This package assumes you already have
@greenwood/cliinstalled.
Installation
You can use your favorite JavaScript package manager to install this package. This package assumes you already have @greenwood/cli installed.
# npm
$ npm i -D @greenwood/plugin-polyfills
# yarn
$ yarn add @greenwood/plugin-polyfills --dev
# pnpm
$ pnpm add -D @greenwood/plugin-polyfillsUsage
Use this plugin in your greenwood.config.js:
import { greenwoodPluginPolyfills } from '@greenwood/plugin-polyfills';
export default {
// ...
plugins: [
greenwoodPluginPolyfills()
]
}Now when your project builds for production, you will see a bundles/ directory in your output directory, as well as a file called webcomponents-loader.js, as well as a <script> tag for that file in the <head> of your index.html files. When a page is loaded, the feature detection capabilities will then load the necessary polyfills to have your project work for a user's given browser.
Note: we would like to add support for differential loading to avoid the cost of this for newer browsers.
Types
Types should automatically be inferred through this package's exports map, but can be referenced explicitly in both JavaScript (JSDoc) and TypeScript files if needed.
/** @type {import('@greenwood/plugin-polyfills').PolyfillsPlugin} */import type { PolyfillsPlugin } from '@greenwood/plugin-polyfills';Options
This plugin supports the following polyfills and configuration options:
- Web Components Loader -
wc - Declarative Shadow DOM -
dsd - Lit -
lit(Use this in conjunction with Web Components Loader)
You can adjust either of these default behaviors by providing true or false for each polyfill type.
import { greenwoodPluginPolyfills } from '@greenwood/plugin-polyfills';
export default {
// ...
// default values shown here
plugins: [
greenwoodPluginPolyfills({
wc: true,
dsd: false,
lit: false
})
]
}