Skip to content
This repository has been archived by the owner on Sep 9, 2021. It is now read-only.

Commit

Permalink
docs(README): standardize (#82)
Browse files Browse the repository at this point in the history
  • Loading branch information
@michael-ciniawsky
michael-ciniawsky authored Oct 14, 2017
1 parent d914288 commit a9ec386
Showing 1 changed file with 143 additions and 63 deletions.
206 changes: 143 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,99 +1,157 @@
[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![test][test]][test-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]

<div align="center">
<a href="https://github.com/webpack/webpack">
<img width="200" height="200" hspace="25" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg">
<img width="200" height="200" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon.svg">
</a>
<h1>Worker Loader</h1>
<p>This loader registers the script as <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API">Web Worker</a>.<p>
<p>This loader registers the script as <a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API">Web Worker</a><p>
</div>


<h2 align="center">Install</h2>

```bash
npm i -D worker-loader
```

or
<h2 align="center"><a href="https://webpack.js.org/concepts/loaders">Usage</a></h2>

```bash
yarn add worker-loader --dev
### `Inline`

**App.js**
```js
import Worker from 'worker-loader!./Worker.js'
```

<h2 align="center"><a href="https://webpack.js.org/concepts/loaders">Usage</a></h2>
### `Config`

**webpack.config.js**
```js
{
module: {
rules: [
{
test: /\.worker\.js$/,
use: { loader: 'worker-loader' }
}
]
}
}
```

**App.js**
```js
import Worker from './file.worker.js'

const worker = new Worker()

worker.postMessage({ a: 1 })
worker.onmessage = function (event) {}

worker.addEventListener("message", function (event) {})
```

<h2 align="center">Options</h2>

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`name`**|`{String}`|`[hash].worker.js`|Set a custom name for the output script|
|**`inline`**|`{Boolean}`|`false`|Inline the worker as a BLOB|
|**`fallback`**|`{Boolean}`|`false`|Require a fallback for non-worker supporting environments|

Import the worker file:
### `name`

``` javascript
// main.js
var MyWorker = require("worker-loader!./file.js");
To set a custom name for the output script, use the `name` parameter. The name may contain the string `[hash]`, which will be replaced with a content dependent hash for caching purposes

var worker = new MyWorker();
worker.postMessage({a: 1});
worker.onmessage = function(event) {...};
worker.addEventListener("message", function(event) {...});
*webpack.config.js**
```js
{
loader: 'worker-loader',
options: { name: 'WorkerName.[hash].js' }
}
```

You can also inline the worker as a blob with the `inline` parameter:
``` javascript
var MyWorker = require("worker-loader?inline!./myWorker.js");
### `inline`

You can also inline the worker as a BLOB with the `inline` parameter

**webpack.config.js**
```js
{
loader: 'worker-loader',
options: { inline: true }
}
```

Inline mode will also create chunks for browsers without supporting of inline workers,
to disable this behavior just set `fallback` parameter as `false`:
> ℹ️ Inline mode will also create chunks for browsers without support for inline workers, to disable this behavior just set `fallback` parameter as `false`
``` javascript
var MyWorker = require("worker-loader?inline&fallback=false!./myWorker.js");
**webpack.config.js**
```js
{
loader: 'worker-loader'
options: { inline: true, fallback: false }
}
```

To set a custom name for the output script, use the `name` parameter. The name may contain the string `[hash]`,
which will be replaced with a content-dependent hash for caching purposes. For example:
### `fallback`

Require a fallback for non-worker supporting environments

``` javascript
var MyWorker = require("worker-loader?name=outputWorkerName.[hash].js!./myWorker.js");
**webpack.config.js**
```js
{
loader: 'worker-loader'
options: { fallback: false }
}
```

<h2 align="center">Examples</h2>

The worker file can import dependencies just like any other file:
The worker file can import dependencies just like any other file

``` javascript
// file.js
var _ = require('lodash')
**Worker.js**
```js
const _ = require('lodash')

var o = {foo: 'foo'}
const obj = { foo: 'foo' }

_.has(o, 'foo') // true
_.has(obj, 'foo')

// Post data to parent thread
self.postMessage({foo: 'foo'})
self.postMessage({ foo: 'foo' })

// Respond to message from parent thread
self.addEventListener('message', function(event){ console.log(event); });
self.addEventListener('message', (event) => console.log(event))
```

You can even use ES6 modules if you have the babel-loader configured:
### `Integrating with ES2015 Modules`

> ℹ️ You can even use ES2015 Modules if you have the [`babel-loader`](https://github.com/babel/babel-loader) configured.
``` javascript
// file.js
**Worker.js**
```js
import _ from 'lodash'

let o = {foo: 'foo'}
const obj = { foo: 'foo' }

_.has(o, 'foo') // true
_.has(obj, 'foo')

// Post data to parent thread
self.postMessage({foo: 'foo'})
self.postMessage({ foo: 'foo' })

// Respond to message from parent thread
self.addEventListener('message', (event) => { console.log(event); });
self.addEventListener('message', (event) => console.log(event))
```

### Integrating with TypeScript
### `Integrating with TypeScript`

To integrate with TypeScript, you will need to define a custom module for the exports of your worker:
To integrate with TypeScript, you will need to define a custom module for the exports of your worker

**typings/custom.d.ts**
```ts
Expand All @@ -106,25 +164,27 @@ declare module "worker-loader!*" {
}
```

**myWorker.ts**
**Worker.ts**
```ts
const ctx: Worker = self as any;

// Post data to parent thread
ctx.postMessage({foo: "foo"})
ctx.postMessage({ foo: "foo" });

// Respond to message from parent thread
ctx.addEventListener("message", (event) => { console.log(event); });
ctx.addEventListener("message", (event) => console.log(event));
```

**main.ts**
**App.ts**
```ts
import MyWorker = require("worker-loader!./myWorker");
import MyWorker = require("worker-loader!./Worker");

const worker = new MyWorker();
worker.postMessage({a: 1});
worker.onmessage = (event) => {...};
worker.addEventListener("message", (event) => {...});

worker.postMessage({ a: 1 });
worker.onmessage = (event) => {};

worker.addEventListener("message", (event) => {});
```

<h2 align="center">Maintainers</h2>
Expand All @@ -133,25 +193,39 @@ worker.addEventListener("message", (event) => {...});
<tbody>
<tr>
<td align="center">
<a href="https://github.com/sokra">
<img width="150" height="150" src="https://github.com/sokra.png?s=150">
<a href="https://github.com/TrySound">
<img width="150" height="150" src="https://avatars3.githubusercontent.com/u/5635476?v=3&s=150">
</a>
<br />
<a href="https://github.com/sokra">Tobias Koppers</a>
<a href="https://github.com/TrySound">Bogdan Chadkin</a>
</td>
<td align="center">
<a href="https://github.com/bebraw">
<img width="150" height="150" src="https://github.com/bebraw.png?v=3&s=150">
</br>
Juho Vepsäläinen
</a>
</td>
<td align="center">
<a href="https://github.com/d3viant0ne">
<img width="150" height="150" src="https://avatars2.githubusercontent.com/u/8420490?v=3&s=150">
<img width="150" height="150" src="https://github.com/d3viant0ne.png?v=3&s=150">
</br>
Joshua Wiens
</a>
<br />
<a href="https://github.com/d3viant0ne">Joshua Wiens</a>
</td>
<td align="center">
<a href="https://github.com/TrySound">
<img width="150" height="150" src="https://avatars3.githubusercontent.com/u/5635476?v=3&s=150">
<a href="https://github.com/michael-ciniawsky">
<img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
</br>
Michael Ciniawsky
</a>
</td>
<td align="center">
<a href="https://github.com/evilebottnawi">
<img width="150" height="150" src="https://github.com/evilebottnawi.png?v=3&s=150">
</br>
Alexander Krasnoyarov
</a>
<br />
<a href="https://github.com/TrySound">Bogdan Chadkin</a>
</td>
</tr>
<tbody>
Expand All @@ -161,11 +235,17 @@ worker.addEventListener("message", (event) => {...});
[npm]: https://img.shields.io/npm/v/worker-loader.svg
[npm-url]: https://npmjs.com/package/worker-loader

[node]: https://img.shields.io/node/v/cache-loader.svg
[node-url]: https://nodejs.org

[deps]: https://david-dm.org/webpack-contrib/worker-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/worker-loader

[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack

[test]: http://img.shields.io/travis/webpack-contrib/worker-loader.svg
[test-url]: https://travis-ci.org/webpack-contrib/worker-loader

[cover]: https://codecov.io/gh/webpack-contrib/cache-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/cache-loader

[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
[chat-url]: https://gitter.im/webpack/webpack

0 comments on commit a9ec386

Please sign in to comment.