External LibrariesTroubleshooting

Troubleshooting

Common issues and solutions for external libraries.

Library Loading Issues

”Failed to fetch library”

Cause: URL is not accessible or returns error.

Solutions:

  1. Open the URL in browser - does it load?
  2. Check for typos in URL
  3. Verify package is published (check npmjs.com)
  4. Wait 1-2 minutes after publishing for CDN propagation

”CORS policy blocked”

Cause: Library URL doesn’t allow cross-origin requests.

Solutions:

  1. Use CDNs that support CORS (unpkg, jsDelivr)
  2. If self-hosting, add CORS headers: 
    Access-Control-Allow-Origin: *

“Library name not found”

Cause: Global variable name doesn’t match bundle.

Solutions:

  1. Check your build config for the output name: 
    // rollup.config.js
output: { name: 'MyTestLib' }  // Use this name
  2. Inspect the bundle file for the global: 
    var MyTestLib = (function() { ... })();

“Cannot use import statement”

Cause: Library is ESM format, not IIFE/UMD.

Solutions:

  1. Configure build to output UMD: 
    output: { format: 'umd' }
  2. Use the ESM Bundler service to convert

Sync Issues

”No components found”

Causes:

  • Export names are wrong
  • Components not in expected format

Solutions:

  1. Verify export names (case-sensitive): 
    export const $$AssertionFunctions = [...]  // ✅
export const AssertionFunctions = [...]     // ❌
  2. Check each component has required fields: 
    {
  id: "my-assertion",      // Required
  name: "My Assertion",    // Required
  enabled: true,           // Required
  deprecated: false,       // Required
  tested: true,            // Required
  function: async () => {} // Required
}

“Component X not appearing in UI”

Causes:

  • Component is disabled
  • Component is deprecated
  • Sync not completed

Solutions:

  1. Check component flags: 
    enabled: true,      // Must be true
deprecated: false,  // Must be false for new components
  2. Re-run sync after changes
  3. Refresh the page

”Sync succeeded but components missing”

Cause: Components have errors that prevent discovery.

Solutions:

  1. Check browser console for errors during sync
  2. Verify function is actually a function: 
    function: async (value) => { ... }  // ✅
function: "not a function"          // ❌

Runtime Issues

”ReferenceError: MyTestLib is not defined”

Causes:

  • Library failed to load
  • Library name mismatch
  • Loading order issue

Solutions:

  1. Check library status in External Libraries page
  2. Verify Library Name matches bundle global
  3. Ensure library is enabled

”TypeError: $addAssertionResult is not a function”

Cause: Running code outside ReAPI context (e.g., unit tests).

Solution: Mock ReAPI globals in tests:

global.$addAssertionResult = vi.fn();
global.$context = {};
global.$server = { baseUrl: 'http://localhost' };

“Assertion not recording”

Causes:

  • $addAssertionResult() not called
  • Error thrown before assertion

Solutions:

  1. Ensure $addAssertionResult() is always called: 
    try {
  // Test logic
  $addAssertionResult({ passed: true, ... });
} catch (error) {
  $addAssertionResult({ passed: false, message: error.message, ... });
}
  2. Add error handling around risky operations

”Generator returns undefined”

Cause: Async function doesn’t return value.

Solution: Ensure you return the value:

function: async (options) => {
  const data = await fetchData();
  return data;  // Don't forget this!
}

Version Issues

”Using old version of library”

Causes:

  • CDN cache not updated
  • URL still points to old version

Solutions:

  1. Update URL to new version: 
    @1.0.0 → @1.0.1
  2. Click Sync from URL
  3. Add cache buster if needed: 
    ...@1.0.1/dist/build.umd.js?v=123

“Components changed unexpectedly”

Cause: Using @latest tag in production.

Solution: Pin to specific version:

# Instead of
https://unpkg.com/lib@latest/...

# Use
https://unpkg.com/lib@1.2.3/...

Build Issues

”Build fails with TypeScript errors”

Solutions:

  1. Check tsconfig.json settings
  2. Ensure all imports are correct
  3. Run npm run typecheck to see errors

”Bundle too large”

Solutions:

  1. Enable minification: 
    import { terser } from 'rollup-plugin-terser';
plugins: [terser()]
  2. Check for unnecessary dependencies
  3. Use tree-shaking: 
    treeshake: true

“Types not generated”

Solutions:

  1. Check tsconfig.json: 
    {
  "compilerOptions": {
    "declaration": true
  }
}
  2. Ensure rollup-plugin-dts is configured

Getting Help

If issues persist:

  1. Check browser console for detailed errors
  2. Verify bundle loads correctly in isolation: 
    <script src="your-bundle-url.js"></script>
<script>console.log(window.MyTestLib)</script>
  3. Test components locally before deploying
  4. Review the official template for reference implementation
Type Definitions