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 used for the project management and building:
- Project management:
- Manage dependendies: npm
- Manage git hooks: husky
- Run multiple npm-scripts in parallel or sequentially: npm-run-all
- Watch changes: onchange
- Release: standard-version
- CSS:
- Ensure correct formatting: Prettier
- Sass: Sass / node-sass
- Support old browsers: PostCSS / Autoprefixer
- JavaScript:
- i18n:
- Replace placeholders with language strings: mustache / mustache.js
- Markdown, JSON, YAML, YML:
- Ensure correct formatting: Prettier
Get the code using git (install git
first if
necessary):
git clone https://github.com/severo/pesticides_website.git
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.
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 generallydist/
orbuild/
are used, but usingdocs/
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.
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
```
-
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
-
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 themain.css
file):npm run build:css:postcss
-
Do both in one call (first SASS, then PostCSS):
npm run build:css
-
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 browsersnpm 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 Englishsrc/lang/en.json
i18n JSON file, and place the generatedmain.en.js
file insrc/lib/
:npm run build:js:mustache:en
-
Replace mustache placeholders in
docs/lib/main.mustache.js
with the corresponding strings from Portuguesesrc/lang/pt.json
i18n JSON file, and place the generatedmain.pt.js
file insrc/lib/
:npm run build:js:mustache:pt
-
Replace mustache placeholders in
docs/lib/main.mustache.js
with the corresponding strings from Spanishsrc/lang/es.json
i18n JSON file, and place the generatedmain.es.js
file insrc/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
-
Replace mustache placeholders in
src/index.mustache.html
with the corresponding strings from Englishsrc/lang/en.json
i18n JSON file, and place the generatedindex.html
file insrc/
:npm run build:html:mustache:en
-
Replace mustache placeholders in
src/index.mustache.html
with the corresponding strings from Portuguesesrc/lang/pt.json
i18n JSON file, and place the generatedindex.pt.html
file (note the.pt
part) insrc/
:npm run build:html:mustache:pt
-
Replace mustache placeholders in
src/index.mustache.html
with the corresponding strings from Spanishsrc/lang/es.json
i18n JSON file, and place the generatedindex.es.html
file (note the.es
part) insrc/
:npm run build:html:mustache:es
-
Generate the files for all the languages
npm run build:html:mustache
or
npm run build:html
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.
Some other scripts are only a help for the developer.
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
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).
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
-
Read https://github.com/damonbauer/npm-build-boilerplate/blob/master/package.json and add more processing if useful. See also https://buzut.fr/npm-for-everything/ and https://buzut.fr/configurer-rollup-bundles-esm-cjs/
-
give hints to configure editors (add an
.editorconfig
file?) -
ESLint: add support for async/await: https://babeljs.io/docs/en/babel-plugin-transform-async-to-generator? (maybe it's already supported)
-
minify (terser?)
-
uglify?
-
tree shaking (already done by rollup?)
-
version generated CSS and JS files and automatically replace the links in index.html
-
automatically deploy the files in
docs
before a commit, and add to git staged files (see https://docs.npmjs.com/misc/scripts) -
add a "clean" script, with rimraf?
-
add unit tests
-
add integration tests
-
if we minify: add a header banner (see how it's done in D3.js)
-
add CI tools: Codacy, Travis?
-
only one script (
npm run serve
) to replace the need for bothwatch
andserve
. But simply launchingrun-p server watch
fails to capture all the changes. -
when the build fails in
watch
, the script needs to be restarted. Find how to avoid this and simply handle the errors. -
maybe compute automatically the data hashes (see src/data/ files). Currently it's done manually with:
cat estados.topojson | openssl dgst -sha384 -binary | openssl base64 -A