@gbg/gbgcomponentlibrary NPM

Using the system

A component library is only as good as the projects that consume it.

npm i @gbg/gbgcomponentlibrary --save

Once thats installed you should include the CSS (node_modules/gbgdesignsystem/dist/bundle.js) and JS (node_modules/gbgdesignsystem/dist/bundle.js) bundles in your project.

Standard Web Projects

For standard web projects this can be done like so (after copying gbgdesignsystem to your document root):

<html>
  <head>
    ...

    <link
      href="gbgdesignsystem/dist/gbgcomponentlibrary.css"
      rel="stylesheet"
    />
  </head>
  <body>
    ...

    <script src="gbgdesignsystem/dist/gbgcomponentlibrary.js"></script>
  </body>
</html>

SCSS Based Projects

Projects using an SCSS pre-processor can consume the SCSS directly. This is done by setting the the relative directory of GBG component assets in a SCSS variable $gbg-component-asset-path before using the main.scss file. Doing this will make all scss variables available in your scss files. Setting a scss variable is necessary because SASS implementations do not provide url rewriting https://github.com/sass/libsass/issues/532

$gbg-component-asset-path: '../node_modules/@gbg/gbgcomponentlibrary/dist/src/assets';
@import '@gbg/gbgcomponentlibrary/dist/src/main.scss';

...

React Projects

We have a specific library for react based projects.

The library is a thin wrapper around this library, allowing for easier consumption in react projects.

Angular Projects

In an Angular project this can be achieved by adding the resources to your angular.json file like so:

{
    "projects": {
        "your-project": {
            "architect": {
                "build": {
                    "options": {
                        "styles": [
                            ...,
                            "./node_modules/gbgdesignsystem/dist/gbgcomponentlibrary.css"
                        ],
                        "scripts": [
                            ...,
                            "./node_modules/gbgdesignsystem/dist/gbgcomponentlibrary.js"
                        ]
                    }
                }
            }
        }
    }
}

Contibuting

Getting set up

make sure your node & npm installations are up to date! (node version 14.0.0 runs best)

Then in the project root:

npm install

And your done!

Editing

Now to work on the project run:

npm run storybook

This will launch storybook and start watching for changes.

finally run

npm run build

to build a final product, done!

Auto Documenting

Each of the html files containing a component also contains a syntax highlighted code sample for that component. This allows us to use saas documenting tools like zeroheight, to display storybook pages, and avoid having to manually update code samples.

To enable auto documenting of a section of code in a html file, wrap that code in comments like this:

<!--CODESAMPLE_BEGIN: A_KEY-->
...YOUR CODE...
<!--CODESAMPLE_END: A_KEY-->

Where A_KEY is replaced by a unique to the page key for that sample.

Then add a place for that sample to be written out, like this:

<!--CODESAMPLE: A_KEY-->
<pre class="code-sample" CODESAMPLE="A_KEY"><code class="language-html"></code><pre>

The comment line is important here. Now whenever the project is built the contents of the code block will be filled with an encoded version of the script, and the documentation will always stay up to date!

Code Syntax Highlighting

The syntax highlighting that can be seen in the code samples component is provided by the prismjs script, this is a superlightweight script that allows for highlighting on a ton of languages.

The plugin babel-plugin-prismjs is used by the webpack config to configure the prism build, and only include those features that we want, keeping the build size down to a minimum.

Adding a language or plugin

New languages or prism plugins can be added to the build by adding importing them in the ./src/index.ts file.

Releasing a new version

We follow a pull request pattern for contributions. All contributions should be in their own feature branch.

Before performing the realease steps, ensure all your changes are committed!

To release a version, and tag it, use the command:

npm run release

This will prompt you to select the type of version bump, bump the version number, create a git commit, tag that commit and push it, done!

FYI: The above command only commits the package.json file (and the lock file) all other changes must be committed first before running this command.

You should then open a new pull request for your changes, this will be reviewed and any required changes will be highlighted. If your changes are accepted they will be merged to the master branch and your new version will be built and published.