Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation #59

Open
wants to merge 8 commits into
base: develop
Choose a base branch
from
Open

Documentation #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
170ad16
docs(webpack-quark-asset): document for asset quark
c3dr0x Dec 24, 2018
0ef8562
docs(webpack-quark-babel): document for babel quark
c3dr0x Dec 25, 2018
f20ed73
docs(webpack-quark-css): document for css quark
c3dr0x Dec 25, 2018
e167518
docs(webpack-quark-entry): document for entry quark
c3dr0x Dec 25, 2018
7fd3bb9
docs(webpack-quark-dev-server): document for dev server quark
c3dr0x Dec 27, 2018
211af52
docs(webpack-quark-html): document for html quark
c3dr0x Dec 27, 2018
3632afe
docs(webpack-quark-optimize): document for optimize quark
c3dr0x Dec 29, 2018
fa3d8c7
docs: fixes mistakes on packages name, and links
Hartorn Jan 6, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 64 additions & 3 deletions packages/quarks/webpack-quark-assets/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,72 @@
# `@thc/webpack-quark-assets`

> TODO: description
This quark intends to handle asset dependencies.

It is based on both `file-loader` and `url-loader`.
All basic files will be put into a `misc/` folder using `file-loader`.
Whereas images and fonts will be inlined if under 1000 bytes or put in respective `img/` and `font/` folders using `url-loader`.

## Usage

Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-assets`

Example in `webpack.config.js` :

```js
"use strict";

const withAssets = require("@thc/webpack-quark-assets");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(env, argv, withAssets());

return configurator();
};
```
const webpackQuarkAssets = require('@thc/webpack-quark-assets');

// TODO: DEMONSTRATE API
## Options

| property | type | required | default | description |
| --------------- | -------- | -------- | ------------------------------------------ | -------------------------------------------------------- |
| handleDefault | boolean | | `true` | if should add a default file loader |
| defaultsExclude | string[] | | `[/\.ejs$/, /\.js$/, /\.css$/, /\.json$/]` | list of excluded files extension for default file loader |
| miscName | string | | `misc/[name]_[sha512:hash:base64:7].[ext]` | name for output files |
| assets | object[] | | see below, Assert format | special care for specific formats using url loader |

Asset format

| property | type | required | default | description |
| -------- | ------ | -------- | ------- | --------------------------------------- |
| test | string | | | regex like to match files |
| limit | number | | 1000 | number bytes limit for inlining content |
| name | string | | | name for output files |

Will by default handle images and fonts like :

```js
assets: [
{
test: /\.(ttf|eot|woff|woff2|svg)(\?.*)?$/,
limit: 10000,
name: "fonts/[name]_[sha512:hash:base64:7].[ext]"
},
{
test: /\.(png|jpg|jpeg|gif)(\?.*)?$/,
limit: 10000,
name: "img/[name]_[sha512:hash:base64:7].[ext]"
}
];
```

## References

- See [`file-loader`](https://github.com/webpack-contrib/file-loader)
- See [`url-loader`](https://github.com/webpack-contrib/url-loader)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
83 changes: 80 additions & 3 deletions packages/quarks/webpack-quark-babel/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,88 @@
# `@thc/webpack-quark-babel`

> TODO: description
This quark intends to handle the usage of babel to use better js using `babel-loader`.
It will add some more configuration to handle easily caching with `cache-loader` and multi-threading build using `thread-loader`.
It can be easily extended to handle framework like React (see [Recipes](#recipes))

## Usage

Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-babel`

Example in `webpack.config.js` :

```js
"use strict";

const withJs = require("@thc/webpack-quark-babel");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(env, argv, withJs());

return configurator();
};
```
const webpackQuarkBabel = require('@thc/webpack-quark-babel');

// TODO: DEMONSTRATE API
## Options

| property | type | required | default | description |
| ----------------- | -------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| useCache | boolean | | `true` | if should use cache, caution should be deactivated for build production |
| test | string | | `/\.js\$/` | file extension that loader should handle |
| exclude | string | | `/node_modules/` | glob that should be ignore by handler |
| extensions | string[] | | `[".js"]` | list of extensions handled by loader |
| babelOptions | object | | `{babelrc: true}` | options for babel |
| nbWorkers | number | | | number of workers to use |
| additionalLoaders | object[] | | [] | any additional loader to use, see [@thc/webpack-quark-typescript](https://github.com/thc-tools/webpack-laboratory/tree/master/packages/quarks/webpack-quark-typescript) |

## Recipes

### Usage for react

```js
"use strict";

const withJs = require("@thc/webpack-quark-babel");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);
const hotReload = env.HOT_RELOAD;

const configurator = createConfigurator(
env,
argv,
withJs({
test: /\.jsx?$/,
extensions: [".js", ".jsx"],
babelOptions: {
presets: [
[
"@thc/babel-preset-react",
{
mode: env.NODE_ENV,
hot: hotReload
}
]
],
babelrc: false
}
})
);

return configurator();
};
```

## References

- See [`babel-loader`](https://github.com/babel/babel-loader)
- See [`cache-loader`](https://github.com/webpack-contrib/cache-loader)
- See [`thread-loader`](https://github.com/webpack-contrib/thread-loader)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
48 changes: 44 additions & 4 deletions packages/quarks/webpack-quark-css/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,51 @@
# `@thc/webpack-quark-css`

> TODO: description
This quarks intends to handle your applicaiton style sheets.
It will use `css-loader` in addition to `postcss-loader` to load your resources.
Both loaders configuration can be easily extended with additionnal options or using a `postcss.config.js` file.
In addition if you set the `extractCss` option to `true` it will extract the css in an external file using `mini-css-extract-plugin`, otherwise `style-loader` adds it to your main output file (usually js).

## Usage

```
const webpackQuarkCss = require('@thc/webpack-quark-css');
Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-css`

Example in `webpack.config.js` :

```js
"use strict";

const withCss = require("@thc/webpack-quark-css");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(env, argv, withCss());

// TODO: DEMONSTRATE API
return configurator();
};
```

## Options

| property | type | required | default | description |
| ----------------- | -------- | -------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| test | string | | `/\.css$/` | glob to test extension |
| extractCss | boolean | | `false` | if should extract css in separate file, should be true for production build |
| filename | string | | `css/[name]_${processEnv.npm_package_version}.bundle.css` | pattern to generate output filename |
| chunkFilename | string[] | | `css/[name]_[hash].css` | pattern to generate chunk filename |
| postcssConfig | object | | | additionnal configuration for `postcss` |
| cssConfig | object | | | additionnal configuration for `css-loader` |
| additionalLoaders | object | | | additionanl loader, see [@thc/webpack-quark-scss](https://github.com/thc-tools/webpack-laboratory/tree/master/packages/quarks/webpack-quark-scss) |

## References

- See [`style-loader`](https://github.com/webpack-contrib/style-loader)
- See [`css-loader`](https://github.com/webpack-contrib/css-loader)
- See [`postcss-loader`](https://github.com/postcss/postcss-loader)
- See [`mini-css-extract-plugin`](https://github.com/webpack-contrib/mini-css-extract-plugin)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
40 changes: 36 additions & 4 deletions packages/quarks/webpack-quark-dev-server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,43 @@
# `@thc/webpack-quark-dev-server`

> TODO: description
This quarks intends to help with using hot reload

## Usage

```
const webpackQuarkHotReload = require('@thc/webpack-quark-dev-server');
Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-dev-server`

Example in `webpack.config.js` :

```js
"use strict";

const withHotReload = require("@thc/webpack-quark-dev-server");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(env, argv, withHotReload());

// TODO: DEMONSTRATE API
return configurator();
};
```

## Options

| property | type | required | default | description |
| ----------------------------------------- | ------- | -------- | ----------- | ------------------------------------- |
| hot | boolean | | `true` | if hot reload is active |
| serverConfig.\_\_DEV_SERVER_PROTOCOL\_\_ | string | | `http` | the rotocol to use: `http` or `https` |
| serverConfig.\_\_DEV_SERVER_HOST\_\_ | string | | `localhost` | the hostname use |
| serverConfig.\_\_DEV_SERVER_PORT\_\_ | string | | `3000` | the port to use |
| serverConfig.\_\_DEV_SERVER_SUBDOMAIN\_\_ | string | | | the subdomain to use |

## References

- See [`hot reload`](https://webpack.js.org/concepts/hot-module-replacement/)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
45 changes: 41 additions & 4 deletions packages/quarks/webpack-quark-entry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,48 @@
# `@thc/webpack-quark-entry`

> TODO: description
This quark intends to handle the entry feature of webpack.
It exposes special care for polyfill and entry enhancing capabilities.

## Usage

```
const webpackQuarkEntry = require('@thc/webpack-quark-entry');
Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-entry`

Example in `webpack.config.js` :

```js
"use strict";

const withEntry = require("@thc/webpack-quark-entry");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(
env,
argv,
withEntry({
entries: { main: "./src/app.js" }
})
);

// TODO: DEMONSTRATE API
return configurator();
};
```

## Options

| property | type | required | default | description |
| -------- | -------------------- | -------- | ------- | ------------------------------------------------------------------- |
| entries | object | x | | A key/value object containing entries point |
| polyfill | string[] | | | A special entry point for polyfills |
| enhance | (string) => string[] | | | An enhancer function to complete entries, eg: usefull for hotreload |

## References

- See [`webpack entry`](https://webpack.js.org/concepts/#entry)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
41 changes: 37 additions & 4 deletions packages/quarks/webpack-quark-html/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,44 @@
# `@thc/webpack-quark-html`

> TODO: description
This quarks intends to handle the booting of you application.
It will by default generate an `index.html` file with reference to all main outputs and chunks generated at build time.

When installing this module, a `template.ejs` will be added to your project.
It is the template that will be use to generate the `index.html` file.

## Usage

```
const webpackQuarkHtml = require('@thc/webpack-quark-html');
Just install it : `npm i --save-dev --save-exact @thc/webpack-chemistry @thc/webpack-quark-html`

Example in `webpack.config.js` :

```js
"use strict";

const withHtml = require("@thc/webpack-quark-html");
const { envDefaults, createConfigurator } = require("@thc/webpack-chemistry");

module.exports = (processEnv, argv) => {
const env = envDefaults(processEnv);

const configurator = createConfigurator(env, argv, withHtml());

// TODO: DEMONSTRATE API
return configurator();
};
```

## Options

| property | type | required | default | description |
| ------------------ | ------ | -------- | -------------- | ------------------------------------------------ |
| template | string | | `template.ejs` | the template path (from `webpack.config.js` dir) |
| templateParameters | object | | | an object with parameters for the template |

## References

- See [`html plugin`](https://webpack.js.org/plugins/html-webpack-plugin//)

## Rules

- Commit must follow [Conventional Commit convention](https://conventionalcommits.org/)
- [Pre-commit package](https://www.npmjs.com/package/pre-commit) should be use to enforce linting, tests validations, ...
Loading