Garage Components

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

Getting Started

1. You need to install garage-component's peerDependencies into your project. React, Ramda, etc...

2. Now you can install the garage-components:

npm install @justgarage/garage-components

3. You'll need to configure your builds to work with the SCSS styles setup before you can use the 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.

SVGs

If you plan on using SVG, Icon or Logo components, you also need to set up SVG loading in your project to use html markup instead of base64 one.

Assuming webpack, you should use the following loader definition:

// e.g. webpack config for `modules.rules`
{
  test: /\.svg(\?v=\d+\.\d+\.\d+)?$/,
  use: [
    {
      loader: 'svg-inline-loader',
      options: { removeTags: false, removeSVGTagAttrs: false },
    },
  ],
}

JavaScript

There are 2 options for integrating the garage components: Option 1 import the source files and compile them in your project. Option 2 import the lib files that have been already compiled into your project.

option 1

Import some files from lib:

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

These will require some assets and scss that you should configure as instructed for Styles.

These are also pre-minified so not so nice to debug with.

option 2

If you want to optimise your bundles, you can import the JavaScript source files directly, this is more complicated however.

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

PR Development

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

Workflow:

1. Make your branch

2. Make your changes, clean them, commit them.

3. i. Update your changelog and then:

4. ii. Make a new commit using for the prelease by manually changing the package.json version to something like 0.234.0-alpha.0. Use the version as a commit message.

5. Publish your version as an alpha dist tag as shown below.

When publishing, a prepublishOnly command compiles the JavaScript using babel from /src into /lib also assets and styles are copied into /lib.

npm publish --tag=alpha --access=public

5. Push your changes to origin branch and make the PR.

NOTE: remember to update changelog in your commit

TODO: We want to automate this versioning process but having Circle make new commits is undesired.

6. IMPORTANT: We need to take control of how the versioning syncs with the deploy. So, we use either Squash and merge or merge commit strategy and ensure the merge commit message contains [ci skip] in it's message.

7. Once merged, remember to pull the changes down into your host master branch and release a minor or major or patch version:

npm version minor # or major or patch
npm publish

NOTE: the changelog might be out of sync at this point. E.g. you have documented your alpha changes but just released as a minor, so change your Changelog and put it in the same commit as the tagged version commit.

8. This will create a new commit with version which you will also need to push and trigger a release using the new version

git 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

Starting the stylepage in productionish mode after building:

npm start

This will also install any missing dependencies to start the server and then open the index.js with a cheecky express app.

Deploying

To deploy the stylepage, first build the stylepage image:

npm run deploy-build -- dev

After building the image, you can deploy; this also happens during builds.

You'll need to set the appropriate environmental variables. The deploy script will have a look for a .env file to populate these for convenience.

DOCKER_USERNAME=
DOCKER_PASSWORD=
AZURE_SERVICEPRINCIPAL=
AZURE_PASSWORD=
AZURE_AD_TENANT=

Then deploy:

docker run -it -v $(pwd):/root/garage-components microsoft/azure-cli

# then inside the image
cd ~/garage-components
./scripts/deploy prod

Code of Conduct

TODO

Continuous Integration

TODO