Website Build Process - OpenDataEnterprise/sdg-nri-website GitHub Wiki

The build process for the SDG National Reporting Initiative can be broken down into multiple steps. The broadest steps consist of:

  1. Processing assets via a combination of npm scripts and Webpack.
  2. Building pages via Jekyll.

Note: Netlify is configured to automatically build the production and staging websites when it detects changes to the website's GitHub repository, so no manual builds should be necessary. The process is only being outlined for informative purposes, or if you are setting up a local development environment.

Configuration Files

Configurations to be used with webpack in compiling the JavaScript should be in _app/config (e.g. _app/config/development.js).

Configurations to be used with Jekyll in building pages should be placed in the project root directory and begin with _config (e.g. config-development.yml).

npm scripts

All of the npm scripts are defined in package.json under the project root directory. A number of them are environment-specific and are configured to execute commands in a chained manner, including invoking a Jekyll build. You can use either npm or Yarn to run the npm scripts.

Environments

The current npm scripts support builds for three different environments:

  • development
  • staging
  • production

Pre and Post Hooks

One mechanism to understand about npm scripts is the convention of pre and post hooks. From the official npm script documentation:

Pre and post commands with matching names will be run for those as well (e.g. premyscript, myscript, postmyscript).

As an example, to kick off a development build, you can run either npm run build:development or yarn run build:development depending on which package manager you're using. This first runs the prebuild:development script before running the build:development script.

Build Commands

Development

To build the website for a development (typically local) environment, run either:

  • npm run build:development
  • yarn run build:development

Staging

To build the website for a staging environment, run either:

  • npm run build:staging
  • yarn run build:staging

Production

To build the website for a staging environment, run either:

  • npm run build:production
  • yarn run build:production

Tips for Development

You can have local processes watch and rebuild your development environment as you make changes. This makes it more convenient to develop as you won't have to manually trigger the rebuild process every time.

To watch for changes to both the CSS and JavaScript when developing locally, run:

yarn run compile-sass --watch & yarn run compile-js:development --watch

Then to run a Jekyll server that automatically rebuilds the site when it detects changes, run:

bundle exec jekyll serve --config=_config.yml,_config-development.yml

Processing Images

Images in _app/images will be processed through the compress-images.js script before being output into the assets/img directory.

Resulting build artifacts should output to assets/img.

Webpack

Styles

webpack.sass.js contains the webpack configuration to process all of the styles in _app/sass. The current process:

  1. Compiles the SCSS files into CSS.
  2. Runs the compiled CSS through Autoprefixer.
  3. Minifies the resulting CSS.

Resulting build artifacts should output to assets/css.

Scripts

webpack.config.js contains the webpack configuration to process all of the scripts in _app/scripts. The current process:

  1. Compiles the scripts and Vue components, resolving any dependencies.
  2. Minifies the resulting scripts.

Resulting build artifacts should output to assets/js.

Jekyll

Jekyll will take all page files and resolve any templates or includes to generate finished pages under the _site directory.

Any directory not beginning with an underscore _ will be unprocessed by Jenkins and moved directly to the _site directory, along with its contents, such as assets.