Starter kit Part 1 - Folder structure

If you work in an agency or you are very fertile, chances are you start new project every now and then. Set it up correctly and miss nothing can be time-consuming challenge, it is error-prone and not particularly enjoyable either. To combat this issue, I've built a starter kit. It utilizes Gulp 4, contains essential tasks and folder structure with some basic code is ready. Now I can just download it, make few adjustments if needed, and start working. The starter-kit is available on github. Feel free to give it a spin or just enhance your current workflow with some practices mentioned here. If you will end up with improved workflow, I'll be happy.

Before I began building it, I outlined several requirements:

  1. Folders and files should be ready - In my case that means folder structure as I am used to - source folder with subfolders for different kinds of assets, and distribution folder for generated ones. In source folder I would already have some code, because the foundation is pretty much always the same. I don’t wanna start with a blank slate, I think no one does.

  2. Gulp with common tasks I often need - I am keen user of Gulp and I use it for myriad of things. Since project I work on are very similar, it is pointless to start from scratch everytime. Like this I can have one place, where I keep the most recent version of the tasks.

  3. It should allow for easy adjustment - Fitting kit to our needs must be easy. If it is problematic to adjust, it would defeat whole point of it, which is shaving off some work, time and cursing.

  4. It should be well-arranged so others can use it without problems - Last, but not the least, there will be other developers who will have to use it or manage it. Clear structure, documentation and help should be in place.

Now I’d like to share how I solved it. In this article, I’ll explain the first part - basic setup.

Folder structure

There are three main parts. Source folder, distribution folder, where everything is compiled to. And lastly Gulp, .gitignore, readme, etc. Names of the folders are chosen so it conveys clear information to everyone on the team.

.
|____.gitignore
|____frontend-dist
|____frontend-src
| |_____unversioned-source
| |____img
| |____js
| | |____libs
| | |____modules
| |____scss
| | |____modules
| | | |_____...
| | |____style.scss
| | |____utils
| | | |_____...
| |____svg
| |____twig
| | |_____base-layout.twig
| | |____components
| | | |_____...
| | |____index.twig
|____gulp
| |____...
|____gulpfile.js
|____LICENSE
|____package.json
|____readme.md

Frontend source

All of my source code and assets are neatly tidied in frontend-src folder.

___frontend-src
|_____unversioned-source
|____img
|____js
| |____libs
| |____modules
|____scss
| |____modules
| | |_____...
| |____style.scss
| |____utils
| | |_____...
|____svg
|____twig
| |_____base-layout.twig
| |____components
| | |_____...
| |____index.twig

Sass

In order to write styles efficienly, I use Sass. Main stylesheet imports many smaller chunks of code. I have two distinct groups of Sass files. First ones are utilities. Mixins, config, helpers, grids, typographic and universal styles belong here. Order matters - style.scss deals with that. Second group is modules. These are unique to given project. They are included to stylesheet with gulp automatically. It might seems slightly complicated system at first, but ultimately it makes our job not only more powerful, but even easier. I’ll write about this in more depth another article.

___scss
|____modules
| |____...
|____style.scss
|____utils
| |_____...

Javascript

In Javascript I both use my own scripts and vendor libraries. I keep the js files separated, because it allows me decide how I will process it. Often I want to concatenate my files, while keep vendor ones alone so I can decide where and when I load it.

___js
|____libs
|____modules

Img, svg and _unversioned-source

Images are stored in img folder and minified by gulp. You can use subfolders, too. SVG is minified and output both as single files and combined into one SVG sprite. You can then use it in HTML as a sprite, or reference given picture in CSS. I keep also _unversioned-source folder for big source images. They are easily in reach, while not blowing up repository.


Twig

I like to use template language twig, because it allows me to addopt more modular approach of building templates. Templates stays in root of this folder and only them get compiled. Reausable blocks and in components folder. Basically it is very simple atomic design workflow. _base-layout.twig extends all the other pages. It holds all the <meta> etc. Because it starts with _, it won’t be compiled.

| |____twig
| | |_____base-layout.twig
| | |____components
| | | |_____...
| | |____index.twig

Frontend distribution

All the assets mentioned above are compiled/copied to frontend-dist folder. HTML is in root, which let us use relative paths in templates. Thanks to this you can deploy templates in staging server with ease.


.gitignore

.gitignore exclude node_modules, frontend-dist and _unversioned-source.

Gulp

Next time, I’ll describe how I utilized Gulp in this starter kit.