CSP and WASM Self‐Hosting Guide

This guide provides solutions for Content Security Policy (CSP) violations when using DotLottie components in applications with strict CSP policies.

Problem

By default, DotLottie loads WebAssembly (WASM) modules from external CDNs:

• https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-web@{version}/dist/dotlottie-player.wasm
• https://unpkg.com/@lottiefiles/dotlottie-web@{version}/dist/dotlottie-player.wasm (backup)

Applications with strict CSP policies (like OneApp) typically block:

1. External CDN connections via connect-src restrictions
2. WebAssembly compilation without 'unsafe-eval' in script-src

Solution: Vite URL Import

Use Vite's built-in URL import functionality to automatically bundle the WASM file from node_modules:

import { DotLottieReact, setWasmUrl } from '@lottiefiles/dotlottie-react';
// Import WASM file as URL - Vite handles bundling automatically
import wasmUrl from '@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm?url';

// Configure WASM URL before component usage
setWasmUrl(wasmUrl);

function MyComponent() {
  return (
    <DotLottieReact
      src="your-animation.lottie"
      loop
      autoplay
    />
  );
}

Initialize in App Entry Point

Configure the WASM URL early in your application lifecycle:

// App.tsx or index.tsx
import { setWasmUrl } from '@lottiefiles/dotlottie-react';
import wasmUrl from '@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm?url';

// Set WASM URL immediately
setWasmUrl(wasmUrl);

function App() {
  return (
    <div>
      {/* Your app components */}
    </div>
  );
}

Alternative Approaches (if Vite is not available)

Manual Copy Approach

If Vite is not available, copy the WASM file manually:

# Copy WASM to public directory
cp node_modules/@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm public/static/

import { setWasmUrl } from '@lottiefiles/dotlottie-react';

// Set static URL
setWasmUrl('/static/dotlottie-player.wasm');

TypeScript Support

If TypeScript complains about importing .wasm files, add to your type declarations:

// types/assets.d.ts
declare module '*.wasm' {
  const content: string;
  export default content;
}

Implementation Best Practices

1. Set WASM URL Early: Call setWasmUrl() in your app's entry point before any component renders.

2. Error Handling:

   import { setWasmUrl } from '@lottiefiles/dotlottie-react';
   import wasmUrl from '@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm?url';
   
   try {
     setWasmUrl(wasmUrl);
   } catch (error) {
     console.error('Failed to set WASM URL:', error);
     // Fallback to default CDN behavior or show error
   }

Troubleshooting

Common Issues

1. 404 Not Found: Ensure WASM file is correctly copied to your public directory and accessible via HTTP.

2. MIME Type Errors: Verify your server serves .wasm files with application/wasm MIME type.

3. CSP Still Blocking: Even with self-hosted WASM, some CSP policies may block WebAssembly compilation. Check if 'wasm-unsafe-eval' is needed.

4. Build Tool Integration: Ensure your build process copies the WASM file to the correct output directory.

Framework-Specific Considerations

React

For React applications (including OneApp environments):

1. Use Vite's ?url import - it automatically handles WASM bundling and avoids CSP violations
2. Consider lazy loading for large applications:

const initializeDotLottie = async () => {
  const { setWasmUrl } = await import('@lottiefiles/dotlottie-react');
  const wasmModule = await import('@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm?url');
  setWasmUrl(wasmModule.default);
};

// Use in component
useEffect(() => {
  initializeDotLottie();
}, []);

4. Bundle splitting: Configure Vite to split the WASM into a separate chunk:

// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'dotlottie-wasm': ['@lottiefiles/dotlottie-web/dist/dotlottie-player.wasm']
        }
      }
    }
  }
});

Other Frameworks

This same approach works with other framework packages:

• @lottiefiles/dotlottie-vue
• @lottiefiles/dotlottie-svelte
• @lottiefiles/dotlottie-solid
• @lottiefiles/dotlottie-wc

Just import from the appropriate package and call setWasmUrl(wasmUrl) before using any components.

Version Compatibility

This guide applies to:

• @lottiefiles/dotlottie-web v0.33.0+
• @lottiefiles/dotlottie-react v0.8.0+
• @lottiefiles/dotlottie-vue v0.5.0+
• All other framework packages that expose setWasmUrl

For older versions, consider upgrading to access the setWasmUrl functionality.