Skip to content

Latest commit

 

History

History
391 lines (287 loc) · 11.1 KB

BUILD.md

File metadata and controls

391 lines (287 loc) · 11.1 KB
Raw

Build

This file is intended to explain the process of building the project, based on npm scripts. If you want to install or deploy the website, see INSTALL.md instead. If you want to contribute to the code, see CONTRIBUTE.md.

Technologies

Technologies used for the project management and building:

Get the code

Get the code using git (install git first if necessary):

git clone https://github.com/severo/pesticides_website.git

Install the dependencies

Then enter the cloned directory and install the npm dependencies (install npm first if necessary):

cd pesticides_website
npm install

Note that most of the dependencies are for development only.

Structure of the code

The repository is composed of three main parts:

  • src/: the source code of the website, in HTML (with mustache placeholders), JS and SASS.

    Development takes place there.

  • docs/: the compiled code, ready to be deployed. Note that generally dist/ or build/ are used, but using docs/ allows to automatically deploy the website on GitHub Pages without any hassle.

    This directory is completely created at build time, and is versionned to make it easier to deploy on GitHub Pages. It should never be modified by hand.

  • files at the root of the repository: doc files, npm dependencies, configuration files.

    Only modify if you want to improve the software project management.

Workflow

The workflow to compile the src/ source code directory into the docs/ output directory realize a series of processings. There are detailed in that section.

To build them all, launch

```bash
npm run build
```

Linters

  • Test the format of JavaScript files with ESLint, and exit with error if a file is not formatted according to eslint rules.

    npm run lint:test:js

  • Test the format of JSON, Markdown, SCSS, YAML and YML files with Prettier, and exit with error if a file is not formatted accorded to prettier rules, showing a list of the files to fix.

    npm run lint:test:other

  • Test both in one command

    npm run lint:test

Note that the configuration for Prettier is defined in the .prettierrc.json file, and that .prettierignore lists the files to ignore when linting with prettier. Similarly, the configuration file for ESLint is .eslintrc.json.

These configuration files should be taken into account by your editor and allow it to fix the files. Otherwise, you can fix the files with the following scripts. Note that they modify the files, and must be launched manually:

  • Fix the format of JavaScript files inline with ESLint

    npm run lint:fix:js

  • Fix the format of JSON, Markdown, SCSS, YAML and YML files inline with Prettier

    npm run lint:fix:other

  • Fix all files inline in one command

    npm run lint:fix

CSS

  • Generate the CSS file in the build directory (main.css) from the Sass file (main.scss):

    npm run build:css:sass

  • Add vendor CSS prefixes (-webkit-, -moz-, -ms-) to improve the support for old browsers (inline modification of the main.css file):

    npm run build:css:postcss

  • Do both in one call (first SASS, then PostCSS):

    npm run build:css

JavaScript

  • Bundle the ECMAScript modules (ESM) in only one file: docs/lib/main.mustache.js. Note that it also calls Babel to add retrocompatibility for old browsers

    npm run build:js:rollup

    The .babelrc configuration file for Babel currently points to the @babel/preset-env preset.

    The Rollup configuration file (for bundling ES modules, and calling Babel) is rollup.config.js.

  • Replace mustache placeholders in docs/lib/main.mustache.js with the corresponding strings from English src/lang/en.json i18n JSON file, and place the generated main.en.js file in src/lib/:

    npm run build:js:mustache:en

  • Replace mustache placeholders in docs/lib/main.mustache.js with the corresponding strings from Portuguese src/lang/pt.json i18n JSON file, and place the generated main.pt.js file in src/lib/:

    npm run build:js:mustache:pt

  • Replace mustache placeholders in docs/lib/main.mustache.js with the corresponding strings from Spanish src/lang/es.json i18n JSON file, and place the generated main.es.js file in src/lib/:

    npm run build:js:mustache:es

  • Generate the files for all the languages

    npm run build:js:mustache

  • Do both in one call (first Rollup, then Mustache):

    npm run build:js

HTML

  • Replace mustache placeholders in src/index.mustache.html with the corresponding strings from English src/lang/en.json i18n JSON file, and place the generated index.html file in src/:

    npm run build:html:mustache:en

  • Replace mustache placeholders in src/index.mustache.html with the corresponding strings from Portuguese src/lang/pt.json i18n JSON file, and place the generated index.pt.html file (note the .pt part) in src/:

    npm run build:html:mustache:pt

  • Replace mustache placeholders in src/index.mustache.html with the corresponding strings from Spanish src/lang/es.json i18n JSON file, and place the generated index.es.html file (note the .es part) in src/:

    npm run build:html:mustache:es

  • Generate the files for all the languages

    npm run build:html:mustache

    or

    npm run build:html

Deployment

The GitHub repository is configured to automatically deploy the website to https://severo.github.io/pesticides_website/ on every new commit on the master branch.

The website files are copied from the /docs directory (destination of the build). This means that the docs directory must be built before every commit, in order the changes to be deployed.

Note that before allowing to commit, a pre-commit hook is launched with husky that triggers npm run test and so cancel the commit if any error appears.

Scripts for development

Some other scripts are only a help for the developer.

Watch

To automatically build the website, and then rebuild it when a source file changes, launch:

npm run build-and-watch

More in details:

  • watch, without building the project before:

    npm run watch

  • watch for changes in JavaScript files and rebuild on change:

    npm run watch:js

  • watch for changes in SASS files and rebuild on change:

    npm run watch:css

  • watch for changes in HTML files and rebuild on change:

    npm run watch:html

  • watch for changes in i18n strings files and rebuild on change:

    npm run watch:lang

Serve

To launch a web server on the docs/ directory:

npm run serve

The configuration for Browsersync is defined in the bc-config.js file.

Note that you certainly want to run both npm run serve and npm run watch at the same time (in two terminals).

Release

The development MUST be done in the develop branch, and the commits must follow the Conventional Commits Specification.

To release a new version:

git checkout master; git pull origin master
git merge develop
npm run release
git push --follow-tags origin master && npm publish

TODO