Any front-end file, non-PHP, is considered an asset in the framework; JavaScript, CSS, SASS, SCSS, LESS, fonts, images and views (templates) are examples of assets files.

Gulp is included out-of-the-box in the framework, to handle some compilation over styles and scripts, and to handle deployments. The following command must be executed in the command line (pointing at the project's root folder) to install all gulp dependencies:

npm install

Optimization and development are key factors that are empowered by the framework. Predefined gulp tasks will compile, minify and or concatenate raw assets for more efficiency.

All the CSS/JS/SASS files located under the folder [projects path]/assets/raw will be subjected to compilation and/or concatenation. Files wanted to have this treatment should be stored under the following subfolders:

• [...]/assets/raw/css: CSS files in this folder will be concatenated into one file called app.css and stored into [..]/assets/css.
  Subfolders under [...]/assets/raw/css will have all its CSS files concatenated into a single file with the same name and stored into [..]/assets/css, for example, all files in subfolder [...]/assets/raw/css/admin will be concatenated into [..]/assets/css/admin.css.
  
  
• [...]/assets/raw/js: JS files in this folder will be concatenated into one file called app.js and stored into [..]/assets/js.
  Subfolders under [...]/assets/raw/js will have all its JS files concatenated into a single file with the same name and stored into [..]/assets/js, for example, all files in subfolder [...]/assets/raw/js/admin will be concatenated into [..]/assets/js/admin.js.
  
  
• [...]/assets/raw/sass: SASS/SCSS files in this folder will be compiled (out-of-the-box) into one or multiple files (this will depend on the number of master files found) and stored into [..]/assets/css.

To compile the assets located in the raw folder run the following command in command-line:

gulp dev

The framework provides multiple watch tasks that can be used to auto-compile raw files upon changes:

Watch any change inside the raw folder

gulp watch

Watch only raw style changes (CSS/SASS/SCSS)

gulp watch-styles

Watch only raw sass changes (SASS/SCSS)

gulp watch-sass

Watch only raw JS changes

gulp watch-js

By default, the generated files, app.css and app.js (compiled from raw assets), will be auto-enqueued into WordPress. Auto-enqueue settings can be modified at the configuration file.

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'css/app.css',
                                'dep'       => [],
                                'footer'    => false,
                            ],
                            [
                                'asset'     => 'js/app.js',
                                'dep'       => [],
                                'footer'    => true,
                            ],
                        ],
    ],
    // more settings....,
];

In the example above, auto-enqueue is enabled, app.css and app.js are set to be enqueued into WordPress. Each asset has additional settings, dep is an array used to define dependencies and footer is the flag the indicates if the asset should be loaded in the <header> or in the <footer> of the HTML document.

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'js/app.js',
                                'dep'       => [],
                                'footer'    => true,
                                'enqueue'   => false,
                            ],
                        ],
    ],
    // more settings....,
];

The example above will only register the asset js/app.js in WordPress, this file will not be auto-enqueued into the system, to enqueue it you must use the function wp_enqueue_script.

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'js/admin.js',
                                'dep'       => [],
                                'footer'    => true,
                                'is_admin'  => true,
                            ],
                        ],
    ],
    // more settings....,
];

The example above will auto-enqueue the asset js/admin.js into WordPress admin dashboard.

Additional and custom asset files can be auto-enqueued as well, see the following example:

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'js/custom.js',
                                'dep'       => ['jquery'],
                                'footer'    => true,
                            ],
                        ],
    ],
    // more settings....,
];

The asset file identifier in WordPress is the name of the file (in lowercase, without the minified .min indication, and without the extension), a dash and the lowercased namespace is appended at the end. For example, if the file name is bootstrap.min.css then the identifier will be bootstrap-mynamespace.

The identifier can be used to indicate file dependency and load order. See the following example:

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'js/bootstrap.min.js',
                                'dep'       => ['jquery'],
                                'footer'    => true,
                            ],
                            [
                                'asset'     => 'js/app.js',
                                'dep'       => ['jquery', 'bootstrap-mynamespace'],
                                'footer'    => true,
                            ],
                        ],
    ],
    // more settings....,
];

Optionally, a file ID (used for dependencies) and a version can be indicated as well:

return [
    // more settings....,
    'autoenqueue' => [
        // Enables or disables auto-enqueue of assets
        'enabled'       => true,
        // Assets to auto-enqueue
        'assets'        => [
                            [
                                'asset'     => 'js/bootstrap.min.js',
                                'id'        => 'bootstrap',
                                'dep'       => ['jquery'],
                                'version'   => '4.3.0',
                                'footer'    => true,
                            ],
                            [
                                'asset'     => 'js/app.js',
                                'dep'       => ['jquery', 'bootstrap'],
                                'footer'    => true,
                            ],
                        ],
    ],
    // more settings....,
];

To compile the assets for production, remove unneeded files, development only, and compress the project for installation (ZIP file), run the following command in command-line:

gulp build

There are certain instances when you don't need to compress and generate a versioned ZIP file, for instance when implementing Continuous Delivery or Automated Deployments. The following command will build a deployment version of the project into the folder [project]/builds/deploy:

gulp deploy

Call the functions assets_url() or assets_path() to get the URL or path of an asset. See the following examples:

<div class="assets-url function sample">
    
    <img src="<?php echo assets_url( 'img/my-logo.png', __FILE__ ) ?>" />
    
</div>

$path = assets_path( 'img/my-logo.png', __FILE__ ) ?>

WPMVC will detect if the project has a Webpack configuration (file webpack.config.js at the root folder), if so, it will add the task webpack and will include it in the build process.

The following script line needs to be added to package.json:

{
  "scripts": {
    "webpack": "webpack --hide-modules"
  },
}

When WPMVC detects the webpack.config.js  file it will execute the script line above.

Webpack is not included as a dependency, it will need to be installed using npm.

npm install webpack --save