@puzzleitc/frontend-guides v1.1.0
Puzzle Frontend Coding Guidelines
This repository provides guidelines, recommendations and code conventions for JavaScript, TypeScript, CSS and HTML to be used in software projects at Puzzle ITC. According to the Puzzle QM Guide, code conventions must be used and automatically verified in software projects.
Please contact the frontend workgroup for questions or create pull requests for improvements.
General
EditorConfig
EditorConfig helps define and maintain consistent coding styles between different editors and IDEs (supporting editors/IDEs).
Put the following .editorconfig
file in your frontend application's root:
# http://editorconfig.org
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
[*.{diff,md}]
insert_final_newline = false
trim_trailing_whitespace = false
Yarn
Always use the Yarn package manager instead of NPM. It uses a lock file for deterministic and faster installations.
Don't install Yarn using NPM, see Installation.
To setup Yarn on Jenkins, read these instructions.
Linting & Fixing
Use either eslint
(JavaScript) or tslint
(TypeScript) to enforce code conventions. Add the package @puzzleitc/frontend-guides
to your project and provide the appropriate linter configuration as described below.
You may use eslint --fix '**/*.js'
or tslint --fix '**/*.ts'
to automatically fix linting issues where possible.
JavaScript
Consider the Airbnb JavaScript Style Guide.
Add the Puzzle linting rules to your project:
yarn add --dev @puzzleitc/frontend-guides
Add
.eslintrc.js
:module.exports = require('@puzzleitc/frontend-guides/eslint/config');
Recommendations:
- Lean towards NPM scripts (see Why I Left Gulp and Grunt for npm Scripts), otherwise use Gulp
- If you need a module bundler: use Webpack
- TODO: transpiling
AngularJS
In addition to the Airbnb Guide, consider John Papa's Angular 1 Style Guide for code conventions and application structure. Use eslint-plugin-angular to enforce these rules.
Add the Puzzle linting rules to your project:
yarn add --dev @puzzleitc/frontend-guides
Add
.eslintrc.js
:module.exports = require('@puzzleitc/frontend-guides/eslint/config/ng');
TypeScript
Consider the Airbnb JavaScript Style Guide.
Add the Puzzle linting rules to your project:
yarn add --dev @puzzleitc/frontend-guides
Add
tslint.json
:{ "extends": ["@puzzleitc/frontend-guides/tslint/config"] }
Recommendations:
- Use strict type checking (
"strict": true
undercompilerOptions
intsconfig.json
)
Angular
In addition to the Airbnb Guide, consider the official Angular Style Guide for code conventions and application structure. Use codelyzer to enforce these rules.
Add the Puzzle linting rules to your project:
yarn add --dev @puzzleitc/frontend-guides
Add
tslint.json
:{ "extends": ["@puzzleitc/frontend-guides/tslint/config/ngx"] }
Recommendations:
- Use TypeScript
- Use Webpack or the Angular CLI
Cascading Style Sheets
Consider Github's Primer Code Guidelines.
TODO:
- SASS usage
- postCSS/autoprefixer/cssnano
- SMACSS?
Hypertext Markup Language
Consider Github's Primer Code Guidelines.
Images & Icons
TODO:
- inline SVG
- optimization?
Preferred Packages & Widgets
TODO:
- Selectize
- Testing (AngularJS & Angular): Karma/Jasmine
- ...