# Gearbox.js

Gearbox is a set of open-source front-end components natively integrated with Cognite Data Fusion (CDF). The Gearbox components are written in the React front-end framework and make it easier to build web applications on top of CDF.

# Install the Gearbox library and dependencies

1. Install the library:

• yarn: yarn add @cognite/gearbox
• npm: npm install @cognite/gearbox --save

2. Install additional dependencies:

• yarn: yarn add @cognite/sdk @cognite/griff-react antd styled-components
• npm: npm install @cognite/sdk @cognite/griff-react antd styled-components --save

# Getting started

1. Set up the SDK context.

   To set up the SDK context, you need to add in ClientSDKProvider. Mount it near the top level and make sure that ALL usages of Gearbox are within this Provider.

   import { CogniteClient } from "@cognite/sdk";
   import { ClientSDKProvider } from "@cognite/gearbox";
   
   // ...
   
   const sdk = new CogniteClient({ appId: 'new-app' })
   
   // ...
   
   sdk.loginWithOAuth({ project: tenant }); // or other authentication methods
   
   // ...
   
   <ClientSDKProvider client={sdk}>
   
   // The part of your app that uses Gearbox
   
   </ClientSDKProvider>
   

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   

   For more information, see the SDK documentation:

   • Authentication
   • SDK Documentation

2. Load the components and start using Gearbox.

   import { /* Component_name */ } from "@cognite/gearbox";
   import 'antd/dist/antd.css';
   

   1
   2
   

   or

   import * as gearbox from "@cognite/gearbox";
   import 'antd/dist/antd.css';
   

   1
   2
   

   You can also import separate components and reduce the bundle size of your app:

   import {
     TenantSelector
   } from "@cognite/gearbox/dist/components/TenantSelector";
   

   1
   2
   3
   

NOTE: You MUST use the Gearbox components inside the ClientSDKProvider. To learn more about context and why this is important, see React Context.

# Examples and tutorials

You can find example Gearbox applications in our public repository. Also, see our YouTube channel for Gearbox video tutorials.

# Storybook

See the up-to-date storybook here.

# Contribution

# Development

To build the library locally it's required to have version of node installed not lower than 10.10

# Tests

Utilising Jest and Enzyme you can test your component

Run yarn test

# Deploy

We use Semantic Versioning 2.0.0 for the package version.

To deploy a new version to NPM follow these steps:

1. Create a new branch from the master branch.
2. Do any neccessary changes (if any).
3. Bump version -> run $ npm version patch|minor|major. Example: $ npm version minor.
4. Push branch to GitHub
5. Create pull request and prefix the PR-name with v{YOUR_VERSION} - {NAME} (example: v1.5.2 - My PR)
6. Ask for review and merge when approved
7. Travis will automatically deploy the new version to https://www.npmjs.com/package/@cognite/gearbox

# License

Apache 2.0