Front-end Gulp DevStack

Gulp stack for building optimized static pages and exports for collaboration between coders and programmers.

Table of contents (click to expand)

• Typical use cases
• Features
  • Something more under the hood
• Getting Started
  • Installation
• Project structure
• Workflow
  • Development
  • Production Build
  • Export Build
• Updates from devstack to your existing project
• Inject devstack to your new project
• Roadmap and Known issues
• Contributing
• License
• Contact

Typical use cases

• Developing landing pages or prototypes (npm run dev).
• Building carefully compiled and formated files for collaboration (npm run export).
• Building the final (production) bundle, ready for deployment (npm run deploy).

When you want to build whole web sites from the data sources as API or many markdown files, go with Static Page Generators (SGC). For example Gridsome (VueJS), Gatsby (React) or Hugo (Go) will work for you much better.

Features

• SEO-friendly — Open Graph and Twiter Cards markup, self/canonical.
• User-friendly — image optimizations, favicons, webmanifest and all sources minification to smallest bundle.
• Developer-friendly — ESLint, Prettier, Remark, Stylelint via tasks or with Husky and Lint staged.
• Separate tasks for Development, Export and Build with automatic renaming and hashing all critical assets.
• Ready for implementation Git based CMS as Tina CMS or Netlify CMS etc. — Front Matter (Markdown files metadata and content).
• HTML temlates uses Nunjucks. Fully customisable Bootstrap 5.3.x extended with BEM. JavaScript processed with Babel or injected from CDN or as static files.

---

	Preprocessing / Linting	🛠️ Development Postprocessing	👁️ Export Postprocessing	💯 Build Postprocessing
CSS	SASS / Stylelint	PostCSS (Autoprefixer, prettify)	PostCSS (Autoprefixer, prettify)	PostCSS (Autoprefixer, cssnano, PurgeCSS)
JavaScript	Babel / ESLint	only concatenate	concatenate & uglify	concatenate & uglify
HTML	Nunjucks	prettify	prettify	minify
Content & Metadata	Markdown / Remark
JPG, SVG		imagemin	imagemin	imagemin
PNG		UPNG.js	UPNG.js	UPNG.js
Fonts		gulp-google-webfonts	gulp-google-webfonts	gulp-google-webfonts
Favicons			Favicons	Favicons
Workflow hints		Browsersync

Something more under the hood

• Linting all commit messages by CommitLint, see more about Semantic Commit Messages and Conventional Commits
• Commit guide on the CLI by git-cz
• Automatic releases with Release It!, see more about Semantic Versioning
• Changelog with Conventional Changelog
• Gitflow
• Build and deployment to FTP.

Getting Started

Installation

1. Node.js and npm are required.

2. Clone the repository into the new project directory PROJECT_NAME

   git clone https://github.com/cebreus/gulp-devstack/ ./PROJECT_NAME

3. Go to project directory PROJECT_NAME and install npm dependencies

   cd PROJECT_NAME && npm i

4. Optional clenup (click to expand)

   • Clean CHANGELOG.md

     > CHANGELOG.md

   • Change or remove LICENSE.txt by rm LICENSE

     rm LICENSE

   • Change this README.md according to your new project or replace it from the template

     curl https://gist.githubusercontent.com/cebreus/a6010a2a95a4f2375830b0af3193f2f9/raw/cde6d9c68f2605b34eb5b8710bd553e7ad28a678/minimalistic-readme > README.md

   • Change these data in the package.json accordng to your new project

     • name
     • description
     • keywords
     • author
     • license
     • private
     • repository
     • homepage
     • bugs

Project structure

• /.github

  Specialties designed for GitHub.

• /content

  • /pages — each *.md is data source for templates; each file corresponds to the template ./src/pages/*.html
  • site.md — contains default data for all pages

• /gulp-tasks

  Common Gulp tasks for Development workflow. Do not edit unless you know what you are doing.

• /gulp-tasks-build

  Common Gulp tasks for Build workflow. Do not edit unless you know what you are doing.

• /gulp-tasks-export

  Common Gulp tasks for Export workflow (compiled and formated bundles). Do not edit unless you know what you are doing.

• /src

  Development directory. This is place of developers creativity. Change anything as you wish.
  • /gfx — graphic assets
  • /js — JavaScripts, all files in this directory will be concatenated into one file; files are sorted by name
  • /scss
    • _variables.scss — copy from the Bootstrap core for your customization.
    • bootstrap.scss — copy from the Bootstrap core for your customization.
    • c-article.scss — example of the BEM component Article.
    • custom.scss — main stlesheet for customization of the project. Contains additions and overriding of the Bootstrap.
    • u-debugger.scss — only in Developmnet workflow adds outline and info around HTML element with [BEM namespaces](BEM component. Outlines objects o-, component c- and utilities u-. To enable functionality set $show-debugger to true in the file _variables.scss.
    • u-show-grid.scss — only in Developmnet workflow adds small box into bottom right corner with information about current viewport size accoding to Bootstrap. In the file _variables.scss set $show-grid to true and see bars as Bootstrap grid columns.
  • /templates
    • /pages — every *.html file will be rendered as standalone HTML page on own URL (directory name). Meta attributes passes from according Markdown file in ./content directory.
    • /partials —
    • layout-default.html — main layout which extends files in ./templates/pages
  • font.list — tab-delimeted format for gulp-google-webfonts which download font files and CSS to the project.

• /static

  Content of this directory will be coppied into target (temp, export or build directory).
  • /.well-known/security.txt — definition of the security policies. Further info
  • humans.txt — detailed public information about project e.g. team members, technologies etc. Further info

• / (root)

  • .browserslistrc — Browserslist configuration to share target browsers versions between different front-end tools as Autoprefixer, Babel etc. The configuration is a copy of the Bootstrap configuration in this repo.
  • .editorconfig — basic definition of code formatting for different code editors and IDEs. These settings are used as a baseline for language specialised linters in this repo. Further info
  • .env.example — template of the .env file, where stored fragments of the code shouldn’t be part of repo’s codebase, e.g. login to FTP.
  • .eslintignore — list of the files and directories to be ignore by Eslint.
  • .eslintrc.yml — Eslint configuration to specify and configure rules of JavaScript linting. Further info
  • .gitattributes — path-specific settings used by Git. Settings that Git applies to certain subdirectories or subsets of files - for example EOL (End Of Line) setting. Further info
  • .gitignore — list of path-specific pattern to be ignored (not commited) by Git. Further info
  • .prettierignore — list of the files and directories to be ignore by Prettier.
  • .prettierrc.yml — Prettier configuration to specify and configure rules of language specific code formatting.
  • .release-it.yml — Release It! configuration to specify behaviour of the versioning and package publishing related tasks.
  • .remarkignore — list of the files and directories to be ignore by Remark.
  • .remarkrc.yml — Remark configuration to specify and configure rules of Markdown lintng.
  • .stylelintignore — list of the files and directories to be ignore by Stylelint.
  • .stylelintrc.yml — Stylelint configuration to specify and configure rules of CSS (SCSS) linting. See used plugins! Further info
  • commitlint.config.js — commitlint configuration to help adhering to a commit convention.
  • gulpconfig.js — configuration for 🛠️ development Gulp file gulpfile.js. Contains variables and setting which are specific for Development workflow purposes.
  • gulpconfig-build.js — configuration for 💯 build Gulp file gulpfile.build.js. Contains variables and setting which are specific for Build workflow purposes.
  • gulpconfig-export.js — configuration for 👁️ export Gulp file gulpfile.export.js. Contains variables and setting which are specific for Export workflow purposes.
  • gulpfile.js — Gulp 🛠️ development configuration and definition of automation tasks. Further info
  • gulpfile.build.js — Gulp 💯 build configuration and definition of automation tasks. Further info
  • gulpfile.export.js — Gulp 👁️ export configuration and definition of automation tasks. Further info
  • CHANGELOG.md — list of the notable changes in this project.
  • LICENSE — Open source license of Git repository. It enables others to freely use, change and distribute the project in the repository. Further info
  • package.json — NPM packages specifics. It lists the packages (with their versions) your project depends on. Further info
  • package-lock.json — NPM manifest. Automatically generated with change of node_modules or package.json if working with NPM. Holds information about which versions of each dependency were installed in order to get consistent installs across machines. Further info
  • README.md — It’s me!

Workflow

Development

Starts watchers, compilers etc., for development with hot-reload in the browser.

1. Run development task

   npm run dev

2. Open Browser on URL http://localhost:4000 or what you see in command-line.

3. Modify files in src directory a sub-directories.

4. Changes in the configuration files requires a restart. Stop dev task and run npm run dev again.

Production Build

Produces optimized files in production quality.

1. Run build task

   npm run build

2. See files in build directory.

Export Build

Produces optimized and formated files with good readability of the code.

1. Run build task

   npm run export

2. See files in export directory.

Updates from devstack to your existing project

1. create a branch in your project’s repo (e.g. devstack-update)

   git checkout -b devstack-update

2. Add this Gulp DevStack as a remote to your project devstack

   git remote add devstack git@github.com:cebreus/gulp-devstack.git

3. Fetch remote

   git fetch devstack

4. Merge devstack-update to your branch (e.g. master) (use --allow-unrelated-histories if necessary)

   git merge master

5. solve eventual conflicts

6. push the devstack-update branch

   git push -u devstack-update

7. create PR from devstack-update to your master

Inject devstack to your new project

git remote add devstack git@github.com:cebreus/gulp-devstack.git
git fetch devstack
git merge devstack/master --squash --allow-unrelated-histories
git commit -m "feat: Gulp DevStack init"
git merge devstack/blankenize --squash --allow-unrelated-histories -X theirs
git commit -m "refactor: Gulp DevStack clean-up"

Don't forget to customize for your project by replacing some strings or deleting files like in section "Optional clenup".

Roadmap and Known issues

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what makes the open-source community such a fantastic place to learn, inspire, and create. Any contributions you make are much appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (`git commit -m "feat: Add some AmazingFeature")
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

It is distributed under the MIT License. See LICENSE for more information.

Contact

Jaroslav Vrána — cebreus@live.com, web site

Project Link: github.com/cebreus/gulp-devstack