@micropackage/scripts
v1.2.5
Published
Reusable scripts for (not only) WordPress development.
Downloads
277
Maintainers
Readme
Scripts
🧬 About Scripts
This is a collection of scripts useful for (not only) WordPress development. Inspired by @wordpress/scripts, this package contianis essential tools with default configuration.
💾 Installation
You only need to install one module:
npm install @micropackage/scripts --save-dev
or
yarn add -D @micropackage/scripts
🕹 Usage
This package exposes a binary called mp-scripts
which can be called directly with npx
or yarn
.
npx mp-scripts build
yarn mp-scripts build
However it is intended to use this module in the scripts
section in the package.json
file of our project.
{
"scripts": {
"build": "mp-scripts build",
"lint:js": "mp-scripts lint-js",
"lint:style": "mp-scripts lint-style",
"start": "mp-scripts start"
}
}
WordPress Dependencies
This package uses the Dependency Extraction Webpack Plugin to extract wordpress dependencies. It does two things:
- Externalize dependencies that are available as script dependencies on modern WordPress sites.
- 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.
This plugin is enabled by default with default configuration but can be easyli turned off by passing --no-deps
flag to your build script:
{
"scripts": {
"build": "mp-scripts build --no-deps",
}
}
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 for more information.
Using WordPress Dependencies
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
:
import { Component } from '@wordpress/element';
import { Button, CheckboxControl } from '@wordpress/components';
...
While running mp-scripts build
command the 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
.
The output files for this scenario are:
custom-block.js
custom-block.asset.php
Both files are located in the output directory. The php file will have the following content:
<?php return array('dependencies' => array('wp-components', 'wp-element', 'wp-polyfill'), 'version' => 'e7e3b282b35389ecd440edc71e073e5d'); ?>
Note that version
will change if your source changes.
Here is a simple example of usage:
<?php
add_action( 'enqueue_block_editor_assets', function() {
$dir = plugin_dir_path( __FILE__ );
$src = "{$dir}/dist/custom-block.js";
$asset_file = "{$dir}/dist/custom-block.asset.php";
if ( file_exists( $src ) && file_exists( $asset_file ) ) {
$asset_info = require $asset_file;
wp_enqueue_script(
'custom-block',
$src,
$asset_info['dependencies'],
$asset_info['version'],
true
);
}
} );
?>
📜 Available Scripts
build
Uses webpack 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 and a custom plugin for asset cleanup this will emit only css file for (s)css entry.
This script can be configured using CLI arguments or by setting up a mpScriptsConfig
property in the package.json
.
All arguments other than listed below will be directly passed to webpack.
Configuration
| Name | Argument | Type | Description |
|-------------------|--------------------|--------------|-----------------------------------------------------------------------------------------------------------------|
| inlineAssets | true | boolean|number | Whether to use url-loader for images. If number is passed it will be used as 'limit' option.Default: true
|
| imagemin | -- | boolean|object | Whether to use image-webpack-loader to optimize images with imagemin. Object will be passed as image-webpack-loader configuration.Default: true
|
| paths.src | --src-path | string | Source path relative to project root.Default: 'src/assets'
|
| paths.output | --output-path | string | Output path relative to project root.Default: 'dist'
|
| paths.scripts | --scripts-path | string | Scripts path relative to src\|output
. Use false
to skip this path.Default: 'js'
|
| paths.styles | --styles-path | string | Styles path relative to src\|output
. Use false
to skip this path.Default: 'scss'
|
| paths.images | --images-path | string | Images path relative to output
. Images included in scripts and styles will be placed in this location if inlineAssets
is turned off or the image size exceeds limit
.Default: 'images'
|
| paths.fonts | --fonts-path | Fonts | Fonts path relative to output
. Font files included in scripts and styles will be placed in this location.Default: 'fonts'
|
Example:
{
"mpScriptsConfig": {
"inlineAssets": 8192,
"imagemin": {
"svgo": {
"plugins": [
{ "removeDoctype": false }
]
}
},
"paths": {
"src": "src/assets",
"output": "dist",
"scripts": "js",
"styles": "scss",
}
}
}
Usage
Example:
{
"scripts": {
"build": "mp-scripts build",
"build:dev": "mp-scripts build --mode=development",
"build:custom": "mp-scripts build entry-one.js entry-two.js --output-path=custom",
"build:other": "mp-scripts build --entry-path=other/src --output-path=other/dist --scripts-path=scripts --styles-path=styles"
}
}
How to use it:
yarn build
- builds the code for production using entries fromsrc/assets/js
andsrc/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 insidedist/js
anddist/css
directoriesyarn 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.yarn build:other
- this will work like the default build, but will look for entries insideother/src/scripts
andother/src/styles
directories. Output files will be placed insideother/dist/scripts
andother/dist/styles
.
Mode
By default build
script will work in development mode. There are two ways to use another mode:
- by adding
--mode
argument to your command - by setting NODE_ENV variable
lint-js
Lints your code using eslint.
Default linting ruleset is @wordpress/eslint-plugin/recommended. This can be overwriten by placing an eslint config file in your project or specifing eslintConfig
field in a package.json
.
Example:
{
"scripts": {
"lint:js": "mp-scripts lint-js",
"fix:js": "mp-scripts lint-js --fix",
"lint:js:src": "mp-scripts lint-js ./src"
}
}
How to use it:
yarn lint:js
- lints JavaScript files in the entire project’s directories.yarn lint:js:src
- lints JavaScript files in the project’s src subfolder’s directories.
By default, files located in dist
, vendor
and node_modules
folders are ignored.
lint-style
Uses stylelint to lint your style files.
Example:
{
"scripts": {
"lint:style": "mp-scripts lint-style",
"fix:style": "mp-scripts lint-style --fix",
"lint:css:src": "mp-scripts lint-style 'src/**/*.css'"
}
}
How to use it:
yarn lint:style
- lints CSS and SCSS files in the entire project’s directories.yarn lint:css:src
- lints only CSS files in the project’s src subfolder’s directories.
By default, files located in dist
, vendor
and node_modules
folders are ignored.
start
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.
Example:
{
"scripts": {
"start": "mp-scripts start",
"start:custom": "mp-scripts start --entry-path=custom/src --output-path=custom/build"
}
}
🕵️ Advanced Usage
This package ships with default config files for eslint, stylelint and webpack. Each config file can be overriden in your project.
Extending webpack config
To extend default webpack 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.
In the example below a webpack.config.js file is added to the root folder extending the provided webpack config to include url-loader for images:
const defaultConfig = require( "@micropackage/scripts/config/webpack.config" );
module.exports = {
...defaultConfig,
module: {
...defaultConfig.module,
rules: [
...defaultConfig.module.rules,
{
test: /\.(png|jpg|gif)$/i,
use: [
{
loader: 'url-loader',
options: {
limit: 8192,
name: '[name].[ext]',
outputPath: 'images',
},
},
],
},
],
},
};
Run scripts in parallel or sequential
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.
Using this module ypu can define scripts which will run other scripts in parallel or sequential using run-p
or run-s
commands.
{
"scripts": {
"lint:style": "mp-scripts lint-style",
"lint:js": "mp-scripts lint-js",
"fix:style": "mp-scripts lint-style --fix",
"fix:js": "mp-scripts lint-js --fix",
"lint": "run-p \"lint:*\"",
"lint:fix": "run-p \"fix:*\"",
}
}
With the above config in your package.json
you can run:
yarn lint
- to run bothlint:style
andlint:js
in parallelyarn lint:fix
- to run bothfix:style
andfix:js
in parallel
📦 About the Micropackage project
Micropackages - as the name suggests - are micro packages with a tiny bit of reusable code, helpful particularly in WordPress development.
The aim is to have multiple packages which can be put together to create something bigger by defining only the structure.
Micropackages are maintained by BracketSpace.
📖 Changelog
📃 License
GNU General Public License (GPL) v3.0. See the LICENSE file for more information.