A very strict project configuration / boilerplate for front end projects. It features many ESLint and Stylelint plugins (including enforcing a Stylelint class pattern) and an aggressive git hook which runs on every commit.
Main features include:
- React.
- Webpack dev server for a great server with live-reloading capabilities and HTTPS.
- Dynamic imports and code splitting.
- Caching with hashes in filenames for JavaScript and CSS.
- JavaScript transpilation with Babel (options for modern browsers / IE11 commented out in babel.config.js).
- Strict ESLint and Stylelint with many plugins for good development practices
- Stylint rule "selector-class-pattern" is enabled, enforcing a SCSS class pattern of BemBlock_bemElement___bemModifier.
- Jest with jsdom for fast unit testing and integration testing.
- Also enforces 90% code coverage.
- Cypress for end-to-end testing.
- Aggressive git hook to ensure the build passes in every commit, which runs:
- Prettier code formatter in write mode.
- ESLint and Stylelint in fix mode.
- All the tests for Jest and Cypress, ensuring they all pass and code coverage threshold is met.
- PostCSS with things like autoprefixer and cssnano (to minify our CSS code).
- A lot of NPM scripts for different use cases.
The reason for all of these is that I believe code quality and passing tests are important. Also I believe it's ideal for a repository to always be stable, so that it's possible to revert to any commit. If really needed the git hook can always be bypassed and the test coverage threshold modified.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
- NPM
Installation requires NPM which is included with Node. You can install Node by downloading the installer from the website.
To update NPM to the latest version:
npm install -g npm@latest
- Clone the repo
git clone https://github.com/sargalias/front-end-project-starter.git
- Install NPM packages
npm install
Just delete the .git folder in your project and start a create a new git repository with git init.
Note: In some operating systems the .git folder is hidden. You may need to turn on the "show hidden files" option.
One way to use this project is to keep a dedicated branch and remote for it. That way you can keep getting updates and merging them in your project.
- Rename the remote to "config"
git remote rename origin config
- Checkout a new branch "config"
git checkout -b config
- Pull updates
git checkout config
git pull config master
- Merge those updates in your working branch
git checkout my-work-branch
git merge config
There are many commands / NPM scripts included.
- Start the project on a local server:
npm start
- Build the project for production:
npm run build - Build the project for development (linting errors won't fail the build):
npm run build:dev
-
Start the project on a local server along with Cypress (E2E tests):
npm run start-with-cypress -
Run all tests (Jest and Cypress):
npm run test:all -
Run Jest tests:
npm test -
Run Jest tests without coverage:
npm run test:no-coverage -
Run Jest tests in watch mode:
npm run test:watch -
Open Cypress (requires a server running):
npm run cy:open -
Run Cypress tests:
npm run test:e2e -
Run Cypress tests if a server is already running:
npm run cy:run
- Format code with code formatter:
npm run format - Run lint check:
npm run lint - Run lint check in fix mode:
npm run lint:fix - Run lint check for SCSS only:
npm run lint:scss - Run lint check for JavaScript only:
npm run lint:js - Run lint check in fix mode for SCSS only:
npm run lint:fix:scss - Run lint check in fix mode for JavaScript only:
npm run lint:fix:js
- Run the entire build process (code formatting, linting in fix mode, all tests):
npm run ci
For every option and configuration, please see the relevant documentation. E.g. for any Stylelint issues, please see the Stylelint docs and / or docs for the relevant Stylelint plugin.
There is a pretty aggressive Git hook which runs the entire build process for every commit, ensuring linting and tests pass.
If needed, you can disable the Git hook by deleting the .huskyrc file, or using the --no-verify flag during commits.
The code coverage threshold with Jest is set to 90%. This can be changed by modifying the jest.config.js file. The option is coverageThreshold: { global: {/* ... */} }.
- React
- Webpack - To bundle code
- webpack-dev-server - Server for development
- webpack-merge - To help us create multiple webpack configs
- babel-loader - To run babel as part of webpack
- clean-webpack-plugin - To clean the destination directory for every build
- css-loader - To load CSS
- eslint-loader - For using ESLint with webpack
- file-loader - To load files (such as fonts)
- html-webpack-plugin - To use an HTML template
- mini-css-extract-plugin - To extract CSS into separate files for production
- node-sass - Dependency of sass-loader
- sass-loader - For using SCSS with webpack
- sass-resources-loader - For "globally importing" sass resources such as variables and mixins
- stylelint-webpack-plugin - To run Stylelint as part of webpack
- style-loader - For adding CSS directly to the page in development
- PostCSS
- Autoprefixer - To add vendor prefixes to CSS
- cssnano - To minify CSS
- Jest - Test framework
- identity-obj-proxy - To allow us to see CSS classes in the DOM
- jest-extended - More awesome assertions for Jest
- Cypress - End-to-end testing framework
- React testing library - Test utilities for React
- Cypress testing library - Test utilities for Cypress
- ESLint - JavaScript static code analysis
- eslint-config-airbnb - Aribnb's .eslintrc
- eslint-config-prettier - For using Prettier with ESLint
- eslint-plugin-array-func - Rules for arrays functions and methods
- eslint-plugin-import - Helps validate proper imports
- eslint-plugin-import-resolver-webpack - Import resolver for webpack
- eslint-plugin-cypress - Rules and globals for Cypress
- eslint-plugin-jest - Rules and globals for Jest
- eslint-plugin-jsx-a11y - Rules for accessibility with JSX
- eslint-plugin-no-loops - Encourages array methods instead of traditional for loops and such
- eslint-plugin-no-use-extend-native - Rules for not extending built-in prototypes
- eslint-plugin-prettier - Runs prettier as an ESLint rule
- eslint-plugin-promise - Rules for good promise usage
- eslint-plugin-react - Rules for React
- eslint-plugin-react-hooks - Rules for React hooks
- eslint-plugin-security - Rules preventing unsafe use of JavaScript
- eslint-plugin-xss - Rules for detecting XSS issues
- eslint-plugin-sonarjs - SonarJS rules
- Stylelint - CSS static code analysis
- stylelint-config-idiomatic-order - Imposes an order for CSS declarations
- stylelint-config-prettier - For using Prettier with Stylelint
- stylelint-config-recommended - Recommended configuration for Stylelint
- stylelint-declaration-use-variable - For enforcing variable usage for values in CSS
- stylelint-scss - SCSS specific rules
- Babel - To transpile code
- @babel/preset-env - To transpile code in tests
- @babel/preset-react - To transpile JSX
- babel-jest - For Jest to transpile code
- babel-plugin-dynamic-import-node - To enable dynamic imports in Node (for tests)
- babel-plugin-syntax-dynamic-import - To enable dynamic imports in the browser
- Husky - Simple Git hooks
- lint-staged - To allow us to run commands on git staged files
- npm-run-all - To allow us to run multiple NPM commands in scripts
- live-server - Simple server for Cypress tests
- live-server-https - For live-server HTTPS.
- Prettier - Code formatting
- pretty-quick - Git hook helper for running prettier for staged files
This project is licensed under the MIT License - see the LICENSE.md file for details.