Home Reference Source

projext plugin for webpack

Travis Coveralls github David David

Allows projext to use webpack as a build engine.

Introduction

projext allows you to configure a project without adding specific settings for a module bundler, then you can decide which build engine to use. This plugin allows you to bundle your projext project targets using webpack.

Information

- -
Package projext-plugin-webpack
Description Allows projext to use webpack as a build engine.
Node Version >= v10.13.0

Usage

Since webpack is the default build engine for projext, after you install the plugin there's nothing else to do, just run the build command and the plugin will take care of the rest:

projext build [target-name]

In the case you changed the engine and you want to restore it to webpack, you just need to go to your projext configuration file, on your target settings, change engine to webpack:

// projext.config.js

module.exports = {
  targets: {
    myTarget: {
      type: 'browser',
      engine: 'webpack',
    },
  },
};

Middleware implementation

You can implement both the webpack-dev-middleware and the webpack-hot-middleware on Express and Jimpex very easy:

Express

// Require the function for the implementation
const useExpress = require('projext-plugin-webpack/express');

// Require Express to create a dummy app
const express = require('express');

// Create the app
const app = express();

// Tell the plugin to configure the necessary middlewares for the `myApp` target to be served by the
// `myServer` target
useExpress(app, 'myApp', 'myServer');

// Start the app
app.listen(...);

Jimpex

// Require the function for the implementation
const useJimpex = require('projext-plugin-webpack/jimpex');

// Require Jimpex to create a dummy app
const { Jimpex } = require('jimpex');

// Define the Jimpex app
class DevApp extends Jimpex {
  boot() {
    // This method needs to be created.
  }
}

// Create the app
const app = new DevApp();

// Tell the plugin to configure the necessary middlewares for the `myApp` target to be served by the
// `myServer` target
useJimpex(app, 'myApp', 'myServer');

// Start the app
app.start();

Accessing the dev middleware files

Both useExpress and useJimpex return and object with the following properties:

Extending/Overwriting the configuration

This plugin has 6 different configuration services:

They can be easily extended/overwritten by creating a file on your project with an specific name.

All the configurations receive a single object parameter with the following properties:

Base configuration

This is the top level configuration, the one a regular webpack.config.js file would export.

To extend/overwrite this configuration you would need to create a file with the following path: config/webpack/base.config.js. For example:

// config/webpack/base.config.js

module.exports = (params) => ({
  resolve: {
    extensions: ['.js', '.jsx', '.tsx'],
  },
});

Rules configuration

This is what you would normally found inside module.rules. It has all the rules to handle the different file types, based on a target type: If it's a Node target, it will only handle Javascript; but if the target is for browsers, it will also handle stylesheets, images and fonts.

To extend/overwrite this configuration you would need to create a file with the following path: config/webpack/rules.config.js. For example:

// config/webpack/rules.config.js

module.exports = (params) => ({
  rules: [{
    test: /\.tsx?$/i,
    use: [
      'babel-loader',
      'ts-loader',
    ],
  }]
});

Browser targets configuration for development and production

These configurations handles the specifics of a browser target: entry, output and plugins.

To extend/overwrite these configurations you would need to create a file with the following path: config/webpack/browser.development.config.js or config/webpack/browser.production.config.js. For example:

// config/webpack/browser.development.config.js

module.exports = (params) => ({
  devtool: 'eval',
});

Node targets configuration for development and production

These configurations handles the specifics of a Node target: entry, output and plugins.

To extend/overwrite these configurations you would need to create a file with the following path: config/webpack/node.development.config.js or config/webpack/node.production.config.js. For example:

// config/webpack/node.production.config.js

module.exports = (params) => ({
  node: {
    __filename: false,
  }
});

Extending/Overwriting a target configuration

The methods above allow you to extend/overwrite a configuration service for all the targets, but there are two ways of extending/overwriting configurations for an specific target:

config/webpack/[target].config.js

This file allows you to overwrite the webpack configuration generated for an specific target, no matter the build type:

// config/webpack/myApp.config.js

module.exports = (params) => ({
  node: {
    __filename: false,
  }
});

That change will only be applied when building the target myApp.

config/webpack/[target].[build-type].config.js

This file allows you to overwrite the webpack configuration generated for an specifc target and build type.

// config/webpack/myApp.production.config.js

module.exports = (params) => ({
  devtool: 'eval',
});

That change will only be applied when building the target myApp on a production build.

Images optimization

By default, this plugin used to include image-webpack-loader but the package wasn't being updated often and the requirement of libpng was something that caused issues for some of the users' environments.

Now, this plugin only uses the loader if the implementation has image-webpack-loader on its package.json dependencies/devDependencies.

Making a plugin

If you want to write a plugin that works with this one (like a framework plugin), there are a lot of reducer events you can listen for and use to modify the webpack configuration:

Configuration parameters

This is called before generating any configuration.

Node target configuration

This is called after generating the configuration for a Node target and before using it.

Browser target configuration

This is called after generating the configuration for a browser target and before using it.

Rules configuration

This is called after defining all the rules for a target and before sending them to the main configuration.

Node target rules configuration

This is called after defining all the rules for a Node target and before sending them to the main configuration.

Browser target rules configuration

This is called after defining all the rules for a browser target and before sending them to the main configuration.

Node target Javascript rules configuration

This is called after defining all Javascript files rules for a Node target and before sending them to the main rules configuration.

Browser target Javascript rules configuration

This is called after defining all Javascript files rules for a browser target and before sending them to the main rules configuration.

Browser target SCSS stylesheets rules configuration

This is called after defining all SCSS stylesheets files rules for a browser target and before sending them to the main rules configuration.

Browser target CSS stylesheets rules configuration

This is called after defining all CSS stylesheets files rules for a browser target and before sending them to the main rules configuration.

Browser target HTML rules configuration

This is called after defining all HTML files rules for a browser target and before sending them to the main rules configuration.

Browser target fonts rules configuration

This is called after defining all font files rules for a browser target and before sending them to the main rules configuration.

The supported formats are:

Browser target images rules configuration

This is called after defining all images files rules for a browser target and before sending them to the main rules configuration.

It excludes all images which path matches with favicon, as the favicon needs to be on the root directory in order to be automatically detected by the browser.

The supported formats are:

Browser target favicons rules configuration

This is called after defining all favicons files rules for a browser target and before sending them to the main rules configuration.

The reason this is not included with the images rules is because favicons need to be on the roto directory in order to be automatically detected by the browser, and they can only be ico and png.

Node target development configuration

This is called after generating the configuration for a Node target development build and before sending it to the main configuration to merge everything.

Node target production configuration

This is called after generating the configuration for a Node target production build and before sending it to the main configuration to merge everything.

Browser target development configuration

This is called after generating the configuration for a browser target development build and before sending it to the main configuration to merge everything.

Browser target production configuration

This is called after generating the configuration for a browser target production build and before sending it to the main configuration to merge everything.

Development

NPM/Yarn Tasks

Task Description
yarn test Run the project unit tests.
yarn run lint Lint the modified files.
yarn run lint:full Lint the project code.
yarn run docs Generate the project documentation.
yarn run todo List all the pending to-do's.

Testing

I use Jest with Jest-Ex to test the project. The configuration file is on ./.jestrc, the tests and mocks are on ./tests and the script that runs it is on ./utils/scripts/test.

Linting

I use ESlint to validate all our JS code. The configuration file for the project code is on ./.eslintrc and for the tests on ./tests/.eslintrc (which inherits from the one on the root), there's also an ./.eslintignore to ignore some files on the process, and the script that runs it is on ./utils/scripts/lint.

Documentation

I use ESDoc to generate HTML documentation for the project. The configuration file is on ./.esdocrc and the script that runs it is on ./utils/scripts/docs.

To-Dos

I use @todo comments to write all the pending improvements and fixes, and Leasot to generate a report. The script that runs it is on ./utils/scripts/todo.