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

npm install @elsedev/react-csr-sdk

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

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

Basic Usage

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()
})

How It Works

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

Backend Integration

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

// 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:

// 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)
})

Advanced Usage

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

1. Install the SDK

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

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.

2. Verify HTML Structure

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

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Else bundle loader - Automatically added by postinstall script -->
  <script src="https://sdk-cdn.somethingelse.ai/react-csr/else-bundle-loader-v1.0.17.js"></script>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Your App</title>
  
  <!-- Optional: Enable debug logging for bundle loader -->
  <script>
    setTimeout(() => {
      if (window.else) {
        window.else.setDebug(true);
      }
    }, 0);
  </script>
</head>
<body>
  <div id="root"></div>
  
  <!-- IMPORTANT: Add data-else-default-bundle attribute -->
  <script data-else-default-bundle type="module" src="/src/main.tsx"></script>
</body>
</html>

Critical Details:

• The bundle loader script is automatically added to <head> 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. Create Vendor Backend Endpoint

Your backend should authenticate users and call the Else API:

// 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 });
  }
});

4. Use SDK in Frontend

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

Bundle Management

setCustomBundle(bundleUrl, reload?)

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

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.

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

clearCustomBundle(reload?)

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

clearCustomBundle(true);

reloadWithBundle(bundleUrl)

Sets a bundle URL and immediately reloads the page.

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

Utility Functions

setDebugMode(enabled)

Enable/disable debug logging.

setDebugMode(true); // See bundle loading logs

Integration Patterns

User Login Flow

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
    }
  }
}

User Logout Flow

async function handleUserLogout() {
  // 1. Clear session with your backend
  await logoutUser();
  
  // 2. Clear custom bundle and reload with default
  clearCustomBundle();
}

Tenant Switching

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
  }
}

Error Handling

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:

// 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:

{
  "bundleUrl": "https://cdn.example.com/tenant-123/bundle.js"
}

Or if no custom bundle:

{
  "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:

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

Both Default and Custom Bundles Loading Simultaneously

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

   <script data-else-default-bundle type="module" src="/src/main.tsx"></script>

   • 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 <head>
   • If not, ensure your build process preserves the script order

Debug Steps:

1. Enable debug mode in your index.html:

   <script>
     setTimeout(() => {
       if (window.else) {
         window.else.setDebug(true);
       }
     }, 0);
   </script>

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

Bundle Not Loading in Production

Checklist:

• ✅ Bundle loader CDN URL is present in dist/index.html
• ✅ Bundle loader CDN script is first script in <head> 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 <head>
   • 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

Custom Bundle Not Applying After Login

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:

// 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: <url> - Confirms SDK function called
• [Else] Custom bundle URL: <url> - Confirms bundle detected on reload
• [Else] Loading script: <url> - Confirms bundle loading attempted
• [Else] Script loaded successfully: <url> - 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:

VITE_ELSE_DISABLED=true npm run dev

Create React App:

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:

// 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.