How to Architect a Multi-Tenant Frontend Application

The application must identify which tenant is being accessed before rendering anything. Resolve the tenant from the subdomain by extracting the prefix from the hostname on application load. Alternatively resolve from the URL path prefix or from a custom domain mapped to a tenant in a lookup table. Fetch the tenant configuration from the server using this identifier before rendering any UI, as the configuration drives theming, feature availability, and authentication setup.

Each tenant requires its own brand colors, logo, typography, and potentially custom CSS. Store tenant theme values as CSS custom properties on the document root element. When the tenant configuration loads, apply their specific token values by setting properties on the root element. All components reference only the semantic token names, never raw values. Switching tenants means replacing the root-level token values, which instantly re-themes the entire application.

Global state must never contain data from a different tenant due to miscached state. Include the tenant ID as part of all cache keys in React Query, localStorage, and any other caching layer. When the active tenant changes, invalidate and clear all cached data before fetching tenant-specific data. Fail loudly in development when any data operation occurs without a tenant context attached to prevent accidental cross-tenant data leakage.

Different tenants subscribe to different feature tiers. Store feature entitlements in the tenant configuration fetched on load. Create a useFeature hook that checks whether a feature is enabled for the current tenant before rendering any associated UI. Feature-gated components render nothing or a disabled placeholder when the feature is not in the tenant's entitlement. This architecture allows deploying a single codebase that presents a different product surface to each tenant.

Each tenant may use a different identity provider. One tenant authenticates through Google Workspace, another through an enterprise SAML provider, and another through username and password. Fetch the tenant's authentication configuration before rendering the login screen. Initialize the correct authentication SDK based on the tenant's configuration. Ensure all issued tokens are scoped to the specific tenant so API calls automatically include the tenant context without additional work from the frontend.

Routes must be scoped to prevent tenants from accidentally navigating to another tenant's content. For subdomain-based tenants, routing works normally since each subdomain is a separate origin. For path-prefix-based tenants, prefix all routes with the tenant identifier and ensure the router never strips it. Deep links shared between users must include the tenant context so recipients arrive at the correct tenant's version of the content rather than a generic entry point.

Fetching tenant configuration on every page load adds latency before the application can render. Cache the tenant configuration at the CDN edge using the subdomain or tenant ID as the cache key. Set cache durations based on how frequently tenant configurations change. For configurations that rarely change like logos and colors, use long cache durations with cache busting on configuration updates. For configurations that affect security like authentication settings, use short durations or no caching.

Enterprise tenants commonly operate in multiple countries with different languages, date formats, currency symbols, and number formatting conventions. Each tenant configuration should specify supported locales and the default locale. Load only the locale files required for the current tenant rather than bundling all available translations. Apply the tenant's locale to all date, number, and currency formatting throughout the application using the Internationalization API rather than manual string manipulation.