kengai v1.1.2

kengai

Kengai is a simple styleguide npm package created for the product and design team at bonsai.io.

It was built following CSS trick's handy Build a Style Guide Straight from Sass blog post.

Firing the project up locally

1. Setup: run bin/setup.

This installs node packages like kss-node, reload, and onchange. It also sets up some handy ruby rack static serving if you use (puma-dev)https://github.com/puma/puma-dev for seeing your site locally at kengai.test.

2. Build site: bin/build.

This generates the static html in public/ from changes and input in sass/. It watches the sass/ directory for any changes and builds on the fly. 🦅

3. Build & watch site: bin/watch

4. Hot reload from the directory itself (instead of using puma-dev): Run bin/reload.

This uses npm reload to navigate into the public directory, watch for changes, and refresh your browser. It's awesome.

Hacking on the styleguide layout

Kss-node allows you to define and use your own layout using handlebars and custom css. Our layout is located in the template/ directory, with custom css that we compile using node sass. To see any changes you've made to the template, you need to re-run the kss build command: bin/build. If you're making any changes to the template sass, you need to run sass in the css directory. There's a handy script for that, too: template:build, or template:watch.

Dependencies

Libraries

Kengai uses one modified library as a small foundation: Spectre CSS.

Others

Fontawesome Pro. Using kengai also means having to load fontawesome files. This may require you to let your style loader resolve the relative urls that kengai uses to load the Font Awesome files (they're within the kengai package). For example, in Webpacker, it requires that you download a url resolver (see the Rails with Webpacker section).

Using It

Access

Local Installation

If you have packagecloud set up locally, you can import the package via yarn:

$ yarn add kengai

Otherwise, you'll need to follow their Node.js documentation or run this command:

curl -s https://PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/omc/kengai/script.node.sh | bash

Remote Installation

In order for the package to install remotely, you'll need to grab a key via packagecloud.com and add it to the .npmrc file in your project:

always-auth=true
registry=https://packagecloud.io/omc/kengai/npm/
//packagecloud.io/omc/kengai/npm/:_authToken=PACKAGECLOUD_TOKEN

This will allow your server to access the package.

Rails with Webpacker

In app/assets/stylesheets/application.scss:

/* import kengai from node_modules */
@import "kengai/sass/main";

In app/javascript/packs/application.js:

import 'application.scss';

In webpacker.yml, let webpacker know where to find your assets:

resolved_paths: ['node_modules', 'app/assets/stylesheets']

Since kengai imports font files in its package, you'll need to let webpacker know how to resolve those paths (instead of looking for the font files in app/assets):

1. Load resolve-url-loader as a package.

$ yarn add resolve-url-loader -save

2. Configure the sass loader.

config/webpack/environment.js

const { environment } = require('@rails/webpacker')

// resolve-url-loader must be used before sass-loader
environment.loaders.get('sass').use.splice(-1, 0, {
  loader: 'resolve-url-loader'
});

module.exports = environment