HTML/CSS/JS Project Template

Use this template to initialize your HTML+CSS+JS project (front end). This project template is pre-configured and contains automation scripts that will make your project starting a lot easier.

Prerequisites

• A BASH-like shell (bash and zsh work well)
• Node.js installed and working
• An active connection to the Internet
• The curl utility, which is installed by default on Linux, macOS, and Git BASH

Features

The following features are present:

1. Pre-configured with all dependencies listed in package.json
2. Pre-configured with the GitHub Linters workflow
3. A .gitignore file generated by gitignore.io with extra ignores
4. Scripts to initialize all the tools and run the pre-commit tasks
5. Empty index.html template and directory tree
6. Instructions (this file) to set up everything and get all working

Working tree architecture

• ./: the root of the tree, here you have your index.html, package.json, .gitignore and other files
  • ./.github/: this is the GitHub workflows folder
  • ./.gitignore: a file to instruct git what patterns you do not want to track
  • ./assets/: contains some folder where you can organize your assets
  • ./build/: a folder where you can place the output of preprocessors, minifiers, and compilers
  • ./gulpfile.js: a gulp worker that will help you to auto-prefix CSS files
  • ./index.html: an empty HTML index page
  • ./initialize.sh: a sh script that will initialize your project
  • ./package.json: a description of the current project and it's dependencies for Node
  • ./src/: a folder where you can organize the original (i.e. SASS) files to be compiled or processed
  • ./README.md: this wonderful file

Step 1: get the code

This is a template repository, therefore working with it is as simple as clicking the big green Use This Template button.

Alternatively, if you don't want to drag the commits into your repository, you can download a compressed .zip file and extract it inside your work tree.

Step 2: initializing the template

This template is an empty template. Here are some things that you want to change before initializing the template:

• Update your .gitignore accordingly to your project
• Be careful of changing the title of the template index.html
• Change the project name, URL, version, description, and any detail of the package.json before running any script or Node
• After reading this file, you should write a relevant README.md for your project

After that, use a BASH-like shell to run the initialize.sh script, like this, running it from the root of the working tree:

$SHELL initialize.sh

This will download and install all dependencies and configuration files. Note that this README.md file will be moved to README.md.old and replaced with the template README.md.

Check your terminal output, it should show no errors.

Step 3: running pre-commit tasks

The pre-commit task is tasks meant to be run before committing your code and pushing it to your repository. Mainly, they will run the linters, compiler, and any other relevant task.

If you understand the UNIX shell and know how to program in BASH, you can extend the pre-commit task easily by modifying the script. Otherwise, you can open a GitHub issue here.

Once everything is set up, and you are ready to commit, you can run the following command:

$SHELL tasks.sh

For specific use cases, you can change some parameters, regarding what you want to run, what not, modify some assumptions and behavior. This is done by setting up Environment Variables.

If everything looks good, you can commit and push.

Environment Variables

The behavior of the pre-commit task is modified by the usage of environment variables. As you read in the Archlinux Wiki, there are several ways of setting up variables, and with different scopes and persistence. The following variables modify the behavior"

Variable	Default	Effect
RUN_GULP	yes	If this variable is set to anything but yes, no gulp task will be run for this project.
RUN_GULP_STYLES	yes	If yes, run the gulp styles task, which will auto-prefix all .css files inside ./src/css/ and put them inside ./build/css/. You can edit the output folder by modifying guilpfile.js.
RUN_HINT	yes	If yes, run the hint (webhint) linter in the root of the source tree.
RUN_STYLELINT	yes	If yes, run the stylelint (Stylelint) linter in the root of the source code tree.
STYLELINT_MATCH_PATTERN	**/*.{css,scss}	This is a pattern that will match any .css or .scss (pure CSS or SASS) files. This is a shell globbing, which looks like a regular expression but is quite different.
RUN_LHCI	yes	If yes, run the lhci (Lighthouse) web auditor in your project.

Author's notes

Please, take your time to understand what the scripts do, how, when, and why. You don't need to be shell savvy to understand what commands are being executed.

Read the documentation to the Wikis carefully, if you are new to the Bourne shell, you will find them really helpful. This work is in progress, and any feedback is welcome.

If you have a problem or suggestion

Open a GitHub issue explaining what is wrong. If you have problems with your scripts, copy the output of the shell command. For better feedback, replace the $SHELL part of the command with $SHELL -x.

If this work is useful

Do not hesitate of opening a GitHub issue telling me that you enjoyed this work. Also, do not hesitate to give this repository a nice golden star.

---

Copyright (c) 2020 Oever González, this project is free and open-source under the MIT license