CodyHouse Framework + Components are featured on Product Hunt! Join the discussion →

Understanding the CodyHouse Framework Gulp configuration file

Learn how you can speed up your workflow using the Gulp configuration file of the CodyHouse Framework.

1) Watch asset changes and reload your project #

The following lines in the gulpfile.js take care of reloading your browser when you change a HTML/SCSS/JS file:

gulp.task('watch', gulp.series(['browserSync', 'sass', 'scripts'], function () {
  gulp.watch('main/*.html', gulp.series(reload));  
  gulp.watch('main/assets/css/**/*.scss', gulp.series(['sass']));
  gulp.watch('main/assets/js/components/*.js', gulp.series(['scripts']));
}));
  • When a .html file inside the 📁main folder is updated, the browser reloads your project so that you can preview the updated content.
  • When a .scss file inside the 📁main/assets/css folder is updated, the 'sass' task is executed: it takes care of converting SCSS to CSS code (and more!). Take a look at section 2 and section 3 for more details about the 'sass' task.
  • When a .js file inside the 📁main/assets/js/components folder is updated, the 'scripts' task is executed: all .js files in that folder are combined in a single scripts.js file. Take a look at section 4 for more details about the 'scripts' task.

2) Convert SCSS code to CSS code #

The 'sass' task takes care of compiling your SCSS code to CSS code. And way more!

Each time one of your .scss files is updated, the gulp-sass module converts all your SCSS code to compressed CSS code; the autoprefixer module is then used to add vendor prefixes where required. The final code is then saved in the style.css file.

The 'sass' task does not stop here: in the CodyHouse framework, we use CSS custom properties which are not supported in older browsers (IE11 and below).

When the SCSS code is compiled to CSS, a second .css file (style-fallback.css) is created: in this file, the CSS custom properties are replaced with their values to provide a fallback for older browsers.

This way, you can serve the style.css file to modern browsers and the style-fallback.css to older browsers. 

To do so, insert the following code in the <head> element of your page (replacing the style <link> element); you'll find this code already included in the index.html file of the framework:

<script>
  if('CSS' in window && CSS.supports('color', 'var(--color-var)')) {
    document.write('<link rel="stylesheet" href="assets/css/style.css">');
  } else {
    document.write('<link rel="stylesheet" href="assets/css/style-fallback.css">');
  }
</script>
<noscript>
  <link rel="stylesheet" href="assets/css/style-fallback.css">
</noscript>

Why do we need to create two separate CSS files rather than a single .css file that includes both CSS custom properties and fallback? Because we serve a lighter CSS file to both modern and older browsers. The style.scss contains only the CSS variable definitions and var() declarations (with no need to duplicate code to support older browsers). On the other hand, the style-fallback.css won't include the CSS variable definitions or var() declarations but only the computed variable values.

3) Import CodyHouse components style #

The CodyHouse library of components is a collection of HTML, CSS, JS components that work seamlessly with the framework.

If you want to include the .scss code of one or multiple components in your project, here's what you have to do:

  • Create a 📁components folder inside 📁main/assets/css; in this new folder, create a new .scss file for each component SCSS code:

    Components folder for scss code
  • In the style.scss file, make sure to import the new component .scss files. Here's what your style.scss file would look like:

    Import components scss code

Each time a file is created/updated inside the 📁main/assets/css, the 'sass' task takes care of re-compiling the CSS.

Additionally, we use the gulp-sass-glob module so that you can import all the SCSS files in the 📁components adding a single line of code to the style.scss file:

@import 'components/**/*.scss';

What about files order? Importing SCSS files in the proper order is crucial for the style to work properly. For example: if component-2 depends on component-1 (or is a variation of that component), then you'll need to make sure its style is imported after the one of component-1.

The 'sass' task imports .scss files based on an alpha-numeric order (e.g., _1_modal-window.scss will be imported before _2_modal-video.scss).

To help you import the SCSS files in the right order, the .scss code of each CodyHouse component includes the file name you can use:

Import components scss code

We use an index (1, 2 or 3, based on the component dependencies).

4) Combine and compress multiple JS files #

When including multiple .js files (for example, you are importing multiple CodyHouse components), you would need to make sure they are combined in a single (compressed) .js file. The Gulp configuration file can help you in that as well. 

If you want to include the .js code of one or multiple components in your project, create a 📁components folder inside 📁main/assets/js; in this new folder, create a new .js file for each component:

Components folder for js code

Each time a file is created/updated in 📁main/assets/js/components, the 'scripts' task will run.

This task combines the util.js file of the framework (utility functions used in all the Components) and all the .js files inside the 📁components in a single scripts.js (not minified) file and scripts.min.js (minified) file (we use the gulp-concat module for that).

What about files order? As discussed in section 3, the .js files inside 📁components should be imported in the correct order.

Once again, you'll find the file name to use for each component at the top of the component code:

Import components js code 

That's all for the Gulp configuration file! 😉

Feedbacks/suggestions? Get in touch on Twitter.

Project duplicated.