Webpack HTML Boilerplate

Useful for static prototyping, gpu rendering and shipping modular html. Extendable webpack ecosystem and config, default loaders and preview features.

  • Node 14
  • Npm 6
  • Webpack 4
  • Babel 7
  • Modernizr
  • Typescript
  • Sass
  • Twing
  • Nunjucks
  • Vue
  • React
  • Svelte
  • Stylelint
  • Eslint
  • TSLint
  • Husky
  • Browsersync
  • WDS
  • WebGL
  • GLSL
  • SVG Sprites
  • Favicons
  • Lazy Imports
  • Jasmine
  • Ally
  • Legacy Build
  • Unic AG
Github Repo

Motivation

create a simple webpack ecosystem to test technologies, approaches or mechanism independently of framework CLI. While many static frontend generators aren't maintained anymore, Darvin came up with the latest packages.

Quickstart

git clone https://github.com/unic/darvin-webpack-boilerplate.git myProject
cd myProject
nvm install 14.3.0; nvm use 14.3.0
npm start

Installation

1. Prerequisites

It's highly recommended to install the Node Version Manager according to the links:

Linux/Mac

https://github.com/creationix/nvm

Windows

https://github.com/coreybutler/nvm-windows

Install Node.js

nvm install 14.3.0

Switch between installed versions in your project directory:

list versions

nvm list

use version

nvm use 14.3.0

2. Clone Repo

Clone the actual repo to a new empty directory (e.g myProject) and navigate inside.

git clone https://github.com/unic/darvin-boilerplate.git myProject

cd myProject

3. Configure Darvin

Its time to configure your darvin setup and select your favorite configs and engines.

npm start

Recommended
  • assets-cleaner (clean-webpack-plugin)
  • assets-copy (copy-webpack-plugin)
  • assets-favicons (favicons-webpack-plugin)
  • assets-fonts (file-loader)
  • assets-images (image-webpack-loader)
  • assets-sprites (svg-spritemap-webpack-plugin)
  • bundler-analyzer (webpack-bundle-analyzer)
Related
  • server
    • env-browsersync (browser-sync-webpack-plugin)
    • env-devserver (webpack-dev-server)
  • template
    • html-njk (nunjucks-loader)
    • html-twig (twig-loader/twing)
  • styles
    • style-sass (sass-loader/postcss-css-variables)
    • style-sass-svelte (sass-loader-svelte) [undone]
  • scripts
    • javascript-i18n (file-loader)
    • javascript-modernizr (webpack-modernizr-loader)
    • javascript-typescript (ts-loader)
    • javascript-vue (vue-loader)
    • javascript-react (react-loader)
    • javascript-svelte (svelte-loader)
  • html-markdown (markdown-loader)

Startup

Use Full-Start after darvin installation or package updates. Start fast if npm packages up to date and preview already builded.

Full start
installation, preview bundle and devserver

npm start

Fast start
devserver only

npm run dev

Publish Bundles

Develop

Bundle in develop mode without dev-server for rollout.

bundle dev
bundle dev mode

npm run dev-bundle

bundle system dev
bundle dev mode with system settings

npm run dev-bundle-system

Production

Bundle local and system builds in production mode.

bundle dev
dual bundle prod-modern and prod-legacy with dev settings

npm run prod

bundle prod
dual bundle prod-modern and prod-legacy with system settings

npm run prod-system

Legacy Build (IE11)

Develop

Only run legacy scripts

bundle dev
dev legacy mode

npm run dev-legacy

bundle dev with system settings
dev legacy mode with system settings

npm run dev-legacy-system

Production

Build legacy styles with postcss.

bundle prod
bundle prod legacy with dev settings

npm run prod-legacy

bundle prod with system settings
bundle prod legacy with system settings

npm run prod-legacy-system

Loaders

There are several configurations for already existing loaders in the folder webpack/settings

Recommended
  • assets-cleaner (clean-webpack-plugin)
  • assets-copy (copy-webpack-plugin)
  • assets-favicons (favicons-webpack-plugin)
  • assets-fonts (file-loader)
  • assets-images (image-webpack-loader)
  • assets-sprites (svg-spritemap-webpack-plugin)
  • bundler-analyzer (webpack-bundle-analyzer)
Related
  • server
    • env-browsersync (browser-sync-webpack-plugin)
    • env-devserver (webpack-dev-server)
  • template
    • html-njk (nunjucks-loader)
    • html-twig (twig-loader/twing)
  • styles
    • style-sass (sass-loader/postcss-css-variables)
    • style-sass-svelte (sass-loader-svelte) [undone]
  • scripts
    • javascript-i18n (file-loader)
    • javascript-modernizr (webpack-modernizr-loader)
    • javascript-typescript (ts-loader)
    • javascript-vue (vue-loader)
    • javascript-react (react-loader)
    • javascript-svelte (svelte-loader)
  • html-markdown (markdown-loader)

Bind Loader

Open 'config/.darvinrc.all.json' and check which loaders are binded. You can extend this configuration file.

config/.darvinrc.modern.json
{
  "settings": {
    "base": ["js", "typescript"],
    "default": ["cleaner", "copy", "fonts", "images", "sprites", "modernizr", "sass"],
    "html": ["nunjucks"],
    "devserver": ["webpackdev"],
    "framework": ["vue"],
    "addons": ["favicons", "analyzer", "markdown", "i18n"]
  },
  "name": "My Project",
  "company": "Unic AG"
}

Each Webpack Loader Config has a Darvin setting file with the name, value and type of the setting. The keywords above are referenced to this value:

Example
webpack/settings/javascript-vue/.dv.settings
{
  "name": "Vue.js",
  "value": "vue",
  "type": "framework"
}
Key Scope Usage
name CLI Information for CLI Setup
value config/.darvinrc.* Key for darvin configuration
type CLI Group for CLI Setup

Add new loader

This is how to add new webpack loaders to darvin

1. Create Dir

Navigate to the settings and create folder

cd webpack/settings
mkdir javascript-react

2. Add Dependencies

Create a package.json inside the new directory and add dependencies.

Example
webpack/settings/javascript-react/package.json
{
  "dependencies": {
    "react": "^16.9.0",
    "@babel/preset-react": "^7.0.0",
    "react-dom": "^16.9.0"
  }
}

3. Add Darvin Config

Add a new darvin configuration and set the type for CLI purpose.

Example
webpack/settings/javascript-react/.dv.settings
{
    "name": "React",
    "value": "react",
    "type": "framework"
}

4. Add webpack settings

Create index.js and set the webpack config for dev, prod and prev.

Example
webpack/settings/javascript-react/index.js
const prod = {
  plugins: [
    new ...({

    }),
  ],
}

const dev = {
  plugins: [
    new ...({

    }),
  ],
}

const prev = {
  plugins: [
    new ...({

    }),
  ],
}

5. Hook into lifecycle

Add your new setting to build process by adding the value under defined type array.

Example
config/.darvinrc.*.json
{
  "settings": {
    "base": ["js"],
    "default": ["cleaner", "fonts", "images", "sass"],
    "html": ["twig"],
    "devserver": ["browsersync"],
    "framework": ["react"],
    "addons": ["analyzer", "markdown"]
  },
  "name": "My Project",
  "company": "Unic AG"
}

Build Parameter

There's a configuration file for your local build and one for the system build.

Example
config/.darvinconf.*.js
global.project = 'Darvin';
global.mainChunk = 'js/main'; // other entrypoints can be defined in the webpack.config.*.js -> settings.entry[global.mainChunk]
global.proxy = 'unic.local'; // used proxy if boilerplate initialised with thirdparty
global.port = 8001; // dev server port
global.template = {
  'extIn': 'njk', // template extensions for HTML Engine
  'extOut': 'html' // rendered extensions for HTML Engine
}
global.preview = {
  indexFileInput: 'index.njk', // preview template file
  indexFileOutput: 'index.html' // rendered preview file
}
global.inputDirs = {
  src: 'src', // source directory in project root
  assets: 'assets', // asset directory in source directory
  templates: 'templates', // html templates in source directory
  scripts: 'scripts' // directory for scripts and entrypoint
}
global.output = {
  'index': 'index' // start index name
}
global.server = {
  'base': (process.env.NODE_ENV === 'dev') ? '' : '', // root path to assets directory (different on system config)
  'assets': 'assets' // name of systems assets directory
}
global.build = {
  'legacy': true // build IE11 styles
}

Command Line Interface

The Darvin-CLI is useful for project initialisation and scaffolding:

bind CLI

npm link

show commands

darvin-cli usage

add new module to project

darvin-cli add

show settings

darvin-cli list

init settings

darvin-cli init

Scripts

Darvin load chunks from a almost empty scriptbase. Dynamic chunk load if module exist in dom or lazy load with intersection observer.

Lets take a look over the different loading options:

src/scripts/main.js
window.apps = {};
window.apps.main = createApp({
  modules: {
    // Directly integrate module
    button,

    // lazy-load module if it's found in the DOM
    'vue-module': () => import(/* webpackChunkName: "vue-mod" */ './demo/vue-module'),

    // lazy laod when scrolled to this element
    'lazy-module': {
      lazy: true,
      handler: () => import(/* webpackChunkName: "lazy-mod" */ './demo/lazy-module'),
    },
  },
});

Use the 'create-module.js' to create your chunks. Set options and declare functions in the constructor. You can find examples in the demo directory.

src/scripts/demo/lazy-module.js
import createModule from '@scripts/libs/create-module';

export default createModule({
  options: () => ({
    foo: 'bar',
  }),

  /**
   * createVueModule
   * @param {Object} module - Module
   * @param {Element} module.el - Element
   * @param {Object} module.state - State
   * @param {Object} module.options - Options
   * @return {Object} state
   */
  constructor({ el, state, options }) {
    el.innerHTML = 'this is lazy initiated by IntersectionObserver; ' + options.foo;

    return state;
  },
});

Set the data-module on the root element to hook your module. You can also overwrite the JS options from HTML {moduleName='lazy-mod'}

Hook HTML with script
<!-- START - m01-lazymod -->
  <div class="m-lazymod" data-module="lazymod" data-lazymod-options='{"json": true}'>
    <a class="lazylink">
      ..
    </a>
    <div class="lazybody">
      ..
    </div>
  </div>
  <!-- END - m01-lazymod -->

Sass

Legacy mode is on by default and support CSS features also for IE11.

CSS Custom Properties
//== Grid
//
$grid-gap: (
  small: #{rem(20)},
  regular: #{rem(26)},
);

$grid-gap-index: (
  'zero': 'small',
  'large': 'regular',
);

..

@each $breakpoint, $value in $grid-gap-index {
  :root {
    @if $breakpoint == 'zero' {
      --grid-gap: #{map-get($grid-gap, $value)};
    } @else {
      @include media-breakpoint-up($breakpoint) {
        --grid-gap: #{map-get($grid-gap, $value)};
      }
    }
  }
}

Author

Tobias Frei, Unic AG

Contribution

Christian Sany, Pascal Giehl, Pascal Kuster, Nenad Brcic

Shader Example

fragment code partly based on srtuss example (shadertoy)

Repo

https://github.com/unic/darvin-webpack-boilerplate

Links