Cognite documentation

Gearbox.js

Build Status codecov Storybook

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
  1. Install additional dependencies:
  • yarn: yarn add @cognite/sdk @cognite/griff-react@~0.4.2 antd styled-components
  • npm: npm install @cognite/sdk @cognite/griff-react@~0.4.2 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:

  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 guidelines

Feel free to contribute to the project, but first have a look at our guidelines

Compatibility

Gearbox v1 compatible with @cognite/sdk v2 and Gearbox v2 compatible with @cognite/sdk v3 packages.

License

Apache 2.0