@vkgp/webpack-core

WEBPACK Vanksen v2.0.1

Brand new front distribution to use JS6, TypeScript with new features and still compatible with old browsers.

Overview

Features

Feature	Informations
Webpack 4	Base functionnalities (compile, import/export behavior, create bundle etc...)
Babel	Mapped to .browserslinkrc to target desired output EcmaScript version
Typescript	TypeScript compiler, use babel after compilation (JS and TS consistency)
Sass	Transform your SCSS stylesheets to standard CSS
PostCSS	Concact and organize CSS, mapped with .browserslinkrc like Babel
Autoprefixer	Autoprefix your CSS for many browsers
CSSNano	Minify your CSS (minify base64 and svg inlined string, global minifying)
SVG Inline	Minify SVG outputed files
ESLint	JavaScript/TS linter, make your project sane and robust

Requirements

Dependencies	Version
NPM	v6.13
NodeJS	v12.18

Files structure

This package

node_modules/@vkgp/webpack-core
├── .babelrc                  # Babel configuration (Typescript and JS files)
├── .browserslistrc           # Browserslist need to works with your project (used by Babel, PostCSS)
├── .eslintrc                 # ESLint configuration, warns only as default
├── postcss.config.js         # Export modules for PostCSS configuration
├── tsconfig.json             # TypeScript configuration
├── config.default.json       # Common configuration (shared with dev and prod, also your main configuration file)
├── webpack.dev.config.js     # Developement mode webpack configuration
└── webpack.build.config.js   # Production mode webpack configuration

# (package.json, .editorconfig...)

Sources folder (<project_root>/.webpack for example)

Your src folder need to be a copy of src_default to start your project.

src
├── config.json               # Override config.default.json, same function
├── distribution              # Contain project distribution (Not exported at build can only serve dependencies like sass mixins etc)
└── public                    # Exported dir into project public root (for example public dir is ./web for Drupal 8)

# (package.json, .editorconfig, .git, node_modules ...)

Getting Started

Starting your project from skratch easyly !

Installation

First step install or create your project root dependencies (Drupal, Symfony, Sylius as you want..). Now, is recommanded to use files structure explain above, so :

Note : You can use a preconfigured webpack sources here : webpack preconfigured sources

• Create a folder which contain your sources (.webpack for example)
• Run in console npm install @vkgp/webpack-core
• Run npm install
• Copying config.default.json at root of .webpack and rename as config.json
• Setup your configuration
• Create run scripts in your package.json as below :

{
// code ...
  "scripts": {
    "build": "webpack --config=node_modules/@vkgp/webpack-core/webpack.build.config.js",
    "dev": "webpack --config=node_modules/@vkgp/webpack-core/webpack.dev.config.js"
  }
// code ...
}

You're ready to use it.

Configuration

Your main configuration is in your sources folder, config.json, this file override config.default.json.

Take that into consideration :

Base configuration is an example for Drupal website which has theme named vanksen. For drupal public folder is <project_root>/web, so this is your mapped dir with <project_root>/.webpack/public folder and it's mapped with / website route. Remember, your configuration paths is relative from npm script running folder in this case <project_root>/.webpack.

Common configuration

Webpack Vanksen provide a configuration file which is loaded by Webpack production and development mode. In most of the cases, this is your only configuration file you need to edit. See comments below for more informations :

{
  "src": "public",                                                    // Source public path, need to math with public dist
  "dist": "../web",                                                   // Dist public path
  "publicPath": "/",                                                  // Dist root route (to resolve required files from compiled JS)
  "chunkDir": "themes/custom/vanksen/chunks",                         // Your chunks directory, each dynamic import create a chunk js file
  "compileExtensions": [".js",".ts",".scss",".svg"],                  // Extensions to use as entries, webpack compile it with associated loaders
  "resolveExtensions": [".js",".ts",".sass",".tsx",".jsx",".json"],   // Resolve path in extensions (import, export, url functionnalities...)
  "extractExtensions": ["css","scss","svg"],                          // Extracted from bundle (example: create .css files not style tag in JS)
  "exclude": "/(node_modules|bower_components)/",                     // Excluded from webpack parsing without calling with import
  "browserSync": {
    "network": {
      "host": "localhost",                                            // BrowserSync host
      "proxy": "vanksen.docksal",                                     // BrowserSync proxy (your local project url)
      "port": 4200,                                                   // BrowserSync port
      "ui": { "port": 4201 },                                         // BrowserSync ui port
      "open": false                                                   // Open browser on build
    },
    "options": {
      "injectCss": true                                               // Inject CSS without page reload
    }
  },
  "sass": {
    "includePaths": [                                                 // Sass included path to resolve it without full or relative url
      "distribution/sass",
    ]
  },
  "copy": {
    "ignore": ["*.ts","*.js","*.scss",".svg",".gitkeep"]              // When your build is finalized, webpack copying all files from src to dist
  },
  "clean": {
    "beforeBuild": ["../web/**/*chunk.js"],                           // Before build, removing matched files
    "afterBuild": []                                                  // After build, removing matched files
  },
  "stats": {                                                          // Webpack output, see webpack documentation for more informations
    "all": false,
    "errors": true,
    "errorDetails": true,
    "warnings": true,
    "performance": true,
    "timings": true,
    "builtAt": true,
    "publicPath": true,
    "outputPath": true
  }
}

Configure specific mode

Webpack provide two mode as default : production and development.

• Webpack production mode default configuration : production mode
• Webpack development mode default configuration : development mode

This distribution use both configurations, which is loaded by :

• Production : webpack.dev.config.js
• Development : webpack.build.config.js

It's not recommanded to edit both files before, but it's a possibility if it's realy necessary. For more information, visit webpack documentation here : Webpack documentation

Usages

First step, run npm install

Production and development

Easy to use :

• npm run dev : Development
• npm run build Production

Entries & bundle

Understanding

Webpack Vanksen distribution override default Webpack behavior. As default Webpack use few entries and generate CSS, chunks and other file in unique bundle file. The Vanksen distribution extract assets like CSS, SVG and others files to increase performance and provide a distribution which can used with a lot of frameworks and tools. To make it, Webpack is configured to parse your public repository and use assets as bundle but not generate useless bundle file. For example : Your CSS is used as entry, but only SVG file is extracted and Webpack do not create a bundle file for this entry.

Use bundle functionnality

All files not prefixed by underscore is a bundle, webpack integrate static imports and others depencencies in the generated bundle. So, use underscore _ to specify if your file is a dependency.

For example :

public/_dependency.ts

export class Example {

  private message: string;

  public constructor () {
    this.message = 'Hello World !';
  }

  public displayMessage() {
    return console.log(this.message);
  }
}

public/mybundle.ts

import { Example } from './_dependency';

new Example().displayMessage();

In this example, webpack generate a file ( mybundle.js the bundle) which contain example class and code of mybundle.ts.

Use dynamic imports

The dynamic import works different, the imported class isn't integrated in the bundled file but a chunks with specific id is generated. So, when the dynamic import function is called, the chunk file is automatically added to JS file in browser.

For example, to dynamically import bootstrap from node_modules :

public/mybundle.ts

setTimeout(() => {
  import('bootstrap').then(bootstrap => console.log(bootstrap));
},3000)