Skip to main content
By default, SublayProvider creates and manages its own isolated Redux store. This is the recommended approach for most projects — no Redux configuration required. If your application already has its own Redux store, we strongly recommend merging Sublay’s state into it using SublayIntegrationProvider. Running two separate Redux stores in the same React app is a common source of subtle bugs: React-Redux binds components to the nearest <Provider> in the tree, so hooks can silently read from the wrong store depending on where components are rendered.

​
When to Use This

If your app already has a Redux store, use SublayIntegrationProvider. This is the right path for virtually every app in that situation. The standalone SublayProvider is only appropriate for apps that don’t use Redux at all. The standalone provider creates its own internal store. When that coexists with your app’s store, React-Redux binds components to whichever <Provider> is closest in the tree — which means hooks silently read from the wrong store depending on where a component is rendered. These bugs are hard to spot and hard to trace. The only reason to use SublayProvider alongside an existing Redux store is if you have a specific, deliberate reason to keep the two stores completely separate and you fully understand the implications. For nearly everyone, that’s not the case.

​
Setup

Integration mode requires three changes to your existing store and one change to your provider setup.
1

Add Sublay reducers to your store

Import sublayReducers and sublayApiReducer from @sublay/react-js and add them to your store’s reducer map. The keys must be exactly sublay and sublayApi — the SDK’s internal selectors depend on these names.
import { configureStore } from "@reduxjs/toolkit";
import {
  sublayReducers,
  sublayApiReducer,
  sublayMiddleware,
} from "@sublay/react-js";
import yourReducer from "./yourSlice";

const store = configureStore({
  reducer: {
    // Your own reducers
    yourFeature: yourReducer,

    // Sublay — keys must be exactly these
    sublay: sublayReducers,
    sublayApi: sublayApiReducer,
  },
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(...sublayMiddleware),
});

export default store;
export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;
2

Replace SublayProvider with SublayIntegrationProvider

Use SublayIntegrationProvider instead of SublayProvider. This provider does not create a Redux store — it expects your own <Provider> to already be in the tree above it.
import { Provider } from "react-redux";
import { SublayIntegrationProvider } from "@sublay/react-js";
import store from "./store";

function App() {
  return (
    <Provider store={store}>
      <SublayIntegrationProvider projectId="your-project-id">
        {/* your app */}
      </SublayIntegrationProvider>
    </Provider>
  );
}

​
Props

SublayIntegrationProvider accepts the same props as SublayProvider:
​
projectId
string
required
Your Sublay project ID.
​
signedToken
string | null
A signed JWT for external authentication mode. See External Auth.

​
Exports Reference

All integration exports are available from @sublay/react-js:
ExportTypePurpose
sublayReducersReducerCombined reducer for all Sublay feature slices. Mount under the sublay key.
sublayApiReducerReducerRTK Query API reducer. Mount under the sublayApi key.
sublayApiMiddlewareMiddlewareRTK Query middleware for cache invalidation and subscriptions.
sublayMiddlewareMiddleware[]Combined array of all required Sublay middleware. Spread into your middleware chain.
SublayIntegrationProviderReact.FCContext provider for integration mode.

​
State Shape

When integrated, Sublay occupies two top-level keys in your store: 
{
  sublay: {
    auth: { ... },          // Auth tokens, current user, initialization state
    accounts: { ... },      // Multi-account list and active account
    user: { ... },          // Current user profile
    appNotifications: { ... },
    collections: { ... },
    entityLists: { ... },
    spaceLists: { ... },
    chat: { ... },
  },
  sublayApi: { ... },      // RTK Query cache (collections, entity lists, etc.)
  
  // Your own slices
  yourFeature: { ... },
}
The sublay and sublayApi keys are required by Sublay’s internal selectors. Mounting the reducers under different keys will cause the SDK to malfunction.

​
TypeScript

Sublay exports SublayState if you need to type a state slice that references Sublay’s shape: 
import type { SublayState } from "@sublay/react-js";

interface RootState {
  sublay: SublayState;
  sublayApi: unknown; // RTK Query manages this type internally
  yourFeature: YourFeatureState;
}