Node.js version 8.9.0
, but might work with earlier versions.
npm install
Installation of ImageMagick or GraphicsMagick is not required, since all optimized and resized images are already included (see Build/Images).
Build process is controlled with gulp
, and its config is located in file gulp/config.js
.
Everything is built into /build/
directory and server must be run from there.
There are two commands, one is to build everything once, the other is to build and then watch source files for changes:
npm run build
— Builds everythingnpm run watch
— Builds everything, and then watches for changes injs
/scss
/html
files, changes in/assets/root/
and/assets/images/processed/
directories.
There are 3 build flags, which can be passed to either one of the build commands:
-
--dev
/--prod
1.1. Applies minification if it is production.
1.2. Adds.min
extension to filenames ofjs
andcss
files if it is production.
1.3. Writes sourcemaps forcss
files if it is development.
1.4. Calculates separate hash for chunks in webpack if it is production.
Note:--prod
can be omitted, by default production version is used. -
--analyze-js-bundle
If present — runs webpack bundle analyzer after build is complete.
Note: Should be run with anpm run build
command, since there is generally no need to continually analyze bundle after each build. -
--source-maps
If present, enables source maps in webpack build, slows scripts build process a little. Source maps for webpack are disabled by default.
Examples:
npm run watch -- --dev
npm run watch -- --dev --source-maps
npm run build -- --prod --analyze-js-bundle
Webpack
is run as one of the steps of the build process. Configuration file for webpack is located in root of the project in a file webpack.config.js
.
Scripts (except service worker) are build into three chunks.
vendor
chunk — common scripts for every page.index
chunk — code, specific to the index pagerestaurant
chunk — same, but for restaurant page
Scripts are transpiled with babel
into ES5
syntax.
All resulting js
files have its hash inserted into resulting filenames.
Webpack build also generates webpack-manifest.json
file with the information about built files. This file is used later, to build html files and service worker.
Sass
is used with its scss
syntax.
There is only one resulting css
file — bundle[.min].css
.
bundle.scss
file references all the files used in the build in the specific order: scss
variables first, then normalize
, then basic styles, then components and so on.
BEM-like naming is used for css
classes.
There is an option serializeCSSBundle
in the gulp/config.js
file, which if set to true
serializes contents of the bundle into <style>
tag and puts it into <head>
of resulting html pages.
By default it is set to true
.
If it would be set to false
, then css
bundle will be linked to resulting html files in a regular way with the <link>
tag.
This option also affects build of the service worker.
Note: gulp-sourcemaps
plugin is currently not working because of conflict with gulp-autoprefixer
plugin, might be fixed in the near future, but for now css is without sourcemaps.
There is a list of pages (just 2 of them) in the gulp/config.js
file, with a titles set for them.
Gulp task generate-html
iterates over that list to generate these pages.
For each page it takes layout.html
file as a template.
Then list of params is passed to layout.html
through gulp-ejs
package.
Params include:
- name of page
html
file and the title of the page. - hashed filenames of
js
files. - hashed filename of
css
bundle or serialized content of it. - google maps api key.
Note: Google maps key is set in gulp/config.js
file and is limited to localhost
domain.
Service worker is built in gulp task generate-sw
.
- It uses parameter
cacheForeignResources
fromgulp/config.js
to decide if google maps resources need to be cached. By default it isfalse
and google maps resources are cached in service worker. Some metrics scripts from google maps are not cached and even aborted for a speed. - Uses parameter
serializeCSSBundle
to see if css bundle is serialized in content of pages and if the css bundle needs to be cached separately. By default it istrue
, and service worker does not cache css bundle separately. If set tofalse
, then it would read filename of css bundle fromstyles-manifest.json
and cache it. - Reads all names of
js
chunks fromwebpack-manifest.json
to decide whichjs
-files to cache. - Reads directory
/assets/root/
for a list of icons/favicons/json/xml that also need to be cached.
Resulting service worker is located at the root of build directory /build/sw.js
.
Note: Transpiling is not used for service worker to greatly simplify its debugging, and therefore it is written with es5 syntax to avoid any problems with browsers that do support service worker, but not fully support es6 features or syntax.
Resized and optimized images are already included.
Original images directory: /assets/images/src/
Processed images directory: /assets/images/processed/
Build commands are simply copying already processed images to the /build/assets/images/
directory.
If there is a need to resize+optimize them again, the command npm run build-images
needs to be run.
For this command to correctly work, there needs to be installed either ImageMagick or GraphicsMagick.
Parameter magick
in gulp/config.js
chooses which one is used in the build process.
Note: Tested only with GraphicsMagick, but should work with ImageMagick also.
HTTP Server needs to take the /build/
directory as the root.
In the package.json
there is a script named server
, that can be run as a command npm run server
from the project's root directory, it starts server on the 8000
port.
It uses Node.js server package serve
.
Python server python -m SimpleHTTPServer 8000
also works, but is scoring MUCH worse in the lighthouse audit and might throw errors. DO NOT use python server for evaluation.
npm install
npm run build
npm run server
— starts server onlocalhost:8000