GravDept Frontend Starter

A simple HTML + CSS + JS baseline with Gulp build tools.

Quick start

1. Clone the repository to your computer.
2. Point a PHP/Apache server at the project root directory.
3. Recommended: setup a virtual host like project.test.
4. Run npm install.
5. Run gulp watch.

Overview

Prototype templates

Prototypes are built using PHP includes for simple templating. The output is logic-less plain HTML, which is easily adaptable to test patterns and content together.

See: http://project.test/

Code standards

Frontend code follow the GravDept code standards, which are maintained here:

• http://manuals.gravitydept.com/code/css
• http://manuals.gravitydept.com/code/html
• http://manuals.gravitydept.com/code/js

Build system

Gulp powers the frontend build system. All the frontend assets (CSS, JS, images) are processed from source material into production-ready assets.

Important build files

File	Description
.eslintrc	Configuration for JS linting. Avoid editing.
gulp/config.js	Configuration for all Gulp tasks. Edit this frequently.
gulp/error-handler.js	Show readable error message in the console from failed Gulp tasks. Avoid editing.
node-modules/	Contains Node modules installed via NPM. Never edit.
gulpfile.js	Define Gulp tasks. Add tasks as needed. Avoid rewriting tasks.
package.json	Define Node modules the build process requires. Maintain this monthly.
package-lock.json	Lock file for Node module dependencies. Never edit.
stylelint.config.js	Configuration for CSS linting. Avoid editing.

Build tasks

Task Name	Description
clean	Delete all assets generated by the build. This runs before "default" task to force all site assets to be generated.
css	Pre-process SCSS to CSS. Process SCSS to sourcemaps. Post-process CSS with Autoprefixer.
default	Run "clean" to force all site assets to be regenerated. Run all specified tasks and linters (css, image, js).
image	Optimize image files (JPG, PNG, GIF, SVG) using ImageOptim library.
js{BundleName}	Compress JS without mangling (rewriting for shortness). Concatenate into bundles. Process JS to sourcemaps.
lintCss	Lint CSS with "stylelint" module. This runs in "default" and anytime a watched CSS file is changed.
lintJs	Lint JS with "ESLint" module. This runs in "default" and anytime a watched JS file is
watch	Run "default" immediately. Start watchers for appropriate tasks.

Install build tools

• Install Node 10.15.0+
  • https://nodejs.org/en/
• Run commands:
  • cd /your/project/path
  • npm install

Run build tasks

Command	Description
gulp	Run "default" task (once)
gulp watch	Run "default" task and continue watching
gulp {taskName}	Run a specific task
gulp --hide-notify	Run "default" task (once) and suppress Mac/Windows notifications
gulp --show-properties	Run "default" task (once) and log detailed error info in the console

Maintain build tools

1. Check for outdated packages. Run: npm outdated
2. Check the package list for changes.
3. Review the release notes for each package to ensure there aren't breaking changes.
4. Update "package.json" to specify the latest (only set exact versions, no wildcards).
5. Run commands: npm update
6. Check for update errors.
7. Run the build and check for errors: gulp

Sometimes updating fails or breaks the build. Before reverting to prior versions try:

1. Delete the /node-modules folder.
2. Run npm install.
3. Test the build again.

Update build tools

1. Run npm update.
2. Check for update errors.
3. Run the build and check for errors: gulp.

Sometimes updating fails or breaks the build. Before reverting to prior versions try:

1. Delete the /node-modules folder.
2. Run npm install.
3. Test the build again.