synapse-react-client

4.0.9 verified Sat Apr 25 auth: no javascript

React component library and client SDK for integrating with the Sage Bionetworks Synapse API. Current stable version is 4.0.9, released monthly. Provides pre-built React components (EntityFinder, SynapseTable, etc.) along with React Query hooks and a SynapseContextProvider for managing authentication and caching. Supports TypeScript, MUI theming, and SCSS customization. Differentiated by official Synapse platform integration and a comprehensive set of data access and visualization widgets for biomedical research portals.

Common errors

error Module not found: Can't resolve 'synapse-react-client' ↓

cause Package not installed or import path incorrect

fix

Run 'npm install synapse-react-client' and ensure import is correct: 'import { ... } from "synapse-react-client"'

error TypeError: Cannot read properties of undefined (reading 'accessToken') ↓

cause SynapseContextProvider missing or not wrapping the component

fix

Wrap component tree with <SynapseContextProvider synapseContext={{ accessToken: '...' }}>...</SynapseContextProvider>

error Error: Could not find react-query context ↓

cause React Query provider not set up

fix

Wrap app with <QueryClientProvider client={queryClient}> from @tanstack/react-query

error Uncaught ReferenceError: require is not defined ↓

cause Using CommonJS require in ESM environment

fix

Use ES module import syntax instead of require(). Set type: 'module' in package.json if needed.

Warnings

breaking React 19 peer dependency required as of v4.0.0 ↓

fix Upgrade React and React DOM to >=19.2.0. If on React 18, stay on v3.x.

breaking ESM-only since v3 - CommonJS require will fail ↓

fix Convert to ES module imports. Use 'import' syntax instead of require.

gotcha SynapseContextProvider must wrap all components; missing provider leads to runtime errors ↓

fix Wrap your component tree with SynapseContextProvider and provide an accessToken.

gotcha Access token handling - do not hardcode tokens in client-side code ↓

fix Obtain token via secure OAuth flow or environment variables (server-side). Provide as prop to SynapseContextProvider.

deprecated Some components from v2 may have been removed or renamed in v4 ↓

fix Check changelog for breaking changes. For v3->v4 migration, consult upgrade guide.

Install

npm install synapse-react-client

yarn add synapse-react-client

pnpm add synapse-react-client

Imports

SynapseContextProvider

wrong

const SynapseContextProvider = require('synapse-react-client').SynapseContextProvider

correct

import { SynapseContextProvider } from 'synapse-react-client'

ESM-only. Use named import. Provider must wrap all components.

EntityFinder

wrong

import EntityFinder from 'synapse-react-client/EntityFinder'

correct

import { EntityFinder } from 'synapse-react-client'

Named export, not a default export. Path imports may break tree shaking.

SynapseClient

wrong

import SynapseClient from 'synapse-react-client'

correct

import { SynapseClient } from 'synapse-react-client'

SynapseClient is a namespace object, not a default export.

Quickstart

Shows minimal setup with QueryClientProvider, SynapseContextProvider, and EntityFinder component.

import { SynapseContextProvider, EntityFinder } from 'synapse-react-client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import React from 'react';
import ReactDOM from 'react-dom/client';

const queryClient = new QueryClient();
const myToken = process.env.SYNAPSE_ACCESS_TOKEN ?? '';

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <SynapseContextProvider
        synapseContext={{
          accessToken: myToken,
          isInExperimentalMode: false,
          utcTime: true,
        }}
      >
        <EntityFinder
          entityTypes={['org.sagebionetworks.repo.model.Project']}
          selectMultiple={false}
        />
      </SynapseContextProvider>
    </QueryClientProvider>
  );
}

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<App />);