update README

This commit is contained in:
Adam Piontek 2021-08-02 17:19:29 -04:00
parent ebd68b8f0e
commit e8b2b5656e
1 changed files with 5 additions and 226 deletions

231
README.md
View File

@ -1,230 +1,9 @@
# Webpack 5 Boilerplate Template
# 73k.us custom rainbow error pages (40x/50x)
![Maintenance](https://img.shields.io/maintenance/yes/2021?logo=github)
![webpack-current](https://img.shields.io/badge/webpack-v5.44.0-green?logo=webpack)
![node-current (scoped)](https://img.shields.io/node/v/@weareathlon/frontend-webpack-boilerplate)
[![Build Status](https://travis-ci.com/WeAreAthlon/frontend-webpack-boilerplate.svg?branch=master)](https://travis-ci.com/WeAreAthlon/frontend-webpack-boilerplate)
[![@weareathlon/frontend-webpack-boilerplate](https://snyk.io/advisor/npm-package/@weareathlon/frontend-webpack-boilerplate/badge.svg)](https://snyk.io/advisor/npm-package/@weareathlon/frontend-webpack-boilerplate)
[![GitHub Issues](https://img.shields.io/github/issues-raw/WeAreAthlon/frontend-webpack-boilerplate)](https://github.com/WeAreAthlon/frontend-webpack-boilerplate/issues)
[![Known Vulnerabilities](https://snyk.io/test/github/WeAreAthlon/frontend-webpack-boilerplate/badge.svg?targetFile=package.json)](https://snyk.io/test/github/WeAreAthlon/frontend-webpack-boilerplate?targetFile=package.json)
[![devDependency Status](https://david-dm.org/WeAreAthlon/frontend-webpack-boilerplate/dev-status.svg)](https://david-dm.org/WeAreAthlon/frontend-webpack-boilerplate?type=dev)
[![npm](https://img.shields.io/npm/dm/@weareathlon/frontend-webpack-boilerplate)](https://www.npmjs.com/package/@weareathlon/frontend-webpack-boilerplate)
[![GitHub License](https://img.shields.io/github/license/WeAreAthlon/frontend-webpack-boilerplate)](https://github.com/WeAreAthlon/frontend-webpack-boilerplate/blob/master/LICENSE)
Based off [frontend-webpack-boilerplate](https://github.com/WeAreAthlon/frontend-webpack-boilerplate) with TailwindCSS added.
![Front-end Webpack Boilerplate](https://repository-images.githubusercontent.com/96102257/4be7b600-61f1-11e9-9ebf-67b17d5ba125)
Builds html & css that can be used as custom error pages with, e.g., nginx.
## Demo
## NOTE
* [Demo page demonstrating building - SASS, JavaScript, Images, Fonts, HTML](https://weareathlon.github.io/frontend-webpack-boilerplate/)
Table of Contents
=================
* [Webpack 5 Boilerplate Template](#webpack-5-boilerplate-template)
* [Demo](#demo)
* [Features](#features)
* [Requirements](#requirements)
* [Setup](#setup)
* [Installation](#installation)
* [Define Package Metadata](#define-package-metadata)
* [Configuration](#configuration)
* [Environment Configuration](#environment-configuration)
* [Additional webpack configuration](#additional-webpack-configuration)
* [Development](#development)
* [Assets Source](#assets-source)
* [Build Assets](#build-assets)
* [One time build assets for development](#one-time-build-assets-for-development)
* [Build assets and enable source files watcher](#build-assets-and-enable-source-files-watcher)
* [Start a development server - reloading automatically after each file change.](#start-a-development-server---reloading-automatically-after-each-file-change)
* [Production](#production)
* [Build Assets](#build-assets-1)
* [Get Built Assets](#get-built-assets)
* [Run Code Style Linters](#run-code-style-linters)
* [SASS](#sass)
* [JavaScript](#javascript)
* [Additional Tools](#additional-tools)
* [Run Assets Bundle Analyzer](#run-assets-bundle-analyzer)
* [Continuous Integration](#continuous-integration)
## Features
* **Simple setup** instructions
* Start development of a project right away with **simple**, **configured**, **linter enabled**, **browser synced** asset files.
* Configuration per **environment**
* `development` - [`sourcemaps`](https://webpack.js.org/configuration/devtool/), [`browser synced developmentment server`](https://webpack.js.org/configuration/dev-server/)
* `production` - [`minification`](https://webpack.js.org/plugins/terser-webpack-plugin/), [`sourcemaps`](https://webpack.js.org/configuration/devtool/)
* Configurable **browsers versions support**. It uses [`browserslist`](https://github.com/browserslist/browserslist#full-list) - just specify the browsers you want to support in the `package.json` file for `browserslist`:
```js
"browserslist": [
"last 2 versions",
"> 5%"
]
```
* The built CSS / JavaScript files will respect the **configured supported browser versions** using the following tools:
* [`autoprefixer`](https://github.com/postcss/autoprefixer) - automatically adds vendor prefixes to CSS rules
* [`babel-preset-env`](https://babeljs.io/docs/en/babel-preset-env) - smart preset that allows you to use the latest JavaScript without needing to micromanage which syntax transforms (*and optionally, browser polyfills*) are needed by your target environment(s).
* Demo project files to be used as a reference and **example demo** building of:
* *JavaScript*
* *SASS / PostCSS*
* *HTML* templates
* *Images* (*CSS backgrounds and image tags*)
* *Fonts*
* Support for **assets optimization** for production environment with ability to configure:
* **Code Minification** of *JavaScript* and *CSS* processed files.
* **Optimize Assets Loading** - inline and embed **images** / **fonts** files having file size below a *configurable* threshold value.
* **Images Optimisation** - optimize `jpeg`, `jpg`, `png`, `gif`, `svg` filesize and loading type via [`imagemin`](https://github.com/imagemin/imagemin). Plugin and Loader for webpack to optimize (*compress*) all images using `imagemin`. Do not worry about size of images, now they are always optimized/compressed.
* Support for **source code syntax style and formatting linters** that analyze source code to flag any programming errors, bugs, stylistic errors or suspicious constructs:
* **SASS/PostCSS syntax cheker** - you can change or add additional rules in `.sasslintrc` file. Configuration options can be found on [`sass-lint`](https://github.com/sasstools/sass-lint/blob/master/lib/config/sass-lint.yml) documentation.
* **JavaScript syntax checker** - following the `airbnb` style, you can review and configure the rules in `.eslintrc` file. Configuration options can be found on [`eslint`](https://eslint.org/docs/user-guide/configuring) documentation.
* Latest [Webpack 5](https://github.com/webpack/webpack) - *JavaScript* module bundler.
* Latest [SASS/PostCSS](https://github.com/sass/sass) compiler based on Dart `sass`.
* Latest [Babel 7](https://github.com/babel/babel) (`@babel/core`) - JavaScript compiler - _Use next generation JavaScript, today._
* Integration with [Travis CI](https://travis-ci.com/)
* [Demo deployment available to GitHub pages](https://weareathlon.github.io/frontend-webpack-boilerplate/)
* Configured and ready to use **Webpack Dev Server** plugin for faster local development - [`webpack-dev-server`](https://webpack.js.org/configuration/dev-server/)
* Integration with [Webpack Bundle Analyzer](https://www.npmjs.com/package/webpack-bundle-analyzer) - _Visualize size of webpack output files with an interactive zoomable treemap._
## Requirements
* `node` : `^12 || >=14`
* `npm`
# Setup
## Installation
1. Choose and download the latest template release from [List of Releases](https://github.com/WeAreAthlon/frontend-webpack-boilerplate/releases).
2. Extract the release archive to a new directory, rename it to your project name and browse the directory.
3. Install all dependencies using `npm` *clean install* command.
```sh
$ npm ci
```
> More on the clean install npm command can be read here [`npm ci`](https://docs.npmjs.com/cli/ci.html)
> You can still use `npm install` in cases the `npm ci` raises system error due to specific platform incompatibilities.
## Define Package Metadata
* Amend `package.json` file and optionally specify:
* `name` - Name of your project. A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`.
* `version` - Specify and maintain a version number indicator for your project code.
* `author` - Your organisation or just yourself. You can also specify [`contributors`](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
* `description` - Short description of your project.
* `keywords` - Put keywords in it. Its an array of strings.
* `repository` - Specify the place where your code lives.
* `license` - Announce your code license, figure out the license from [Choose an Open Source License](https://choosealicense.com) .
* `browserslist` - Specify the supported browsers versions - you can refer to [full list](https://github.com/browserslist/browserslist#full-list) of availalbe options.
# Configuration
## Environment Configuration
* Edit the [`configuration/environment.js`](configuration/environment.js) if you want to specify:
* **`server`**: configure development server, specify `host`, `port`. Refer to the full development server configuration options for [`webpack-dev-server`](https://webpack.js.org/configuration/dev-server/).
* **`limits`**: configure file size thresholds for assets optimizations.
* Image/Font files size in bytes. Below this value the image file will be served as Data URL (_inline base64_).
* **`paths`**: `src` or `dist` directories names and file system location.
## Additional `webpack` configuration
You can additionally configure `webpack` for specific environment:
* `development` - [`configuration/webpack.dev.config.js`](configuration/webpack.dev.config.js)
* `production` - [`configuration/webpack.prod.config.js`](configuration/webpack.prod.config.js)
* Note that if you prefer to build and deploy [`sourcemap`](https://webpack.js.org/configuration/devtool/#production) files:
> You should configure your server to disallow access to the Source Map file for normal users!
# Development
## Assets Source
* **SASS/PostCSS** files are located under `src/scss/`
* **JavaScript** files with support of latest ECMAScript _ES6 / ECMAScript 2016(ES7)/ etc_ files are located under `src/js/`
* **Image** files are located under `src/images/`
* **Font** files are located under `src/fonts/`
* **HTML** files are located under `src/`
* It will **automatically** build **all HTML files** placed under `src/` directory, no need to manually configure each template anymore!
## Build Assets
### One time build assets for development
```sh
$ npm run build
```
### Build assets and enable source files watcher
```sh
$ npm run watch
```
This command is suitable if you develop with external web server.
> **Note:** File watching does not work with *NFS* (*Windows*) and virtual machines under *VirtualBox*. Extend the configuration in such cases by:
```js
module.exports = {
//...
watchOptions: {
poll: 1000 // Check for changes every second
}
};
```
### Start a development server - reloading automatically after each file change.
```sh
$ npm run dev
```
# Production
## Build Assets
Optimize assets for production by:
```sh
$ npm run production
```
## Get Built Assets
* _CSS_ files are located under `/dist/css/`
* _JavaScript_ files with support of _ES6 / ECMAScript 2016(ES7)_ files are located under `/dist/js/`
* _Images_ are located under `/dist/images/`
* Images part of the _design_ (_usually referenced in the CSS_) are located under `/dist/images/design/`
* Images part of the _content_ (_usually referenced via `<img>` tags_) are located under `/dist/images/content/`
* _Fonts_ are located under `/dist/fonts/`
* _HTML_ files are located under `/dist/`
# Run Code Style Linters
## SASS
```sh
$ npm run lint:sass
```
## JavaScript
```sh
$ npm run lint:js
```
# Additional Tools
## Run Assets Bundle Analyzer
```sh
$ npm run stats
```
> This will open the visualisaion on the default configuraiton URL `localhost:8888`, you can change this URL or port following the [package](https://github.com/webpack-contrib/webpack-bundle-analyzer#options-for-cli) documentation.
## Continuous Integration
This boilerplate template contains integration with [Travis CI](https://travis-ci.org/). The build system runs all linting scripts and deploys production optimized pages to _GitHub_ pages upon push to the `master` branch. However, note that this deployment flow only works for _Project Pages_, as User and Organization pages [only support the master branch flow](https://help.github.com/articles/user-organization-and-project-pages/).
For more information on how to set up alternative deployment processes, check out the [Travis CI documentation on deployment](https://docs.travis-ci.com/user/deployment). The service can deploy to dozens of cloud providers, including Heroku, AWS, and Firebase.
After production build, optionally remove the app.js script tags from the built files, just to optimize things further.