@axclip/axclip-editor-sdk

Axclip Editor SDK available as a framework-agnostic Web Component. Demo: https://axclip.com

📦 Installation

pnpm install @axclip/axclip-editor-sdk

🔧 Prerequisites (Important!)

This SDK uses advanced browser features like SharedArrayBuffer for high-performance video processing. You must serve your application with specific HTTP headers, otherwise the editor will strictly fail to load.

1. COOP/COEP Headers

Configure your server (Nginx, Vercel, Netlify, Vite, etc.) to send these headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

2. Static Assets

The SDK requires static assets (WASM files, icons).

• Option A (Recommended): Use our CDN (no action needed, default behavior).
• Option B (Self-hosted): Copy the assets folder from node_modules/@axclip/axclip-editor-sdk/dist/assets to your public directory and set assets-url="/your/public/path".

🚀 Usage Guide

1. Vue 3.0+

In Vue, you must tell the compiler to treat <axclip-editor> as a custom element, otherwise it will try to resolve it as a Vue component and warn you.

vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // Treat all tags starting with 'axclip-' as custom elements
          isCustomElement: (tag) => tag.startsWith("axclip-"),
        },
      },
    }),
  ],
});

App.vue:

<script setup lang="ts">
  import "@axclip/axclip-editor-sdk/axclip-editor.css"; // Import CSS
  import "@axclip/axclip-editor-sdk"; // Import Web Component registration

  const handleExport = (e: CustomEvent) => {
    console.log("Project JSON:", e.detail);
  };

  const handleVideoExport = (e: CustomEvent) => {
    console.log("Video Blob:", e.detail.file);
  };
</script>

<template>
  <div class="editor-container">
    <axclip-editor
      sdk-key="YOUR_SDK_KEY"
      assets-url="https://cdn.axclip.com/assets/"
      @ax-export="handleExport"
      @ax-video-export="handleVideoExport"
    ></axclip-editor>
  </div>
</template>

<style scoped>
  .editor-container {
    width: 100vw;
    height: 100vh;
  }
</style>

2. React 18 / Next.js

React 18 does not fully support Web Components events (like @ax-export). You need to use a ref to attach event listeners manually.

Top-level declaration (to fix TypeScript red errors):

// global.d.ts or at the top of your file
declare global {
  namespace JSX {
    interface IntrinsicElements {
      "axclip-editor": React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      > & {
        "sdk-key"?: string;
        "assets-url"?: string;
        "resource-id"?: string;
        class?: string;
      };
    }
  }
}

Editor Component:

"use client"; // If using Next.js App Router

import { useEffect, useRef } from "react";
import "@axclip/axclip-editor-sdk/axclip-editor.css";

// Dynamic import to avoid SSR issues if needed
// import('@axclip/axclip-editor-sdk');

export default function VideoEditor() {
  const editorRef = useRef<HTMLElement>(null);
  const initialized = useRef(false);

  useEffect(() => {
    // Dynamically import the SDK on client-side only
    import("@axclip/axclip-editor-sdk");

    const editor = editorRef.current;
    if (!editor) return;

    const onExport = (e: any) => console.log("Export:", e.detail);
    const onVideo = (e: any) => console.log("Video:", e.detail);

    // React 18: Manually attach custom event listeners
    editor.addEventListener("ax-export", onExport);
    editor.addEventListener("ax-video-export", onVideo);

    return () => {
      editor.removeEventListener("ax-export", onExport);
      editor.removeEventListener("ax-video-export", onVideo);
    };
  }, []);

  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <axclip-editor
        ref={editorRef}
        sdk-key="YOUR_SDK_KEY"
        assets-url="https://cdn.axclip.com/assets/"
      ></axclip-editor>
    </div>
  );
}

3. React 19

React 19 has full support for Custom Elements! You can use it just like a normal component without refs.

import { useEffect, useRef } from "react";
import "@axclip/axclip-editor-sdk/axclip-editor.css";
import "@axclip/axclip-editor-sdk";

export default function Editor() {
  const editorRef = useRef<HTMLElement>(null);

  useEffect(() => {
    // Standard event listener attachment
    const el = editorRef.current;
    if (!el) return;

    const handler = (e: any) => console.log(e.detail);
    el.addEventListener("ax-export", handler);
    return () => el.removeEventListener("ax-export", handler);
  }, []);

  return <axclip-editor ref={editorRef} sdk-key="YOUR_SDK_KEY"></axclip-editor>;
}

(Note: React 19 is still new. If events don't fire, fallback to the React 18 method.)

4. Vanilla JS / HTML (CDN)

Use the ESM build for modern browsers.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link
      rel="stylesheet"
      href="./node_modules/@axclip/axclip-editor-sdk/axclip-editor.css"
    />
    <style>
      body {
        margin: 0;
        height: 100vh;
        background: #000;
      }
    </style>
  </head>
  <body>
    <axclip-editor id="editor" sdk-key="YOUR_KEY"></axclip-editor>

    <!-- Load ESM module -->
    <script
      type="module"
      src="./node_modules/@axclip/axclip-editor-sdk/axclip-editor.es.js"
    ></script>

    <script>
      const editor = document.getElementById("editor");

      editor.addEventListener("ax-export", (e) => {
        console.log("Project Data:", e.detail);
      });

      // You can also manipulate it via JS
      // editor.setAttribute('resource-id', '123');
    </script>
  </body>
</html>

5. Vanilla JS (UMD / Legacy)

Use the UMD build if you are not using a bundler and cannot use ES modules.

<script src="./node_modules/@axclip/axclip-editor-sdk/axclip-editor.umd.js"></script>
<!-- The component is automatically registered -->
<axclip-editor sdk-key="..."></axclip-editor>

📚 API Reference

Attributes (Properties)

These attributes can be set on the <axclip-editor> element.

Important: In HTML, use kebab-case (e.g. sdk-key). In JavaScript/React refs, use camelCase (e.g. element.sdkKey).

| Attribute (HTML) | Property (JS) | Type | Required | Description | | :--------------- | :------------ | :------- | :------- | :------------------------------------------------- | | sdk-key | sdkKey | string | Yes | Your SDK Access Token. | | resource-id | resourceId | string | No | ID of the project/template to load. | | assets-url | assetsUrl | string | No | Base URL for fetching static assets (icons, wasm). | | api-base-url | apiBaseUrl | string | No | Custom API endpoint for private deployments. |

Events

Listen to these events to interact with the editor.

| Event Name | Detail Type | Description | | :---------------- | :--------------------- | :------------------------------------------------------------------------------------------------------------- | | ax-export | JSONObject | Fired when the user triggers a "Save/Export Project" action. Matches the internal project state format. | | ax-video-export | { file: Uint8Array } | Fired when the video rendering process finishes. event.detail.file contains the binary video data (MP4). |

Methods

Currently, the editor is primarily controlled via Attributes and User Interaction. Programmatic control methods (e.g., save(), load()) are planned for v2.1.

💡 Common Issues & Troubleshooting

Q: "Failed to resolve component: axclip-editor" in Vue A: You forgot to configure compilerOptions.isCustomElement in your vite/vue config. See the Vue section above.

Q: "Property 'axclip-editor' does not exist on type 'JSX.IntrinsicElements'" in React/TS A: You need to add the module declaration to extends JSX types. See the React 18 section above.

Q: Editor stuck at "Loading..." A: Open DevTools > Console. If you see SharedArrayBuffer is not defined, you are missing the COOP/COEP headers. See "Prerequisites".

Q: Icons or Fonts are missing (404) A: Check the Network tab. If requests to /assets/... are failing, set the assets-url attribute to point to the correct absolute path (e.g., https://my-cdn.com/axclip/).