@stokr/components-library

React UI library for STOKR apps: modals, forms, navigation, tables, auth context, styles.

Contents

• Quick start — install, router, AuthProvider, styles
• Configuration reference — config keys & helpers
• AuthProvider & AuthContext
• Troubleshooting
• Development

Quick start

Install

npm install @stokr/components-library
npm install react react-dom styled-components react-router-dom

Peers: React 18+/19+, styled-components 6.x, react-router-dom 6.x when you use routing-driven components (HeaderHo, MainMenu, …).

1. Router — Navigation helpers need a React Router:

import { BrowserRouter } from 'react-router-dom'
import { RouterWrapper } from '@stokr/components-library'

// Normal app
root.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>,
)

// Outside a Router: RouterWrapper wraps children in BrowserRouter once.
// Inside an existing Router: it renders children only (no nested BrowserRouter).
root.render(
  <RouterWrapper>
    <App />
  </RouterWrapper>,
)

2. Auth & runtime config (required when consuming via npm) — Vite freezes import.meta.env inside pre-built deps, so push your .env at runtime via config:

import { AuthProvider } from '@stokr/components-library'

export default function App() {
  return (
    <AuthProvider
      config={{
        apiUrl: import.meta.env.VITE_API_URL,
        baseUrlPublic: import.meta.env.VITE_BASE_URL_PUBLIC,
        cookieDomain: import.meta.env.VITE_COOKIE_DOMAIN,
        websiteDomain: import.meta.env.VITE_WEBSITE_DOMAIN,
        photoApiUrl: import.meta.env.VITE_PHOTO_API_URL,
        onboardingUrl: import.meta.env.VITE_ONBOARDING_URL,
        dashboardUrl: import.meta.env.VITE_DASHBOARD_URL,
        adminUrl: import.meta.env.VITE_ADMIN_URL,
        registerUrl: import.meta.env.VITE_REGISTER_URL,
        firebase: {
          apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
          authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
          projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
          storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
          messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
          appId: import.meta.env.VITE_FIREBASE_APP_ID,
          measurementId: import.meta.env.VITE_FIREBASE_MEASUREMENT_ID,
        },
      }}>
      {/* app */}
    </AuthProvider>
  )
}

3. Earlier config (e.g. analytics before mount): import { configure } from '@stokr/components-library' with the same shape as config.

4. Icons / fonts — Optional: <IoniconsStyles /> at root, or rely on lazy injection when a component uses icons; for Layout / Open Sans: import '@stokr/components-library/styles.css'.

5. Imports — import { ConfirmModal, Button, … } from '@stokr/components-library'.

Full URL env example:

VITE_WEBSITE_DOMAIN=example.com
VITE_ONBOARDING_URL=https://signup.example.com
VITE_DASHBOARD_URL=https://dashboard.example.com
VITE_ADMIN_URL=https://admin.example.com
VITE_REGISTER_URL=https://example.com/signup

Configuration reference {#runtime-config}

| config key | Typical VITE_* | Role | | ----------------- | -------------------------- | ----------------------------------------- | | apiUrl | VITE_API_URL | Authenticated REST base | | baseUrlPublic | VITE_BASE_URL_PUBLIC | Public API base | | cookieDomain | VITE_COOKIE_DOMAIN | Auth cookie domain attribute | | websiteDomain | VITE_WEBSITE_DOMAIN | Bare host → links / getPlatformURL() | | photoApiUrl | VITE_PHOTO_API_URL | Avatars / media | | onboardingUrl | VITE_ONBOARDING_URL | Full signup/sign-in app URL | | dashboardUrl | VITE_DASHBOARD_URL | Investor dashboard URL | | adminUrl | VITE_ADMIN_URL | Venture / admin dashboard URL | | registerUrl | VITE_REGISTER_URL | Public registration entry | | firebase | VITE_FIREBASE_* | Firebase client config |

Helpers: getConfig('…') for any key above; getPlatformURL() → https://{websiteDomain}; getAnalyticsIngestUrl(), getBackofficeAppUrl(path); getFooterGroups() replaces static footer URL lists.

Auth-only HTTP: authenticationApi.post(segment, body) for auth/*; default axios stays the main API client after login.

Missing overrides may trigger a one-time warning listing unresolved VITE_* expectations.

AuthProvider & AuthContext {#authprovider-optional-props}

AuthProvider is wrapped with withRouter — mount it inside a Router so redirects work.

Optional provider props

• inactivityTimeMs — Idle timeout before auto-logout + session modal (default 5 min).
• accessTokenExpiryMs — Cookie TTL when Auth.setAccessToken runs (default DEFAULT_TOKEN_EXPIRY_MS = 1 h); not extended by getUser alone.
• hideInactivityModal — Suppress built-in session modal.
• customValidateGetUser(user) — Hook after user/get succeeds (see src/context/AuthContext.js).

AuthContext consumer {#authcontext-usecontext}

import { AuthContext } from '…' then useContext(AuthContext).

• Invalid Firebase guard: value is { user: null, isFetchingUser: false } only (no methods).
• State (grouped): user / firebaseUser, isFetchingUser, avatar; MFA (waitingFor2fa, userMfaEnrollment, firebaseError); verify-email (verifyEmailError, isVerifyingEmail); session UX (loggedOutDueToInactivity, loggedOutDueToCookieExpiry, sessionExpiryPendingReason).
• Actions (grouped): userRef, loginUser, logoutUser, getUser, setUser, updateUser, refreshIdToken; checkUserIsValid, checkTokenIsValid; uploadPhoto, deletePhoto, checkUserPhoto; MFA enroll / verify / unenroll + reset2faFlow; subscription/onboarding helpers; password & email (handleResetPassword, handleVerifyEmail, requestUpdateEmail, …); wallets / PoA (uploaProofOfAddress keeps the source spelling); dismissSessionExpiryModal.

Use AuthConsumer for the render-prop pattern.

Troubleshooting {#troubleshooting}

useNavigate / Router

Add BrowserRouter (or RouterWrapper from this package where the shell has no router). Install react-router-dom.

Invalid hook call / duplicated React

Dedupe peers in Vite: resolve: { dedupe: ['react', 'react-dom', 'styled-components'] }.

Development {#development--publishing}

| Command | Meaning | | -------------------- | -------------------------------- | | npm run storybook | Local docs / stories | | npm run build:dist | Library build + static copy | | npm run pub | Build then publish (npm login) |

Release: changelog entry → npm version → npm run pub. Details: CHANGELOG.md.