<div align="center"> <a href="https://webpack.js.org/"> <img width="200" height="200" src="https://cdn.rawgit.com/webpack/media/e7485eb2/logo/icon-square-big.svg"> </a> </div>

SuperDevStack

Web development stack based on Webpack with React static templating.

Today, JavaScript rules the web. You're creating websites with React, working with server side rendering, using Gatsby, Create React App, Next.js or other modern stuff. However there are still cases when you might need to create a website without any client-side routing, with generated static HTML templates (that back end developers will take, or for creating a static site). If you don't want to learn or use any templating language and want to work with React, you're at the right place. SuperDevStack is a composition of different environments and tools flavoured with ideas and techniques based on a personal experience in the front end development.

Templating languages like Nunjucks or Handlebars are very handy tools, however it's another thing you need to learn, get familiar with the syntax, deal with its issues and limitations. If you're familiar with React, you can make use of it as your templating language, meaning creating static HTML files via React components with JSX syntax and use advantages it provides. All together with a bunch of modern tools.

The Core Features

• React templating (React components -> HTML templates)
• A local server with Webpack dev server
• HMR (Hot Module Replacement)
• Code splitting
• Transpiling JS with Babel
• Remote debugging with Browsersync
• Automatic polyfill injection
• Linting with ESlint / Stylelint / Prettier
• Mock REST API server
• JavaScript testing with Jest
• Git hooks with Husky
• Reduced bundle size by using Preact
• Assets optimization
• and much more

Getting Started

Installation

For now, simply clone the repository and run npm i.

Usage

Your work is starting with your code editor. Open the project and decide what you want to do.

List of available scripts is specified in package-scripts.js file. However there are 2 main scripts you will use:

Running the Development Server

For developing it's needed to run the local server. All npm start dev scripts will first fix the formatting of all config files, but each is then doing the different things:

• npm start dev will run Webpack dev server
• npm start dev.hot will run Webpack dev server with the support of HMR
• npm start dev.prod will run Webpack dev server with the production config (to test the prod assets in dev)

Running the Build

For bundling production assets it's needed to run the build.

• npm start build will:
  • Check the format of all config files
  • Run Webpack with production settings
  • Run Jest to run all the JavaScript tests

Documentation

The code should be self-documented with comments at proper places, however this section gives you better overview with the basic explanation of the folder structure, used files and the configuration of SuperDevStack.

Folder Structure

• .vscode - Recommended settings for VS Code users
• dist - Target folder where ready-for-production files are built. Created by the build script
• externals - Storage for external assets (like 3rd party scripts or things you don't have control over) that you need to be present in dist folder, not processed by Webpack (simply for copy-paste)
• src - Source folder containing all application related files

  • api - Local mock API definitions used for AJAX testing

  • app - JavaScript components and utilities

  • fonts - Local fonts loaded by CSS

  • img - Images with various formats

  • styles - SASS files

  • tpl - React pages, layouts and components for HTML composition

• webpack - Webpack configuration for different environments
• Root files - Configuration files can be written in different formats, the preferred file format in SuperDevStack is .js (.babelrc.js) before non-extension format (.babelrc) due ability to programmatically configure files and use comments in JS files
  • .babelrc.js - Babel config with presets, plugins and specific environment settings
  • .browserslistrc - Target browsers config shared by multiple tools like Babel, ESlint, Stylelint and more
    • .eslintignore - ESlint config for ignoring specific files and directories while linting
    • .eslintrc - ESlint config with plugins, rules and other settings
    • .gitignore - GIT config for ignoring specific files and directories
    • .huskyrc.js - Husky config for GIT hooks
    • .npmrc - NPM global config
    • .prettierignore - Prettier config for ignoring specific files and directories while prettifying
    • .prettierrc.js - Prettier config with formatting setup
    • .stylelintrc.js - Stylelint config with plugins, rules and other settings
    • jest.config.js - Jest config with needed libraries, aliases and more
    • jest.setup.js - Jest config with adding features (e.g. fetch) to global scope that allows to use them in test files
    • package-scripts.js - NPM scripts are now not in package.json but moved to the separate file to not bloat the file and programmatically configure files and use comments
    • package.json - General project configuration with dependencies
    • postcss.config.js - PostCSS config with plugins needed for postprocessing CSS
    • README.md - It's me!

Environment

• NPS

  NPS solves the issue of having tons of NPM scripts in package.json file. Maintaining app with just few simple scripts is fine, but with more complex solution it can grow into the burning hell. Only script you need there is one-word start script - nps.

  The scripts are located in package-scripts.js file. Notice it's a JavaScript file so you can generate your scripts programmatically, use comments and much more. And most importantly, it's nicely separated in one file.

• Browsers support

  In .browserslistrc file you can specify the browsers you app is tuned for. It will tell tools like Autoprefixer or Babel what browsers you want to support and the tools will adjust their configuration to serve you features that the specified browsers support. If you are not sure what features work in what browsers, check Can I Use and test your Browserslist queries at the official page.

• GIT hooks

  Git hooks are scripts that Git executes before or after events like commit or push. Handy for ensuring your code is properly formatted with no errors. Powered by Husky.

Webpack

A module bundler, the heart of your application. In simple words, it takes your source files, processes them with loaders and plugins, run the tasks you specify over it and returns the optimized output files.

One of the most useful features is code splitting, allowing you to improve the load time and performance of your app by splitting the output file(s) into multiple, separated chunks and load them on demand only when they are currently needed.

The entire Webpack magic is specified in config files.

• Entry - Source files like JavaScript and CSS files, images, ...
• Output - Production-ready built files
• Loaders - Alter the files as you specify, e.g. transpile JavaScript, minify CSS, optimize images, ...
• Plugins - Inject polyfills, extract files, generate favicons, ...

Config files

You often need different configuration for development and production environment. Config file for each environment can be used.

• Base config

  Base Webpack config sharing configuration for both development and production env.

  Stuff that is needed on both dev and prod such as linting, generating templates, transpilation, ...

  Sometimes it contains conditions to differentiate specific configuration for dev/prod. You might think why do we have the separated dev and prod config if we are checking for the environment in this file. At some cases it's better to do it in this file in order to prevent scripts duplication or unnecessarily writing of more code.

• Dev config

  Development environment config is used for the best developer experience.

  No assets optimization, producing into much bigger files enabling features like running development server and using hot module replacement.

• Prod config

  Production config focusing on as much assets optimization as possible.

  Caching, compression, bundle analyzer tools, ....

Features

• Dev server and Browsersync remote debugging

  Webpack dev server runs the local server. However Browsersync is also included in order to be able to test your app on the external IP address, on multiple devices while allowing remote debugging via Weinre.