Front-end Readme

README.md

website-name front-end

A Website built on with

Built with:

• Gulp
• SASS
• Babel + Webpack

Requirements

• Node.js 12+
• git

Upgrading from < Node 12

1. re-run the install: npm install
2. If you encounter an error with node sass, do a rebuild: npm rebuild node-sass

Commands

Command	Purpose
npm install	Installs all packages
npm run clean	Deletes the build folder
npm run build	Builds all assets for a development environment
npm run build:staging	Builds for staging (only assets, unminified)
npm run build:production	Builds for production (only assets, minified)
npm start	build for development, watches source folders, live reloading
npm run lint:styles	runs linter on all scss files in src, outputs in console and reports/scss.lint.txt
npm run lint:js	runs linter on JS files in src, output in console and reports/js.lint.txt
npm run lint:js:fix	runs lint:js and fixes all fixable things
npm run lint	runs lint:styles and lint:js
npm run test:ui	runs jest --maxworkers=2
npm run test	runs test:ui and has linting as a posttest

Docker

Docker isn't necessary, but may be useful if you don't want to change your version of node or NPM. It allows you to run the front-end static site in a container. You can then use VS Code's WSL extensions to connect to it.

Be mindful that the container will not run Puppeteer.

Create a Docker image

You can always give your own tag. Take note of the . at the end.

docker build --tag WEBSITE-front-end .

Create a Docker container

You can always give your own name. Take note that this binds port 3000 from the container to port 3000 on your machine. You could bind it to your own port.

docker create --name exlrt-front-end-local -p YOURPORT:3000 WEBSITE-front-end

Run the container

docker run WEBSITE-front-end-local

Run the container with the NPM command of your choice

docker run --rm --name WEBSITE-front-end-local -v "%cd%":/app -w /app WEBSITE-front-end npm COMMAND
docker

Connect to the container's bash

docker exec -it WEBSITE-local-site bash

Development Process

If using VSCode, install the Jira Extension. The Jira extension lets you view issues, start branches from them, and create pull requests.

You can view Jira issues with this extension with the following JQL:

project = "WEBSITE-JIRA-PROJECT"  AND assignee = "<YOUR NAME>" AND status != "resolved" AND status !="closed" AND Sprint = <SPRINT NUMBER> ORDER BY priority DESC

1. New works starts as a branch off of develop.
   • Set ticket to "in progress"
2. Follow the "gitflow" style with branch names Use a prefix, include the ticket number, optionally choose a description of the work.
   • feature\WEBSITE-JIRA-123
   • bugfix\WEBSITE-JIRA-456-correct-everything-in-ie
   • hotfix\WEBSITE-JIRA-IE-didnt-work
3. After local testing is finished submit a pull request to merge into develop
   • Double check linters to make sure there's no errors
   • Did you look at in Firefox, IE11, and mobile?
   • Set ticket to "on hold"
4. After the pull request is approved, merge develop into staging branch
   • Set ticket to "To deploy"
5. Every Tuesday and Thursday, the staging branch is deployed to uat.exlrt.com.
   • Set ticket to "in review" and assign to tester or whomever opened it.
6. After ticket is reviewed, it should be moved to "done"

Coding StyleGuide

1. Write working code
2. Write good code
3. Write fast code
4. Don't commit code that would make a teammate curse your name
   • Note: Future You is also a team mate

CSS

1. Follow ITCSS pattern
2. Be BEM-ish:
   • camelCase for multiple words
   • use hyphens to indicate "elements"
   • Use modifiers on the block for variations
3. Give all variables semantic names, even colors, following small rules for naming things.
4. Follow the stylelintrc.json, with extras:
   • indent 2 spaces
   • strings should be double quotes
   • classNames should be camelCased
   • Don't nest more that 2 levels deep
   • Seriously, seriously reconsider using :not
   • @extends is against the law.
5. !important is permitted for utilities only
6. CSS must be accessible
   1. don't use display: none if it contains text, screen readers can't find it
   2. Where you add :hover, :focus must follow
7. Generally follow Harry Roberts' CSS Guidelines
8. Don't override or ignore lint errors, lint warnings, or Industry Best Practices without leaving a comment explaining why.

JS

1. prefer ===
2. Use semicolons
3. Put JS in a class and instantiate it in index.js
4. Use JSDoc to document all functions, classes, and methods
5. Generally follow AirBnB's JS style guide; it will not lead you astray.
6. Don't override or ignore lint errors, lint warnings, or Industry Best Practices without leaving comments explaining why.

HTML

1. HTML must be valid
2. HTML must be semantic
3. HTML must be accessible
4. Do not abstract HTML into templating if it leads to a loss of understanding for back-end developers
5. All partials should be commented explaining what parts are content manageable, what kinds of output are expected, and what any logic rules are expected.
6. Don't ignore Industry Best Practices without leaving a comment explaining why
7. Use real images whenever possible. Placekitten, placeimg, placebear, and baconmockup are fun, but may not reflect what goes into the CMS
8. Use real real content whenever possible. Lorem ipsum does not reveal how a CMS user will author content.

Debugging

Project Structure

Source files

/
├── src
│   ├── css
│   │   └── index.scss
│   ├── data
│   │   ├── replacements.json
│   │   └── site.json
│   ├── fonts
│   ├── img
│   ├── js
│   │   └── index.js
│   ├── views
│   │   ├── layout
│   │   │   └── default.hbs
│   │   ├── partials
|   |   |   └── *.hbs
│   │   ├── helpers
|   |   |   └── *.js
│   │   ├── pages
|   |   |   └── *.hbs
├── gulpfile.js
│   ├── functions
│   |   └── *.function.js
│   ├── tasks
│   |   └── *.task.js
│   ├── config.js
│   ├── index.js
├── .babelrc
├── .editorconfig
├── .eslintrc
├── .stylelintrc.json
└── env.config.js

Build files

Note: Development and staging builds have -development and -staging postfixed to the file names.

Development:

/
├── build
│   ├── assets
│   │   └── css
│   │   └── fonts
│   │   └── img
│   │   └── js
|   ├── index.html
|   └── *.html

Staging, Production:

/
├── build
│   ├── assets
│   │   └── css
│   │   └── js