afresquet / express-template

Template to create Express servers

My Express Template

An Express Template I did to learn some coding and GitHub stuff, there are many wrong things with it so it shouldn't be used.

---

Table of Contents

1. TL;DR
2. Getting Started
   • System Preparation
   • Local Instalation
3. Views
4. Sass
5. JavaScript
6. Gulp
   • watch
   • sass
   • javascript
   • img-min
   • route
   • yaml
   • nodemon
   • browser-sync
   • Create a new task
   • Add a task to gulpfile.js
7. i18n

---

TL;DR

• Install locally following the Getting Started section.

• Run the command gulp inside the directory to start the server and browser-sync. This also watches for files and restarts the server/reloads the browser when needed.

• Files are written modularly, and Gulp takes care of making them work. Just need to add them where gulp requires to (Sass files under ./assets/css/main.scss and Javascript files in the files array under ./gulp-tasks/javascript.js).

• Internationalization with i18n is built in. Make the .yml files under ./locales/ and they get converted into .json. Their route and cookie also get automatically created.

---

Getting Started

System Preparation

1. Install Node.js.
2. Install Gulp globally running npm install gulp -g.

Local Installation

1. Clone or download this repository.
2. Run npm install inside its directory.

---

Views

Pug is the View Engine used, the files get automatically rendered as HTML.

Find the views folders under ./views/

---

Sass

Sass is used to style the pages, it gets both compiled to CSS and minified with Gulp.

Place the Sass files under ./assets/css/

main.sass

This is where every file gets imported into a single file. It should be declared in the desired order with the keyword @import followed by the file source, like this:

@import 'base/base'

@import 'layouts/container'

@import 'modules/header'
@import 'modules/footer'

@import 'pages/index'

The compiled and minified file, and its sourcemap, are located at ./public/css/.

---

Javascript

Javascript files go inside ./assets/js/

Everything should be written on its own file to keep the scripts modular, but declaring variables in _vars.js and declaring events in _events.js.

To see where to add the files to get them compiled, check the gulp javascript task.

The compiled and minified file, and its sourcemap, are located at ./public/js/.

---

Gulp

Gulp is used for development in this app. The gulpfile is located at ./gulpfile.js.

It runs the server, watches files and runs the necesary tasks when different files get modified.

The command used to run all the previously said is:

$ gulp 

We'll look at all the available tasks now.

$ gulp watch

This task is found in ./gulp-tasks/watch.js and watches for four things:

1. Modified .sass files under ./assets/css/, runs the task sass.
2. Modified .js files under ./assets/js/, runs the task javascript.
3. Adding images under ./assets/img, runs the task img-min.
4. Modified .yml files under ./locales/, runs the task yaml.

$ gulp sass

This task is found in ./gulp-tasks/sass.js and does the following:

1. Compiles the main.sass file into CSS.
2. Adds any necessary prefixes required by some browsers.
3. Minifies the file to make its size smaller.
4. Creates a sourcemap for clarity.

The resulting files go to ./public/css/.

$ gulp javascript

This task is found in ./gulp-tasks/javascript.js and does the following:

1. Concatenates all provided files into a single one.
2. Minifies the file to make its size smaller.
3. Creates a sourcemap for clarity.

The resulting files go to ./public/js/.

$ gulp img-min

This task is found in ./gulp-tasks/img-min.js and minifies the images to make them use less space.

The optimized images go to ./public/img/.

$ gulp route -r nameOfRoute

This task is found in ./gulp-tasks/route.js and does the following:

1. Creates the route file under ./routes/.
2. Copies some content to the clipboard to add to index.js to make the route work.
3. Creates a pug file for the route under ./views/.
4. Creates a sass file for the page under ./assets/css/pages/ (which needs to be added to main.sass).

The content to be set inside of each file and clipboard can be changed inside the task file, their variables are:

let jsContent = `...`;

let clipboard = `...`;

let pugContent = `...`;

let sassContent = `...`;

$ gulp yaml

This task is found in ./gulp-tasks/yaml.js and converts the locale files from .yml to .json.

$ gulp nodemon

This task is found in ./gulp-tasks/nodemon.js and does the following:

1. Starts the server.
2. Restarts the server whenever a file changes.

$ gulp browser-sync

This task is found in ./gulp-tasks/browser-sync.js and does the following:

1. Runs the nodemon task.
2. Starts a Browser Sync server and opens a new Google Chrome window with it.
3. Reloads the browser whenever a file changes.

Create a new task

To create a new task make a new file under ./gulp-tasks/ with the name of the task and the .js extension.

The file should look like this:

'use strict';

// REQUIRES (requiring gulp is not needed)
const example = require('gulp-example');

// TASK EXPORT
module.exports = (gulp) => {
  return () => {
    // This should be the task function
    return gulp.src('foo/bar.js')
      .pipe(example())
      .pipe(gulp.dest('foo'))
  };
};

Add a task to gulpfile.js

Once the task is created it has to be added to the gulpfile.

To do that use the getTask('fileNameHere') function as the callback function like this:

gulp.task('sass', getTask('sass'));

Note that the parameter inside getTask() has to be a string and the exact name of the file without the extension.

---

i18n

To use more than one language add the locale files inside ./locales/ as .yml files.

Routes and cookies get automatically created for each locale file except the default (default locale has to be hardcoded) under ./routes/locales.js.

Locale files get converted from .yml to .json with Gulp.

i18n is added as a local automatically for every route created with the $ gulp route command, under the object t like this:

res.render('pug-file', {
  t: res.__
});

It's used inside a pug file like this:

h1 #{t('foo.bar')}

Which outputs the content of the current locale file:

foo:
  bar: "Hello world!"