Skip to content

Commit bd5403c

Browse files
jakubmikitajakubmikita
committed
Merge branch 'release/1.1.2'
2 parents d5bc002 + c6196d1 commit bd5403c

17 files changed

+5531
-1858
lines changed

‎CHANGELOG.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,28 @@
11
# Changelog
22
All notable changes to this project will be documented in this file.
33

4-
## 1.0.0 - 12.02.2020
4+
## 1.1.2
5+
6+
* [Fixed] Webpack config
7+
* [Fixed] Security fixes
8+
9+
## 1.1.1
10+
11+
* [Added] Missing directory handling (displays warning about missing directory and processes the other)
12+
* [Fixed] Option to set `false` for a `scripts` or `styles` path is now working properly
13+
* [Fixed] isProduction constant is now defined based on cli args, not only NODE_ENV
14+
15+
## 1.1.0
16+
17+
* [Added] Images handling
18+
* [Changed] Paths configuration
19+
20+
## 1.0.1
21+
22+
* [Added] SourceMaps
23+
* [Added] Option tu turn off the DependencyExtractionWebpackPlugin
24+
* [Fixed] RemoveSuperflousAssetsPlugin fixed
25+
26+
## 1.0.0
527

628
Initial release

‎README.md

Lines changed: 148 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -38,50 +38,151 @@ However it is intended to use this module in the `scripts` section in the `packa
3838
"build": "mp-scripts build",
3939
"lint:js": "mp-scripts lint-js",
4040
"lint:style": "mp-scripts lint-style",
41-
"start": "mp-scripts start",
41+
"start": "mp-scripts start"
4242
}
4343
}
4444
```
4545

46+
### WordPress Dependencies
47+
48+
This package uses the [Dependency Extraction Webpack Plugin](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) to extract wordpress dependencies. It does two things:
49+
* Externalize dependencies that are available as script dependencies on modern WordPress sites.
50+
* Add an asset file for each entry point that declares an object with the list of WordPress script dependencies for the entry point. The asset file also contains the current version calculated for the current source code.
51+
52+
This plugin is enabled by default with default configuration but can be easyli turned off by passing `--no-deps` flag to your build script:
53+
``` json
54+
{
55+
"scripts": {
56+
"build": "mp-scripts build --no-deps",
57+
}
58+
}
59+
```
60+
61+
If you need to use this plugin with other configuration (for example you want it to generate `json` files instead `php` - see the plugin's documentation) you can extend webpack config. See [Advanced Usage](https://www.npmjs.com/package/@micropackage/scripts#%EF%B8%8F-advanced-usage) for more information.
62+
63+
### Using WordPress Dependencies
64+
65+
Let's assume we are creating a Gutenberg block. We want to import `Component` class and some Gutenberg components to use in our block. Entry file would be `custom-block.js`:
66+
```javascript
67+
import { Component } from '@wordpress/element';
68+
import { Button, CheckboxControl } from '@wordpress/components';
69+
70+
...
71+
```
72+
73+
While running `mp-scripts build` command the [Dependency Extraction Webpack Plugin](https://www.npmjs.com/package/@wordpress/dependency-extraction-webpack-plugin) will create additional php file containing an object with dependencies list and asset version. Note, that there is also no need to add imported packages to your `package.json` - since they are being externalized you don't need them in `node_modules`.
74+
The output files for this scenario are:
75+
* `custom-block.js`
76+
* `custom-block.asset.php`
77+
78+
Both files are located in the output directory.
79+
The php file will have the following content:
80+
```php
81+
<?php return array('dependencies' => array('wp-components', 'wp-element', 'wp-polyfill'), 'version' => 'e7e3b282b35389ecd440edc71e073e5d'); ?>
82+
```
83+
Note that `version` will change if your source changes.
84+
85+
Here is a simple example of usage:
86+
```php
87+
<?php
88+
add_action( 'enqueue_block_editor_assets', function() {
89+
$dir = plugin_dir_path( __FILE__ );
90+
$src = "{$dir}/dist/custom-block.js";
91+
$asset_file = "{$dir}/dist/custom-block.asset.php";
92+
93+
if ( file_exists( $src ) && file_exists( $asset_file ) ) {
94+
$asset_info = require $asset_file;
95+
96+
wp_enqueue_script(
97+
'custom-block',
98+
$src,
99+
$asset_info['dependencies'],
100+
$asset_info['version'],
101+
true
102+
);
103+
}
104+
} );
105+
?>
106+
```
107+
46108
## 📜 Available Scripts
47109

48110
### `build`
49-
Uses [webpack](https://webpack.js.org/) to transform your code. The default [webpack](https://webpack.js.org/) configuration scans entry directory and uses each file as an entry point. It is also possible to use css/scss files as entry points. Using [MiniCssExtractPlugin](https://github.com/[webpack](https://webpack.js.org/)-contrib/mini-css-extract-plugin) and a custom plugin for asset cleanup this will emit only css file for css/scss etry.
50-
All the params passed to this script will be passed forward to [webpack](https://webpack.js.org/). There are also params specific for this script:
111+
Uses [webpack](https://webpack.js.org/) to transform your code. By default it will scan the source paths to automatically create an entry point for each file. Subfolders are not scanned, also files which names start with underscore are skipped. Entry points can be js and (s)css files. Using [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin) and a custom plugin for asset cleanup this will emit only css file for (s)css entry.
112+
113+
This script can be configured using CLI arguments or by setting up a `mpScriptsConfig` property in the `package.json`.
114+
115+
All arguments other than listed below will be directly passed to [webpack](https://webpack.js.org/).
51116

52-
| Parameter | Default Value | Description |
53-
|------------------|---------------|----------------------------------------------------------------------------------------------------------|
54-
| **--entry-dir** | 'src/assets' | Directory in which to look for entries. |
55-
| **--output-dir** | 'dist' | Output directory.<br/>_**Note:** this is not the same as [webpack](https://webpack.js.org/)'s `--output-path`. See examples below._ |
56-
| **--js-dir** | 'js' | Scripts dir inside `--entry-dir` |
57-
| **--style-dir** | 'scss' | Style dir inside `--entry-dir` |
117+
#### Configuration
118+
119+
| Name | Argument | Type | Description |
120+
|-------------------|--------------------|--------------|-----------------------------------------------------------------------------------------------------------------|
121+
| **urlLoader** | -- | boolean\|number | Whether to use [url-loader](https://github.com/webpack-contrib/url-loader) for images. If number is passed it will be used as '[limit](https://github.com/webpack-contrib/url-loader#limit)' option.<br />**Default: `true`** |
122+
| **imagemin** | -- | boolean\|object | Whether to use [image-webpack-loader](https://github.com/tcoopman/image-webpack-loader) to optimize images with [imagemin](https://github.com/imagemin/imagemin). Object will be passed as [image-webpack-loader](https://github.com/tcoopman/image-webpack-loader) configuration.<br />**Default: `true`** |
123+
| **paths.src** | **--src-path** | string | Source path relative to project root.<br />**Default: `'src/assets'`** |
124+
| **paths.output** | **--output-path** | string | Output path relative to project root.<br />**Default: `'dist'`** |
125+
| **paths.scripts** | **--scripts-path** | string | Scripts path relative to `src\|output`. Use `false` to skip this path.<br />**Default: `'js'`** |
126+
| **paths.styles** | **--styles-path** | string | Styles path relative to `src\|output`. Use `false` to skip this path.<br />**Default: `'scss'`** |
127+
| **paths.images** | **--images-path** | string | Images path relative to `output`. Images included in scripts and styles will be placed in this location if `urlLoader` is turned off or the image size exceeds `limit`.<br />**Default: `'images'`** |
58128

59129
*Example:*
60130
```json
61131
{
62-
"scripts": {
63-
"build": "mp-scripts build",
64-
"build:custom": "mp-scripts build entry-one.js entry-two.js --output-path=custom",
65-
"build:other": "mp-scripts build --entry-dir=other/src --output-dir=other/dist --js-dir=scripts --style-dir=styles"
66-
}
132+
"mpScriptsConfig": {
133+
"urlLoader": 8192,
134+
"imagemin": {
135+
"svgo": {
136+
"plugins": [
137+
{ "removeDoctype": false }
138+
]
139+
}
140+
},
141+
"paths": {
142+
"src": "src/assets",
143+
"output": "dist",
144+
"scripts": "js",
145+
"styles": "scss",
146+
}
147+
}
148+
}
149+
```
150+
151+
#### Usage
152+
*Example:*
153+
```json
154+
{
155+
"scripts": {
156+
"build": "mp-scripts build",
157+
"build:dev": "mp-scripts build --mode=development",
158+
"build:custom": "mp-scripts build entry-one.js entry-two.js --output-path=custom",
159+
"build:other": "mp-scripts build --entry-path=other/src --output-path=other/dist --scripts-path=scripts --styles-path=styles"
160+
}
67161
}
68162
```
69163
How to use it:
70164
- `yarn build` - builds the code for production using entries from `src/assets/js` and `src/assets/scss`. Only files located directly in this folders will be used. All file names starting with `_` (underscore) are skipped. Output files will be placed inside `dist/js` and `dist/css` directories
71165
- `yarn build:custom` - builds the code for production with two entry points and a custom output folder. Paths for custom entry points are relative to the project root.
72166
- `yarn build:other` - this will work like the default build, but will look for entries inside `other/src/scripts` and `other/src/styles` directories. Output files will be placed inside `other/dist/scripts` and `other/dist/styles`.
73167

168+
#### Mode
169+
170+
By default `build` script will work in development mode. There are two ways to use another mode:
171+
* by adding `--mode` argument to your command
172+
* by setting NODE_ENV variable
173+
74174
### `lint-js`
75175
Lints your code using [eslint](https://eslint.org/).
76176
Default linting ruleset is [@wordpress/eslint-plugin/recommended](https://www.npmjs.com/package/@wordpress/eslint-plugin). This can be overwriten by placing an [eslint](https://eslint.org/) config file in your project or specifing `eslintConfig` field in a `package.json`.
77177

78178
*Example:*
79179
```json
80180
{
81-
"scripts": {
82-
"lint:js": "mp-scripts lint-js",
83-
"lint:js:src": "mp-scripts lint-js ./src"
84-
}
181+
"scripts": {
182+
"lint:js": "mp-scripts lint-js",
183+
"fix:js": "mp-scripts lint-js --fix",
184+
"lint:js:src": "mp-scripts lint-js ./src"
185+
}
85186
}
86187
```
87188

@@ -97,10 +198,11 @@ Uses [stylelint](https://stylelint.io/) to lint your style files.
97198
*Example:*
98199
```json
99200
{
100-
"scripts": {
101-
"lint:style": "mp-scripts lint-style",
102-
"lint:css:src": "mp-scripts lint-style 'src/**/*.css'"
103-
}
201+
"scripts": {
202+
"lint:style": "mp-scripts lint-style",
203+
"fix:style": "mp-scripts lint-style --fix",
204+
"lint:css:src": "mp-scripts lint-style 'src/**/*.css'"
205+
}
104206
}
105207
```
106208
How to use it:
@@ -110,14 +212,14 @@ How to use it:
110212
By default, files located in `dist`, `vendor` and `node_modules` folders are ignored.
111213

112214
### `start`
113-
This script works exactly like `build` but configured for development. It will also automatically rebuild if the code will change. All the params work the same as in `build` script.
215+
This script works exactly like `build` but configured for development. It will also automatically rebuild if the code will change. All the params work the same way as in `build` script.
114216

115217
*Example:*
116218
```json
117219
{
118220
"scripts": {
119221
"start": "mp-scripts start",
120-
"start:custom": "mp-scripts start --entry-dir=custom/src --output-dir=custom/build"
222+
"start:custom": "mp-scripts start --entry-path=custom/src --output-path=custom/build"
121223
}
122224
}
123225
```
@@ -126,13 +228,13 @@ This script works exactly like `build` but configured for development. It will a
126228

127229
This package ships with default config files for [eslint](https://eslint.org/), [stylelint](https://stylelint.io/) and [webpack](https://webpack.js.org/). Each config file can be overriden in your project.
128230

129-
### Extending [webpack](https://webpack.js.org/) config
231+
### Extending webpack config
130232

131233
To extend default [webpack](https://webpack.js.org/) config you can provide your own `webpack.config.js` file and `require` the provided `webpack.config.js` file. You can use spread operator to import parts of the config.
132234

133235
In the example below a webpack.config.js file is added to the root folder extending the provided [webpack](https://webpack.js.org/) config to include [url-loader](https://github.com/webpack-contrib/url-loader) for images:
134236
```javascript
135-
const defaultConfig = require( "@micropackage/scripts/config/[webpack](https://webpack.js.org/).config" );
237+
const defaultConfig = require( "@micropackage/scripts/config/webpack.config" );
136238

137239
module.exports = {
138240
...defaultConfig,
@@ -158,6 +260,26 @@ module.exports = {
158260
};
159261
```
160262

263+
### Run scripts in parallel or sequential
264+
265+
There are separate scripts to lint js and (s)css files, but it would be nice to have a single task to lint both. It can be accomplished using external modules, e.g. [npm-run-all](https://github.com/mysticatea/npm-run-all).
266+
Using this module ypu can define scripts which will run other scripts in parallel or sequential using `run-p` or `run-s` commands.
267+
```json
268+
{
269+
"scripts": {
270+
"lint:style": "mp-scripts lint-style",
271+
"lint:js": "mp-scripts lint-js",
272+
"fix:style": "mp-scripts lint-style --fix",
273+
"fix:js": "mp-scripts lint-js --fix",
274+
"lint": "run-p \"lint:*\"",
275+
"lint:fix": "run-p \"fix:*\"",
276+
}
277+
}
278+
```
279+
With the above config in your `package.json` you can run:
280+
* `yarn lint` - to run both `lint:style` and `lint:js` in parallel
281+
* `yarn lint:fix` - to run both `fix:style` and `fix:js` in parallel
282+
161283
## 📦 About the Micropackage project
162284

163285
Micropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.

‎bin/mp-scripts.js

Lines changed: 23 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -5,55 +5,45 @@
55
/**
66
* External dependencies
77
*/
8-
const spawn = require( 'cross-spawn' );
8+
const spawn = require("cross-spawn");
99

1010
/**
1111
* Internal dependencies
1212
*/
13-
const {
14-
getArgs,
15-
} = require( '../utils' );
16-
17-
const [ script, ...args ] = getArgs();
18-
19-
if ( ! [
20-
'build',
21-
'lint-js',
22-
'lint-style',
23-
'start',
24-
].includes( script ) ) {
25-
if ( undefined === script ) {
26-
console.log('No script specified.');
13+
const { getArgs } = require("../utils");
14+
15+
const [script, ...args] = getArgs();
16+
17+
if (!["build", "lint-js", "lint-style", "start"].includes(script)) {
18+
if (undefined === script) {
19+
console.log("No script specified.");
2720
} else {
2821
console.log('Unknown script "' + script + '".');
2922
}
30-
process.exit( 1 );
23+
process.exit(1);
3124
}
3225

3326
const { signal, status } = spawn.sync(
34-
'node',
35-
[
36-
require.resolve( '../scripts/' + script ),
37-
...args,
38-
],
39-
{ stdio: 'inherit' }
27+
"node",
28+
[require.resolve("../scripts/" + script), ...args],
29+
{ stdio: "inherit" }
4030
);
4131

42-
if ( signal ) {
43-
if ( signal === 'SIGKILL' ) {
32+
if (signal) {
33+
if (signal === "SIGKILL") {
4434
console.log(
45-
'The script failed because the process exited too early. ' +
46-
'This probably means the system ran out of memory or someone called ' +
47-
'`kill -9` on the process.'
35+
"The script failed because the process exited too early. " +
36+
"This probably means the system ran out of memory or someone called " +
37+
"`kill -9` on the process."
4838
);
49-
} else if ( signal === 'SIGTERM' ) {
39+
} else if (signal === "SIGTERM") {
5040
console.log(
51-
'The script failed because the process exited too early. ' +
52-
'Someone might have called `kill` or `killall`, or the system could ' +
53-
'be shutting down.'
41+
"The script failed because the process exited too early. " +
42+
"Someone might have called `kill` or `killall`, or the system could " +
43+
"be shutting down."
5444
);
5545
}
56-
process.exit( 1 );
46+
process.exit(1);
5747
}
5848

59-
process.exit( status );
49+
process.exit(status);

0 commit comments

Comments
 (0)