Else React CSR SDK

Dynamic bundle loading for full React app replacement based on user/tenant context.

Overview

The Else React CSR SDK enables you to completely replace your React application bundle based on who is logged in.

How It Works

HTML loads → Bundle loader checks localStorage → Loads custom OR default bundle → Single React app starts

Security Architecture

The SDK follows a secure server-to-server architecture:

``
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Browser │ │ Vendor │ │ Else │
│ (SDK) │ │ Backend │ │ API │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
│ GET /api/bundle │ │
├─────────────────►│ │
│ │ GET /vendor-api │
│ ├─────────────────►│
│ │ (with API key) │
│ │ │
│ │ bundle URL │
│ │◄─────────────────┤
│ bundle URL │ │
│◄─────────────────┤ │
│ │ │
SDK loads bundle │ │
`

- Browser: Never sees API keys, calls vendor backend
- Vendor Backend: Authenticates users, calls Else API server-to-server
- Else API: Returns bundle URLs based on tenant configuration

Installation

`bash
npm install @elsedev/react-csr-sdk
`

After installation, run the init command to add the bundle loader to your HTML:

`bash
npx init-else
`

This will automatically update your HTML to load the bundle loader from the CDN.

Extension Loading

The SDK supports automatic loading of extensions based on URL query parameters. This allows public sharing of extensions through urls. When an extension is created with visibility mode 'public' the user will be given a share link with format https://your-domain.com?else_ext=extension-id

$3

`javascript
import { loadExtensionFromQuery } from '@elsedev/react-csr-sdk'

// Initialize extension loading
await loadExtensionFromQuery(async (identifier) => {
// Call your backend to get bundle info. Replace path with the proper path for your backend.
const response = await fetch(/api/else/bundle?ext=${identifier})
return await response.json()
})
`

$3

1. User visits URL: https://your-domain.com?else_ext=my-extension
2. SDK detects parameter: Automatically finds else_ext query parameter
3. Calls your callback: SDK calls your provided callback function
4. You call your backend: Your callback fetches bundle info from Else API via your backend
5. Loads extension: SDK loads the bundle and replaces the app

$3

You need to implement a callback function that calls your backend, which then calls the Else API:

`javascript
// Your callback function
const fetchBundleInfo = async (identifier) => {
// Call YOUR backend (not Else API directly)
const response = await fetch(/api/else/bundle?ext=${identifier})
return await response.json()
}

// Initialize SDK with your callback
await loadExtensionFromQuery(fetchBundleInfo)
`

Your backend needs a simple proxy endpoint:

`javascript
// Express.js example
app.get('/api/else/bundle', async (req, res) => {
const { ext } = req.query

// Call Else API with your vendor API key
const response = await fetch(
https://api.else.com/vendor-api/products/your-product/extensions/${ext}/bundle,
{
headers: {
'Authorization': Bearer ${process.env.ELSE_VENDOR_API_KEY}
}
}
)

const bundleInfo = await response.json()
res.json(bundleInfo)
})
`

$3

`javascript
import { loadExtensionFromQuery, loadExtension, setDebugMode } from '@elsedev/react-csr-sdk'

// Enable debug logging
setDebugMode(true)

// Load extension from else_ext query parameter
await loadExtensionFromQuery(async (identifier) => {
// Your callback: call YOUR backend, which calls Else API
const response = await fetch(/api/else/bundle?ext=${identifier})
return await response.json()
})

// Load extension programmatically
await loadExtension('my-extension-slug', async (identifier) => {
// Your callback: call YOUR backend, which calls Else API
const response = await fetch(/api/else/bundle?ext=${identifier})
return await response.json()
})
`

Quick Start

$3

The SDK uses a CDN-based approach with automatic HTML updates:

`bash
npm install @elsedev/react-csr-sdk
`

After installation, run npx @elsedev/react-csr-sdk to add the bundle loader CDN script to your index.html. The bundle loader is hosted on our CDN at https://sdk-cdn.somethingelse.ai and is versioned to match your installed SDK version.

$3

After running npx @elsedev/react-csr-sdk, your HTML will be updated. It should look like this:

`html





















`

Critical Details:
- The bundle loader script is automatically added to by the init command
- The CDN URL is versioned and matches your installed SDK version
- Add data-else-default-bundle attribute to your main app script
- After updating the SDK, run npx @elsedev/react-csr-sdk again to update the CDN URL

$3

Your backend should authenticate users and call the Else API:

`javascript
// GET /api/user/bundle
app.get('/api/user/bundle', authenticateUser, async (req, res) => {
const user = req.user; // Your authenticated user

if (!user.tenantId) {
return res.json({ bundleUrl: undefined });
}

try {
// Call Else API server-to-server with your API key
const response = await fetch(
${NEXUS_API_URL}/vendor-api/products/${PRODUCT_SLUG}/tenants/${user.tenantId}/bundle,
{
headers: {
'Authorization': Bearer ${process.env.ELSE_API_KEY}, // Keep API keys on server
'Content-Type': 'application/json',
},
}
);

if (response.ok) {
const data = await response.json();
res.json({ bundleUrl: data.bundle_url });
} else {
res.json({ bundleUrl: undefined });
}
} catch (error) {
console.error('Failed to fetch bundle from Else:', error);
res.json({ bundleUrl: undefined });
}
});
`

$3

`javascript
import { setCustomBundle, clearCustomBundle } from '@elsedev/react-csr-sdk';

// Handle user login - call your own backend
async function handleUserLogin(credentials) {
try {
// 1. Authenticate with your backend (your existing auth flow)
const authResponse = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentials),
credentials: 'include'
});

if (authResponse.ok) {
// 2. Get bundle URL from your backend
const bundleResponse = await fetch('/api/user/bundle', {
credentials: 'include'
});

if (bundleResponse.ok) {
const { bundleUrl } = await bundleResponse.json();

// setCustomBundle will exit early if bundleUrl is unchanged
setCustomBundle(bundleUrl); // Page reloads only if bundle changed
}
}
} catch (error) {
console.error('Login failed:', error);
}
}

// Clear custom bundle on logout
async function handleUserLogout() {
try {
await fetch('/api/auth/logout', { method: 'POST', credentials: 'include' });
clearCustomBundle(); // Reloads with default bundle
} catch (error) {
console.error('Logout failed:', error);
}
}
`

API Reference

$3

#### setCustomBundle(bundleUrl, reload?)

Sets a custom bundle URL and optionally reloads the page. Exits early (no reload) if the bundle URL is unchanged.

`javascript
setCustomBundle('https://cdn.example.com/custom-bundle.js', true);
setCustomBundle(undefined); // Clear bundle
`

Parameters:
- bundleUrl: string | undefined - Bundle URL or undefined to clear
- reload: boolean - Whether to reload page (default: true)

#### getCustomBundle()

Gets the currently set custom bundle URL.

`javascript
const currentBundle = getCustomBundle();
// Returns: string | undefined
`

#### clearCustomBundle(reload?)

Clears the custom bundle and optionally reloads to use the default.

`javascript
clearCustomBundle(true);
`

#### reloadWithBundle(bundleUrl)

Sets a bundle URL and immediately reloads the page.

`javascript
reloadWithBundle('https://cdn.example.com/new-bundle.js');
reloadWithBundle(undefined); // Clear and reload
`

$3

#### setDebugMode(enabled)

Enable/disable debug logging.

`javascript
setDebugMode(true); // See bundle loading logs
`

Integration Patterns

$3

`javascript
async function handleUserLogin(credentials) {
// 1. Authenticate with your backend
const user = await authenticateUser(credentials);

// 2. Get bundle URL from your backend
if (user) {
try {
const response = await fetch('/api/user/bundle', {
credentials: 'include'
});

if (response.ok) {
const { bundleUrl } = await response.json();

// Only reloads if bundle URL changed
setCustomBundle(bundleUrl);
}
} catch (error) {
console.error('Failed to load custom bundle:', error);
// App continues with default bundle
}
}
}
`

$3

`javascript
async function handleUserLogout() {
// 1. Clear session with your backend
await logoutUser();

// 2. Clear custom bundle and reload with default
clearCustomBundle();
}
`

$3

`javascript
async function switchTenant(newTenantId) {
// 1. Update tenant in your backend
await updateUserTenant(newTenantId);

// 2. Get new tenant's bundle URL
const response = await fetch('/api/user/bundle', {
credentials: 'include'
});

if (response.ok) {
const { bundleUrl } = await response.json();
setCustomBundle(bundleUrl); // Page reloads only if bundle changed
}
}
`

$3

`javascript
async function loadUserBundle() {
try {
const response = await fetch('/api/user/bundle', {
credentials: 'include'
});

if (response.ok) {
const { bundleUrl } = await response.json();
setCustomBundle(bundleUrl);
}
} catch (error) {
console.error('Bundle loading failed:', error);

// Optional: Show user notification
showNotification('Custom features unavailable, using default app');

// App continues with default bundle - no action needed
}
}
`

Global API (No Module Import Required)

If you can't use ES modules, the bundle loader exposes global functions:

`javascript
// Available on window.else after bundle-loader.js loads
window.else.setCustomBundle(url);
window.else.getCustomBundle();
window.else.clearCustomBundle();
window.else.reloadWithBundle(url);
window.else.setDebug(enabled);
`

How Bundle Replacement Works

1. Bundle Loader Script: Runs before any React code
2. localStorage Check: Looks for else_bundle_url
3. Bundle Decision:
- If custom URL found → Prevents default bundle, loads custom bundle
- If no custom URL → Allows default bundle to load normally
4. Single App: Only one React application ever starts

Bundle Requirements

Your custom bundles should:

- Be complete, standalone React applications
- Include all dependencies (React, ReactDOM, etc.)
- Mount to the same DOM element (#root)
- Handle their own routing and state management

Backend Integration Requirements

Your backend endpoint (/api/user/bundle or similar) should:

1. Authenticate the user (session, JWT, etc.)
2. Determine user's tenant ID from your user database
3. Call Else API server-to-server with your API key
4. Return bundle URL to frontend (or undefined if no custom bundle)

Example response format:
`json
{
"bundleUrl": "https://cdn.example.com/tenant-123/bundle.js"
}
`

Or if no custom bundle:
`json
{
"bundleUrl": undefined
}
`

Security Benefits

- API Keys Protected: Never exposed to browser
- User Authentication: Your backend validates identity
- Authorization: Your backend ensures user can access their tenant
- Audit Trail: Your backend can log bundle requests
- Rate Limiting: Your backend can implement limits

Debugging

Enable debug mode to see bundle loading logs:

`javascript
import { setDebugMode } from '@elsedev/react-csr-sdk';
setDebugMode(true);

// Or globally:
window.else.setDebug(true);
`

This will log:
- Bundle URL resolution
- Bundle loading attempts
- Fallback scenarios
- Error details

Troubleshooting

$3

Symptom: Both the original app and the custom bundle appear to load at once, creating UI conflicts, duplicate content, or double React mounting.

Root Cause: Race condition where the default bundle script executes before the bundle-loader can prevent it.

Solution (2 Required Steps):

1. Verify CDN Script is Present
- Check that the CDN bundle loader script exists in your index.html
- Run npm install if the CDN script is missing

2. Add data-else-default-bundle Attribute
`html

`
- Helps bundle-loader identify and prevent the default bundle
- Critical for reliable bundle replacement

3. Verify Load Order in Production
- Build your app: npm run build
- Check dist/index.html - the bundle loader CDN script should be the FIRST script in
- If not, ensure your build process preserves the script order

Debug Steps:
1. Enable debug mode in your index.html:
`html

`
2. Check browser console for bundle-loader logs
3. Look for "Found default script:" and "Preventing default bundle load:" messages
4. If you see double mounting, verify the data-else-default-bundle attribute is present

$3

Checklist:
- ✅ Bundle loader CDN URL is present in dist/index.html
- ✅ Bundle loader CDN script is first script in in dist/index.html
- ✅ Main script has data-else-default-bundle attribute
- ✅ Custom bundle URL is valid and accessible

Common Issues:
1. Bundle loader CDN URL missing from dist/index.html
- Run npx @elsedev/react-csr-sdk again to update the CDN URL
- Verify the script tag in your source index.html has been updated

2. Script order wrong in production
- Check dist/index.html manually - bundle loader should be first in
- Ensure your build process doesn't remove or reorder the bundle loader script

3. CORS errors loading custom bundle
- Ensure custom bundle URL has proper CORS headers
- Check browser network tab for failed requests

$3

Checklist:
1. Backend endpoint returning valid bundleUrl
2. setCustomBundle(bundleUrl) is being called
3. Page is reloading (default behavior)
4. Custom bundle URL is accessible (no 404 or CORS errors)

Debug:
`javascript
// Enable debug mode
window.else.setDebug(true);

// Check what's stored
console.log('Current bundle:', window.else.getCustomBundle());

// Test manual load
window.else.reloadWithBundle('https://your-bundle-url.js');
`

Console Logs to Look For:
- [Else] Setting custom bundle: - Confirms SDK function called
- [Else] Custom bundle URL: - Confirms bundle detected on reload
- [Else] Loading script: - Confirms bundle loading attempted
- [Else] Script loaded successfully: - Confirms bundle loaded

Disabling the SDK

The SDK is automatically disabled when developing an extension in an Else workspace.

To manually disable the SDK, set an environment variable:

Vite:
`bash
VITE_ELSE_DISABLED=true npm run dev
`

Create React App:
`bash
REACT_APP_ELSE_DISABLED=true npm start
`

When disabled, custom bundles will not load and all SDK functions become no-ops.

TypeScript Support

The SDK includes full TypeScript definitions. When you install the package, global type definitions for window.else are automatically available:

`typescript
// Global window.else types are automatically available
// No need to manually declare the interface!
window.else?.setCustomBundle('https://example.com/bundle.js')
window.else?.inElseDevEnvironment() // Returns boolean

// Import types for advanced usage
import type { ElseConfig, ElseSDK } from '@elsedev/react-csr-sdk';
`

The window.else API is automatically typed with full autocomplete support.

Examples

See the examples/` directory for complete implementation examples.

Support

For issues or questions, please see the Else documentation or contact support.