Skip to content

Commit

Permalink
Support for Polymer 3 (#96)
Browse files Browse the repository at this point in the history
* Convert to Polymer 3

Recognize tagged template literal expressions and process them as HTML templates.

* 3.0.0-0

* Fix up basic tests

* Update the demo

* Disable the removeAttributeQuotes option for the html-loader by default

* Update node versions to require a minimum of Node 8

* Refactor code to be reusable

* Add support for style urls

* Update readme for Polymer 3

* Add tests to increase coverage

* 3.0.0-1

* Use a text node rather than assigning to innerText

* 3.0.0-2

* Update test snapshots

* feat: add source map support

* 3.0.0-3

* fix: adjust column offset logic

* 3.0.0-4

* Update travis config now that the yarn.lock file is deleted
  • Loading branch information
ChadKillingsworth authored and bryandcoulter committed Jan 7, 2020
1 parent 5ff5c52 commit b7dbd15
Show file tree
Hide file tree
Showing 23 changed files with 1,171 additions and 2,907 deletions.
32 changes: 0 additions & 32 deletions .babelrc

This file was deleted.

8 changes: 6 additions & 2 deletions .eslintrc
@@ -1,3 +1,7 @@
{
"extends": "webpack"
}
"extends": "webpack",
"rules": {
"no-undefined": "off",
"no-continue": "off"
}
}
1 change: 0 additions & 1 deletion .gitignore
Expand Up @@ -6,7 +6,6 @@ logs
npm-debug.log*
.eslintcache
/coverage
/dist
/local
/reports
/node_modules
Expand Down
9 changes: 4 additions & 5 deletions .travis.yml
Expand Up @@ -11,25 +11,24 @@ jobs:
include:
- &test-latest
stage: Webpack latest
node_js: 6
node_js: 8
env: WEBPACK_VERSION=latest JOB_PART=test
script: npm run travis:$JOB_PART
- <<: *test-latest
node_js: 8
node_js: 10
env: WEBPACK_VERSION=latest JOB_PART=lint
script: npm run travis:$JOB_PART
- <<: *test-latest
node_js: 8
node_js: 10
env: WEBPACK_VERSION=latest JOB_PART=coverage
script: npm run travis:$JOB_PART
after_success: 'bash <(curl -s https://codecov.io/bash)'
- stage: Webpack canary
before_script: npm i --no-save git://github.com/webpack/webpack.git#master
script: npm run travis:$JOB_PART
node_js: 8
node_js: 12
env: WEBPACK_VERSION=canary JOB_PART=test
before_install:
- rm yarn.lock
- 'if [[ `npm -v` != 5* ]]; then npm i -g npm@latest; fi'
- nvm --version
- node --version
Expand Down
141 changes: 7 additions & 134 deletions README.md
Expand Up @@ -4,116 +4,33 @@

> [Polymer](https://www.polymer-project.org/) component loader for [webpack](https://webpack.js.org/).
The loader allows you to write mixed HTML, CSS and JavaScript Polymer elements and
still use the full webpack ecosystem including module bundling and code splitting.
The loader processes Polymer 3 template elements to minify the html and add images, fonts and imported
stylesheets to the webpack dependency graph.


<img width="1024" alt="" src="https://user-images.githubusercontent.com/1066253/28131928-3b257288-66f0-11e7-8295-cb968cefb040.png">

The loader transforms your components:

* `<link rel="import" href="./my-other-element.html">` -> `import './my-other-element.html';`
* `<dom-module>` becomes a string which is registered at runtime
* `<script src="./other-script.js"></script>` -> `import './other-script.js';`
* `<script>/* contents */</script>` -> `/* contents */`

What does that mean?

Any ```<link>``` "href" or ```<script>``` "src" that is **not an external link** and does not start with ```~```, ```/```, ```./``` or a series of ```../``` will have ```./``` appended to the beginning of the value. To prevent this change use options ignoreLinks below.

## Path Translations

| `tag` | `import` |
| ----------------------------------- | ------------------------------------- |
| `<link rel="import" href="path/to/some-element.html">` | `import "./path/to/some-element.html"` |
| `<link rel="import" href="/path/to/some-element.html">` | `import "/path/to/some-element.html"` |
| `<link rel="import" href="../path/to/some-element.html">` | `import "../path/to/some-element.html"` |
| `<link rel="import" href="./path/to/some-element.html">` | `import "./path/to/some-element.html"` |
| `<link rel="import" href="~path/to/some-element.html">` | `import "~path/to/some-element.html"` |
**Looking for the Polymer 2 version?** See the
[Polymer 2 branch](https://github.com/webpack-contrib/polymer-webpack-loader/tree/polymer2)

## Configuring the Loader

```javascript
{
test: /\.html$/,
include: Condition(s) (optional),
exclude: Condition(s) (optional),
test: /\.js$/,
options: {
ignoreLinks: Condition(s) (optional),
ignorePathReWrite: Condition(s) (optional),
processStyleLinks: Boolean (optional),
htmlLoader: Object (optional)
},
loader: 'polymer-webpack-loader'
},
```

### include: Condition(s)

See [Rule.include] and [Condition] in the webpack documentation. Paths
matching this option will be processed by polymer-webpack-loader. WARNING: If
this property exists the loader will only process files matching the given
conditions. If your component has a `<link>` pointing to a component e.g. in
another directory, the `include` condition(s) MUST also match that directory.

[Rule.include]: https://webpack.js.org/configuration/module/#rule-include
[Condition]: https://webpack.js.org/configuration/module/#condition

### exclude: Condition(s)

See [Rule.exclude] and [Condition] in the webpack documentation. Paths
matching this option will be excluded from processing by
polymer-webpack-loader. NOTE: Files imported through a `<link>` will not be
excluded by this property. See `Options.ignoreLinks`.

[Rule.exclude]: https://webpack.js.org/configuration/module/#rule-exclude

### Options

#### ignoreLinks: Condition(s)

`<link>`s pointing to paths matching these conditions (see [Condition] in the
webpack documentation) will not be transformed into `import`s.

#### ignorePathReWrite: Condition(s)

`<link>` paths matching these conditions (see [Condition] in the webpack
documentation) will not be changed when transformed into `import`s. This can
be useful for respecting aliases, loader syntax (e.g.
`markup-inline-loader!./my-element.html`), or module paths.

#### processStyleLinks Boolean

If set to true the loader will rewrite `<link import="css" href="...">` or `<link rel="stylesheet" href="...">` that are inside the dom-module with `<style>require('...')</style>`. This will allow for the file to be processed by loaders that are set up in the webpack config to handle their file type.

1. Any `<link>` that is inside the `<dom-module>` but not in the `<template>` will be added to the `<template>` in the order the tags appear in the file.

```html
<dom-module>
<link rel="stylesheet" href="file1.css">
<template>
<link rel="stylesheet" href="file2.css">
</template>
</dom-module>

would produce

<dom-module>
<template>
<style>require('file1.css')</style>
<style>require('file2.css')</style>
</template>
</dom-module>
```

2. The loader will only replace a `<link>` if the href is a relative path. Any link attempting to access an external link i.e. `http`, `https` or `//` will not be replaced.

#### htmlLoader: Object

Options to pass to the html-loader. See [html-loader](https://github.com/webpack-contrib/html-loader).

### Use with Babel (or other JS transpilers)
If you'd like to transpile the contents of your element's `<script>` block you can [chain an additional loader](https://webpack.js.org/configuration/module/#rule-use).
If you'd like to transpile the contents of your element you can
[chain an additional loader](https://webpack.js.org/configuration/module/#rule-use).

```js
module: {
Expand Down Expand Up @@ -142,50 +59,6 @@ module: {
}
```

### Use of HtmlWebpackPlugin
Depending on how you configure the HtmlWebpackPlugin you may encounter conflicts with the polymer-webpack-loader.

Example:

```javascript
{
test: /\.html$/,
loader: 'html-loader',
include: [
path.resolve(__dirname, './index.html'),
],
},
{
test: /\.html$/,
loader: 'polymer-webpack-loader'
}
```
This would expose your index.html file to the polymer-webpack-loader based on the process used by the html-loader. In this case you would need to exclude your html file from the polymer-webpack-loader or look for other ways to avoid this conflict. See: [html-webpack-plugin template options](https://github.com/jantimon/html-webpack-plugin/blob/master/docs/template-option.md)

## Shimming
Not all Polymer Elements have been written to execute as a module and will
require changes to work with webpack. The most common issue encountered is because modules do not execute
in the global scope. Variables, functions and classes will no longer be global unless
they are declared as properties on the global object (window).

```js
class MyElement {} // I'm not global anymore
window.myElement = MyElement; // Now I'm global again
```

For external library code, webpack provides [shimming options](https://webpack.js.org/guides/shimming/).

* Use the [exports-loader](https://webpack.js.org/guides/shimming/#exports-loader) to
add a module export to components which expect a symbol to be global.
* Use the [imports-loader](https://webpack.js.org/guides/shimming/#imports-loader) when a script
expects the `this` keyword to reference `window`.
* Use the [ProvidePlugin](https://webpack.js.org/guides/shimming/#provideplugin) to add a module
import statement when a script expects a variable to be globally defined (but is now a module export).
* Use the [NormalModuleReplacementPlugin](https://webpack.js.org/plugins/normal-module-replacement-plugin/)
to have webpack swap a module-compliant version for a script.

You may need to apply multiple shimming techniques to the same component.

## Boostrapping Your Application

The webcomponent polyfills must be added in a specific order. If you do not delay loading the main bundle with your components, you will see the following exceptions in the browser console:
Expand Down
4 changes: 2 additions & 2 deletions appveyor.yml
Expand Up @@ -5,10 +5,10 @@ init:
- git config --global core.autocrlf input
environment:
matrix:
- nodejs_version: '8'
- nodejs_version: '12'
webpack_version: latest
job_part: test
- nodejs_version: '6'
- nodejs_version: '8'
webpack_version: latest
job_part: test
build: 'off'
Expand Down
10 changes: 10 additions & 0 deletions demo/.eslintrc
@@ -0,0 +1,10 @@
{
"extends": "webpack",
"env": {
"browser": true
},
"rules": {
"import/no-extraneous-dependencies": ["error", {"devDependencies": true}],
"import/extensions": "off"
}
}
19 changes: 0 additions & 19 deletions demo/bower.json

This file was deleted.

0 comments on commit b7dbd15

Please sign in to comment.