Cognite documentation

# Gearbox.js

Build Status (opens new window) codecov (opens new window) Storybook (opens new window)

Gearbox (opens new window) is a set of open-source front-end components natively integrated with Cognite Data Fusion (CDF) (opens new window). The Gearbox components are written in the React (opens new window) 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 (opens new window).

# Examples and tutorials

You can find example Gearbox applications in our public repository (opens new window). Also, see our YouTube channel (opens new window) for Gearbox video tutorials.

# Storybook

See the up-to-date storybook here (opens new window).

# 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 (opens new window)