synapse-react-client

Synapse React Client

This project helps you integrate your app with the Synapse API backend.

See the available Components

Getting started with Synapse.

Synapse.org is a client written for the Synapse platform.

Interested in contributing to this project? See contributing.

Installation

Run the following command:

npm install synapse-react-client

Usage

See index.ts for a comprehensive list of components that can be used.

To function properly, all components must be wrapped in a SynapseContextProvider. To make authenticated requests, you must provide the user's access token as a property to the context provider, among other values. You may maintain this in state, or provide it however you like.

The context provider also maintains a shared cache (via react-query). It is recommended to place the provider at the highest possible point in your component tree, and to use the same provider across components if possible.

Example:

const myToken = "example-token" // this value may also be undefined, if a user is not signed in
const useUtcTime = true
const inExperimentalMode = false

<SynapseContextProvider synapseContext={{ accessToken: myToken, isInExperimentalMode: inExperimentalMode, utcTime: useUtcTime }} >
  <EntityFinder {...entityFinderProps} />
</SynapseContextProvider>

Setting Endpoints

Configuring endpoint destinations for repo and portal

Specifying the following in the window object will override request endpoints:

window.SRC_OVERRIDE_ENDPOINT_CONFIG = {
  PORTAL: '<endpoint>',
  REPO: '<endpoint>',
}

Note - this will apply to all calls being made.

Theming

We are primarily using MUI for styling and per-app theming. We provide a default theme in DefaultTheme.ts which can be overridden with your own theme properties.

SCSS

Synapse React Client also uses Dart Sass. The core css lives in src/style and src/template_style.

For a list of variables you can override, see src/style/abstracts/_variables.scss.

Override the variables by importing the SCSS in your project like so:

@use 'synapse-react-client/dist/style/main.scss' with ($primary-action-color:
      $-my-primary-color, $secondary-action-color: $-my-secondary-color, // ...any other overrides continue);
@use 'synapse-react-client/dist/template_style/Index.scss';

In this example, make sure that your node_modules folder is in your Dart Sass load path.

Project Contents

├── ./src
│   ├── ./assets    Assets such as svgs/pngs needed for logos or buttons
│   ├── ./components  Contains all React components
│   ├── ./style   Contains scss stylesheets
│   ├── ./synapse-client   Functions used to call the Synapse REST API
│   ├── ./synapse-queries   react-query hooks used to interact with the Synapse REST API
│   ├── ./template-style   Contains scss stylesheets
│   ├── ./theme   Utilities and exports for MUI theming
│   └── ./utils   Contains utilities
├── ./mocks Mock data used for testing and stories
├── ./test Tests for all components and utilities
└── ./stories Storybook stories for components

Adding a new component and Publishing a new version of SRC

To expose a component from the library you must export it from index.ts. Ideally, your component will get its own subfolder within src/components/, which will contain an index.ts file that exports the public API of the component (typically the component and its props type). In src/components/index.ts, you can then export the contents of the new subfolder.

To expose a component for use in synapse.org, you must export it from SWC.index.ts. Note that certain dependencies are not included in this bundle. See the config used to build the bundle, vite.config.ts, for more details.

Available Scripts

Before doing anything else run:

pnpm install

In the project directory, you can run:

pnpm start

Runs Storybook, which allows you to inspect and interact with components.

pnpm test

Launches the test runner in the interactive watch mode.

Links to Resources on Testing:

• Vitest: https://vitest.dev/
• React Testing Library: https://testing-library.com/docs/react-testing-library/intro

pnpm build

Bundles the library for production to the dist folder.

pnpm build:js

Bundles the library for production to the dist folder using Vite's library mode. This command creates CJS and ESM bundles with all dependencies removed, and also outputs a single TypeScript declaration file.

Note - this script is run automatically as part of the build command.