@just-tomht/garage-components v0.0.0-alpha.0

Garage Components

But not just components -- also some services, assets and scripts!

Getting Started

Setting up your project's .npmrc

1. As we operate on a private registry, anyone who wants to use Garage Componets has to set add the following to their project's .npmrc file

//justdigitalgarage.pkgs.visualstudio.com/_packaging/garage-packages/npm/registry/:_authToken=${JUST_NPM_TOKEN}
//justdigitalgarage.pkgs.visualstudio.com/_packaging/garage-packages/npm/:_authToken=${JUST_NPM_TOKEN}

registry=https://justdigitalgarage.pkgs.visualstudio.com/_packaging/garage-packages/npm/registry/
always-auth=true

Your password and login details for the JUST garage can be stored as in environment variable in following files (for example)

~/.profile
~/.bashrc
~/.bash_profile
~/.zshrc
~/.config/fish/config.fish

To find the details, go to the JUST digital garage VSTS page

VSTS JUST Digital Garage page

Once signed in, navigate to Build and Release, click on Packages and click on 'Connect to Feed'

On this screen select NPM and then click generate npm credentials. Copy the generated NPM _authToken value out of this screen and set it in your shell's env startup files.

e.g.

# ~/.bashrc
export JUST_NPM_TOKEN=<put_authToken_here>

NOTE: don't forget to copy the project's .npmrc file you created into it's Dockerfile definition if appropriate.

2. You need to install garage-component's peerDependencies into your project.

3. Now you can install the garage-components:

npm install @justgarage/garage-components

Styles

Prepare yourself, this is a bit hairy. Assuming webpack with a scss-loader.

Firstly, add an include of /garage-components/ to your webpack loader config for scss.

Also make sure your node_modules and STYLE folder are in scss includePaths.

// e.g. webpack config for `modules.rules`
{
  test: /\.s?css$/,
  include: [ SRC, /scss-flex-grid/, /garage-components/ ],
  loader: ExtractTextPlugin.extract({
    fallback: 'style-loader',
    use: [
      'css-loader',
      'postcss-loader',
      {
        loader: 'sass-loader',
        options: {
          outputStyle: 'expanded',
          includePaths: [ 'node_modules', STYLES ],
        },
      },
    ],
  }),
}

Next, in your scss entry, index.scss or whatever, do something like this:

// entry.scss
@import 'vars';
@import '@justgarage/garage-components/src/styles/reset';

body {
  background-color: $black-light;
}

::selection {
  background: $coral;
}

@import '@justgarage/garage-components/src/styles/fonts';
@import 'placeholders';
@import '@justgarage/garage-components/src/styles/typography';
@import '@justgarage/garage-components/src/styles/grid';
@import 'utils';

In the vars, placeholders and utils inports, make a local proxy to the garage-components file that has your local modifications in.

Here's an example for the vars.scss local proxy.

// vars.scss as a proxy
$font-path: '@justgarage/garage-components/src/styles/fonts';

@import '@justgarage/garage-components/src/styles/vars';

Finally, if you do any component specific scss imports, use your local scss proxies.

JavaScript

First, add an include of /garage-components/ to your webpack loader (or equivalent) config for js. E.g.

{
  test: /\.jsx?$/,
  include: [ APP, ..., /garage-components/ ],
  loader: 'babel-loader',
  options: {
    presets: [
      [ 'env', {
        targets: { browsers: [ 'last 2 versions' ] },
        modules: false,
      } ],
      'react',
    ],
    plugins: [
      'transform-export-extensions',
      'transform-decorators-legacy',
      'transform-class-properties',
      'transform-object-rest-spread',
      'transform-do-expressions',
      [ 'transform-builtin-classes', {
        'globals': [ 'Error' ],
      } ],
      'add-module-exports',
    ],
  },
}

You will also need the above JavaScript features (plugins) available.

We also need to ensure your server rendering and node-tests includes /garage-components/ in it's compiling. For example, this is how you can use babel-register:

require('babel-register')({
  only: [
    /src/,
    /garage-components/,
  ],
})

For javascript files we do a similiar import to the styles, but on a component level. Now you can import components directly from the src folder.

For example:

import { Section } from '@justgarage/garage-components/src/components'

As now we are relying on the garage components package.

Developing With Stylepage App

You can start the stylepage app locally by running:

npm run parcel

This enables hot-reloading of the app within the /stylepage folder.

Developing

When you npm install inside the garage-components, the peerDependencies will not be locally installed by default.

You'll need the peerDependencies installed to run the Stylepage and tests, to install them, run:

npx npm-install-peers

When working on a component's documentation in the styleapp, the cache for markdown files doesn't update in hot-reloading, so you have two options:

# either
rm -rf .cache
# or
npm run parcel -- --no-cache

When making a change in a PR, you can do a prepublish to deploy a dist tag.

NOTE: remember to update changelog in your commit

In order to npm publish you will need to add the env var JUST_NPM_TOKEN to your host env

npm version prerelease
npm publish --tag=next

Once merged, remember to pull the changes and release a minor or major or patch version

npm version minor # (or major or patch)
npm publish

This will create a new commit with version which you will also need to push

Build and Test

To run linting of javascript.

npm run lint:js

To run linting of styles.

npm run lint:styles

Whenever you commit, the linting will run as a hook using pre-commit.

To run unit tests.

npm run test

To build the project into the dist directory

npm run build

Code of Conduct

TODO

Continuous Integration

TODO