Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

Nexus Sdk logo


Coverage Status Downloads Version License Follow on Twitter

Blue Brain Project | Nexus | Nexus API Docs | Sandbox

Examples | Getting Started | API Documentation | Development | License

This is a handy javascript toolkit that helps people just like you to interact with Blue Brain Nexus to build things like client-side applications, scripts, or backend services.

Get Started

install with your favorite package manager

npm install @bbp/nexus-sdk

import inside your client or node.js

import { createNexusClient } from '@bbp/nexus-sdk';

const nexus = createNexusClient({ uri: 'https://api.url' });

Now go and add use Nexus, such as adding resources to a project

Setup your token on client creation

const nexus = createNexusClient({
  uri: 'https://api.url',
  token: 'my_bearer_token',


You can enhance the behaviour of Nexus Client with middlewares called Links. This will add your middleware link to the front of the execution order, but it will still call triggerFetch and parseResponse links at the end. This is convenient if you just need to add something to your payload request, such as changing headers.

const nexus = createNexusClient({
  uri: 'https://api.url',
  links: [someMiddleware],

You can also use the linksOverwrite property to provide your own middleware, without any defaults. In this case, it might be useful to include the @bbp/nexus-links package to call triggerFetch and parseResonse somewhere else on the chain.

This might be usefull for implementing client-side with the native Cache api.

important! this will overwrite any suppled links array in the links property.

const nexus = createNexusClient({
  uri: 'https://api.url',
  linksOverwrite: [


You can setup a "context" object that will be passed from links to links as part of the operation

const myMiddleware: Link = (operation: Operation, forward: Link) => {
  const { myApiClient } = operation.context;
  // do something with your API client
  return forward(operation);

const nexus = createNexusClient({
  uri: 'https://api.url',
  context: {


Set your bearer token before each request:

const setToken: Link = (operation: Operation, forward: Link) => {
  const token = localStorage.getItem('myToken'); // get your token from somewhere
  const nextOperation = {
    headers: {
      Authorization: `Bearer ${token}`,
  return forward(nextOperation);

const nexus = createNexusClient({ uri: 'https://api.url', links: [setToken] });

Log response time:

const logResponseTime: Link = (operation: Operation, forward: Link) => {
  const time =;
  return forward(operation).map(data => {
    console.log('request took', - time, 'ms');
    return data;

Dispatch a redux action on every requests:

const reduxDispatcher: (dispatch: any) => Link = dispatch => (
  operation: Operation,
  forward: Link,
) => {
  const prefix = '@@nexus';
  const actionName: string = getActionNameFromPath(operation.path);
    name: `${prefix}/${actionName}_FETCHING`,
    payload: operation,
  return forward(operation).map(data => {
    dispatch({ name: `${prefix}/${actionName}_SUCCESS`, payload: data });
    return data;

Node.js support

The Nexus SDK relies on fetch, so in order to use this library in Node.js, you need to provide a fetch implementation when creating a new client. We recommend using node-fetch or even isomorphic-fetch if you build a universal app.

Request Cancellation is using AbortController, so you need to polyfill it. As documented in node-fetch, you can use abort-controller as a polyfill.


// pure node app
const fetch = require('node-fetch');

const nexus = createNexusClient({
  uri: '',

// universal app

const nexus = createNexusClient({
  uri: '',

// and then

  .then(orgs => console.log(orgs))
  .catch(e => console.error(e));



Orgs | Projects

Knowledge Graph

Resources | Schema | Files | Views | Storage | Resolver

Identity and Access Management

Realm | Permissions | Identities | ACL


The client also exposes bare http methods that can be use for operations on a resources using the _self url for example.

 * Methods exposed are:
 * - nexus.httpGet
 * - nexus.httpPost
 * - nexus.httpPut
 * - nexus.httpDelete
 * - nexus.poll
 * - nexus.context

// post something as text
  path: '',
  headers: { 'Content-type': 'text/plain' },
  body: 'Some text',

// get something as blob
nexus.httpGet({ path: '', context: { as: 'blob' } });

// poll something
nexus.poll({ path: '', context: { pollTime: 1000 } });

// you can access a base URL from context if you want to use it somewhere, for example:
const baseURL = nexus.context.uri;
const mySource = await nexus.httpGet(

You can also import constants for default view IDs or default Schema IDs:

import {
} from '@bbp/nexus-sdk';

nexus.View.get('myorg', 'myproject', DEFAULT_ELASTIC_SEARCH_VIEW_ID)
	.then(view => { // do something with my view})
	.catch(err => console.error(err));


How is the repo structured?

This repo is managed as a monorepo using lerna that is composed of multiple npm packages.

Make sure you perform the make actions in the repository root directory!

Using Docker

If you don't have Node.js installed on your machine, you can run a "docker shell" with make dshell from which you'll have a fully working Node.js environment. Make sure you have already installed both Docker Engine and Docker Compose.

Do things

  • Install: make install
  • Build: make build
  • Test: make test
  • Lint: make lint


Apache License, Version 2.0