Setup and Read Me

Alloy setup and configuration, troubleshooting

Node, Yarn, Gulp, Sass, Jekyll

Requirements

  • Node Version Manager (NVM): nvm-windows - a better way to install/manage multiple versions of Node
  • Node: nodejs.org - standalone Node if not using NVM. Latest ‘LTS’ release is a good choice
  • Yarn: yarnpkg.com - latest stable release is a good choice. Why Yarn? Control over exact npm module versions and speedy
  • Ruby (optional): ruby-lang.org - used by Jekyll

Setup

  1. Configure the Proxy and Jekyll-based paths in alloy_config/config.json (with Gulp in the web root, this is now our standard folder setup - JS, Sass and ngTemplates running from assets/_src and outputting to assets/css assets/js)
  2. Navigate to root web folder and run command yarn (this installs the packages listed in package.json)
  3. Install any missing dependencies by running command yarn upgrade
  4. If all is successful, run one of the gulp tasks listed in gulpfile.js.
    • Run as a proxy (with existing site) gulp start --site www.sitename.test
    • Run a Jekyll build (generate a static site) gulp start

If there’s a script execution issue running Gulp on Windows, see Execution Policy security issue.

Gulp is installed locally, so no need to install it globally.

What’s included

  • Sourcemaps - Specificity issues and development made easier. Corrected to linking to correct file (originally caused by using combo of gulp-sourcemaps and gulp-autoprefixer because nested files and modified line numbers weren’t correctly matched).
  • Autoprefixer - Analytics are studied and supported browsers are added to package.json, helps to ensure we output supported features, in addition appropriate manual fallbacks should be added.
  • Media Queries - Sass mixin using include-media to use any values generated or site variable.
  • Normalize - Helpful utility normalize-scss but in the future looking at reducing the amount of rules it generates, and moving it to the top of an optimised CSS file.
  • Optimised and minified - Sass is compiled to optimised CSS, and because we use BEM it’s pretty safe to allow rule restructuring too to save a tiny bit more, which works great when gzip’d.

We’ve integrated include-media and normalize-scss and they’re linked to their respective folders within node_modules. We could configure dep-linker to include these files within our Sass src files automatically, however, because we only run in Development mode, there didn’t seem much point.

Alloy Files

List of alloy files:

.jshintrc
.markdownlint.json
.prettierrc
.stylelintrc
_config.yml
Gulpfile.js
package.json
tslint.json
yarn.lock
alloy_config/config.json
alloy_config/tsconfig.json
alloy_config/stylelint/stylelint-config-jamcow.json
alloy_config/stylelint/stylelint-config-standard.json

Problems

Node

If “Node Sass does not yet support your current environment: OS X 64-bit with Unsupported runtime”:

  • try removing node_modules content and yarn install again, because yarn seems to rebuild node-sass if it needs, old fix was npm rebuild node-sass
  • else can try forcing it: yarn install --force
  • also try yarn install –check-files

Yarn

  • if Yarn issues warnings about “unmet peer dependency” see issue 4595

Ruby Gems & Jekyll

There’s a Gemfile (it acts like an npm/yarn lock file) that installs specific gem versions, generally these can be latest. For playing about with Netlify, Jekyll is kept inline with Netlify’s pre-compiled version (curently v3.8.5).

  • Jekyll may need gem install tzinfo and gem install tzinfo-data (for time zone capabilities), especially if on 64bit Windows
  • Install Bundler Gem gem install bundler -v "=2.0.1" (this should match the version in last line of Gemfile.lock, currently v2.0.1).
  • Then use Bundler to install all required Gems (listed in the Gemfile) bundle install

If you get an error running Jekyll similar to You have already activated X, but your Gemfile requires Y - it means there’s a conflict with Gem’s already installed and the versions in the gemfile of Alloy. Run bundle clean --force to remove global Gems, then bundle install to add the specific ones from Gemfile - you’ll have to swap if other projects run different versions of Gems, (or work out how to run a child process with exec as a spawn’d process in Gulp file).

Troubleshooting

Gulp (or any script) security issue on Windows 10+

Via run-as-administrator Powershell, type Get-ExecutionPolicy -List to view all policies in place.

Run Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine to enable.

        Scope ExecutionPolicy
        ----- ---------------
MachinePolicy       Undefined
   UserPolicy       Undefined
      Process       Undefined
  CurrentUser       Undefined
 LocalMachine    Unrestricted

Updating packages

yarn upgrade works reliably, and adds missing dependencies (eg, del)

yarn upgrade-interactive or yarn upgrade-interactive --latest (get very latest, possibly breaking)

Documentation

  • Need to re-add Sassdocs (not keen on lots of examples/mark-up etc being within the Sass, but it does make a lot of sense for functions/mixins).
  • Docz looks really good.

Future / ToDo’s

Configure/Extend/Experiment

  • Might need to curb cssnext some more, to not be too overzealous with next gen CSS like CSS variables
  • Look into cssnext options more and disable anything that can cause us issues
  • Write it well, modularly, using @supports and fall-backs, using linters, and ensure it’s all compatible, accessible, readable, usable.
  • Look into parker and gulp-parker2
  • WCAG 2.x
  • Heydon’s amazing inclusive components or consult the book in E78 Carbon Library
  • Update Gulp to v4.0.0 and split tasks into separate areas to make it more manageable
  • Speedup Jekyll - already added caching Jekyll includes