Skip to content

Latest commit

 

History

History
230 lines (186 loc) · 6.16 KB

README.md

File metadata and controls

230 lines (186 loc) · 6.16 KB

@kunoichi/grab-deps

A toolset to extract dependencies information from js/css files in WordPress Development.

TEST

This library dump wp-dependencies.json which includes dependencies and path information about js/css.

  • You don't have to specify dependencies from php files.
  • You can automate the registration & enqueue of assets.

Installation

npm install @kunoichi/grab-deps

Usage

Suppose that the directory structure of your theme/plugin is like below:

assets
- js
  - main.js
- css
  - style.css

And run this in your npm scripts or gulpfile.js.

NPM Scripts

Since version 2.0.0, CLI inter face is available. If you need traspiling JavaScripts with @wordpress/scripts, add dependencies.

{
	"dependencies": {
		"@kunoichi/grab-deps": "^2.0.0",
		"@wordpress/sripts": "^27.0.0"
	},
	"scripts": {
	"dump": "grab-deps dump assets",
	"transpile": "grab-deps js src/js assets/js"
  }
}

grab-deps-image 'test/src/images/**/*.{jpg,png,gif,svg}' test/dist/images is also available. See peer dependencies for more information.

Gulp

// gulpfile.js
const gulp = require( 'gulp' );
const { dumpSetting } = require('@kunoichi/grab-deps');

// Dump task.
gulp.task( 'dump', function( done ) {
  dumpSetting( 'assets' );
  done();
} );

// Watch assets directory.
gulp.task( 'watch', function () {
  // Watch assets change and dump.
  gulp.watch( [ 'assets/**/*.css', 'assets/**/*.js' ], gulp.task( 'dump' ) );
} );

Now you can get updated dump information whatever changes you made for assets directory.

Register Assets in WordPress

Suppose that you have assets/js/app.js in your theme folder. Add @params in license comment.

/*!
 * My Plugin main JS
 * 
 * @handle my-plugin-app
 * @version 2.1.0
 * @footer false
 * @deps jquery, jquery-masonry, wp-i18n
 */
console.log( 'This script runs jQuery Masonry.' );

And you can get setting file wp-dependencies.json like this.

[
  {
    "handle": "my-plugin",
    "version": "2.1.0",
    "path": "assets/js/app.js",
    "hash": "5e84fd5b5817a6397aeef4240afeb97a",
    "deps": [ "jquery", "jquery-masonry", "wp-i18n" ],
    "ext": "js",
    "footer": true,
    "media": "all"
  }
]

Now you can bulk register assets through php.

// This code is in your theme's functions.php
add_action( 'init', function() {
    // Load setting as array.
    $settings = json_decode( file_get_contents( __DIR__ . '/wp-dependencies.json' ), true );
    // Register each setting.
    foreach ( $settings as $setting ) {
        $handle  = $setting['handle'];
        $version = $setting['hash']; // You can also specify @version
        $url     = get_template_directory_uri() . '/' . $setting['path'];
        if ( 'js' === $setting['ext'] ) {
            // Register JavaScript.
            $script_setting = [
            	'in_footer' => $setting['footer'],
            ];
            if ( in_array( $setting['strategy'], [ 'async', 'defer' ], true ) ) {
            	$script_setting['strategy'] = $setting['strategy'];
            }
            wp_register_script( $handle, $url, $deps, $version, $setting['footer'] );
            // You can do extra settings here.
        } else {
            // This is CSS.
            wp_register_style( $handle, $url, $deps, $version, $setting['media'] ); 
        }
    }
} );

Now you can enqueue any of your scripts/styles with wp_enqueue_script( 'my-app-js' ) or wp_enqueue_style( 'my-blocks-alert-css' ).

Supported Header Info

Name Default type Target Possible Values
@version 0.0.0 String both 1.0.0
@handle Base file name without extension String both my-script
@deps Empty Array both [jquery, my-js]
@footer True Boolean js true or false
@strategy Empty String css defer,async
@media all String css screen, print
@cssmedia Same as @media. Avoid media query. String css screen, print

Tip

  1. All file will have hash property. This is md5 hash of file content and is useful and handy for version argument of wp_register_(script|style).
  2. If your CSS includes media query and grab-deps parsed it unintentionally, you can use @cssmedia to avoid it.

JSON Example

[
	{
		"path": "assets/js/app.js",
		"version": "0.0.0",
		"deps": [
			"jquery",
			"wp-api-fetch"
		],
		"hash": "900150983cd24fb0d6963f7d28e17f72",
		"strategy": "defer",
		"footer": true,
		"handle": "my-app"
	},
	{
		"path": "assets/css/style.css",
		"version": "0.0.0",
		"deps": [ "bootstrap" ],
		"hash": "900150983cd24fb0d6963f7d28e17f72",
		"media": "screen",
		"handle": "my-style"
	}
]

License text

Nowadays, some compilers/transpilers like webpack extract license comments. If original is like below:

/*!
 * Main app file.js
 *
 * @version 2.0.0
 */
console.log( 'Start rendering!' );

file.js will compiled like below:

console.log('Start rendering!');

And in same directory, file.js.LICENSE.txt will be exported.

/*!
 * Main app file.js
 *
 * @version 2.0.0
 */

In such case, @kunoichi/grab-deps will support .LISENCE.txt format by default. 3rd argument suffix of dumpSetting supports other format.

// If your JS license will be in `app.js.txt`,
// You can set suffix.
dumpSetting( 'assets', './wp-dependencies.json', '.txt' );
// If your licenses will be other format, specify function.
dumpSetting( 'assets', './wp-dependencies.json', function( path ) {
  // Convert path to your license.txt
  return licensePath;
} );

© 2019 TAROSKY