@fraczled/sdk

Embed a powerful design editor in your application with the Fraczled SDK.

Installation

npm install @fraczled/sdk

Server-gated delivery (required)

To prevent unauthorized usage, always gate the SDK bundle through your backend. Use /v1/editor/init to validate the license, then serve the SDK from /v1/editor/sdk. See docs/license-enforcement.md for the full flow.

Quick Start

import { createFraczledEditor } from "@fraczled/sdk";

const editor = createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor")
});

// Listen for changes
editor.on("change", (state) => {
  console.log("Design changed:", state);
});

// Save the design (JSON string)
const designJSON = editor.save();
const designState = JSON.parse(designJSON);

// Cleanup when done
editor.destroy();

Compatibility

• Desktop browsers only (mobile and tablet are not supported yet).

Configuration

interface EditorConfig {
  // Required
  apiKey: string; // Your dev_* or prod_* license key
  projectId: string; // Your project ID (from signup or dashboard)
  container: HTMLElement;

  // Optional
  showCredit?: boolean;
  initialState?: {
    pages: Page[];
    settings: DocumentSettings;
  };
  services?: {
    aiEndpoint?: string;
    unsplashProxyBaseUrl?: string;
  };
  assets?: {
    injectTailwind?: boolean;
    tailwindCdnUrl?: string;
    injectFont?: boolean;
    fontHref?: string;
    injectBaseStyles?: boolean;
    showLoader?: boolean;
  };
  ui?: {
    hideDefaultPanels?: boolean;
    hiddenPanels?: PanelId[];
    topbarMode?: 'default' | 'custom';
    newDesignModal?: NewDesignModalConfig;
  };
  customPanels?: CustomSidebarPanel[];
}

Production note

By default, the SDK injects the Tailwind CDN and Google Fonts for convenience. For production use, set assets.injectTailwind = false and provide your own CSS bundle (and optionally your own fonts) to avoid relying on external CDNs.

License validation is handled by https://fraczled.com and requires outbound HTTPS access. If you need to run offline, supply a signed offline license token via services.licenseRequest.offlineLicense so the SDK can verify it locally.

Server-side enforcement (recommended)

To fully prevent unauthorized usage, gate the editor bundle on your server. See docs/license-enforcement.md for the full flow and sample code.

License Keys

Development Keys (dev_*)

• 100-day free trial
• Works on localhost, staging, and development domains only
• Full feature access for testing

Production Keys (prod_*)

• Required for production domains
• Available with Team ($150/mo) or Business ($250/mo) plans

Note: SDK license keys are used in client-side code. Treat them as publishable and lock them to allowed domains + projectId in your dashboard.

Plans

| Feature | Team ($150/mo) | Business ($250/mo) | | ------------------ | -------------- | ------------------ | | Production Domains | 1 | Unlimited | | Editor Loads | 10,000/month | Unlimited | | AI Features | Yes | Yes | | Export (Web/Print) | Yes | Yes | | Support | Standard | Priority |

Getting Started

1. Sign up for a trial at fraczled.com/signup
2. You'll receive a dev_* key and project ID
3. Install the SDK and start building
4. When ready for production, purchase a Team or Business plan

API Reference

createFraczledEditor(config)

Creates a new editor instance.

Returns:

{
  store: Store;           // Access to the underlying store
  on: (event, callback) => void;  // Subscribe to events
  save: () => string;             // Export current design JSON
  destroy: () => void;            // Cleanup
}

Events

• change - Fired when the design state changes
• save - Fired when the user saves
• select - Fired when selection changes
• export - Fired when user exports
• designSaved - Fired when a saved design is created or updated (payload: SavedDesign)
• designDeleted - Fired when a saved design is deleted (payload: { id, design })

Custom Sidebar Panels

You can add your own sidebar tools and panels inside the editor UI. Custom panels render inside the same side panel shell used by built-in tools, and receive access to the store and current state.

import { createFraczledEditor } from "@fraczled/sdk";
import { BadgeCheck } from "lucide-react";

const editor = createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  customPanels: [
    {
      id: "my-product:approvals",
      label: "Approvals",
      icon: BadgeCheck,
      feature: "approvals", // optional entitlement key
      render: ({ store, state, closePanel, setActivePanel }) => (
        <div className="space-y-4">
          <div className="rounded-lg border border-slate-200 bg-slate-50 p-3 text-xs text-slate-600">
            Selected elements: {state.selection.length}
          </div>
          <button
            className="w-full rounded-lg bg-slate-900 px-3 py-2 text-sm font-semibold text-white"
            onClick={() =>
              store.addElement({
                type: "text",
                name: "Approved Copy",
                content: "Approved Copy"
              })
            }
          >
            Insert Approved Copy
          </button>
          <button
            className="w-full rounded-lg border border-slate-200 px-3 py-2 text-sm font-medium"
            onClick={closePanel}
          >
            Close
          </button>
        </div>
      )
    }
  ]
});

Notes:

• id must be unique and should not match built-in tool labels (for example, Design or Elements).
• feature maps to entitlements.features[feature] and controls visibility/access based on licensing.
• render is called when the panel is active, so you can wire buttons directly to store methods or read from state.

Template save action (SDK only)

You can customize the "Save Current Design as Template" button in the Templates → Designs panel:

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  customTemplates: {
    saveAction: {
      label: "Save as Brand Template",
      onClick: ({ openSaveModal }) => openSaveModal()
    }
  }
});

Note: This action is gated by the templateSave plan feature.

Custom topbar actions (SDK only)

You can replace the default topbar actions (save/new/export/undo/redo/zoom) with your own UI:

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  ui: { topbarMode: "custom" },
  customToolbarItems: [
    {
      id: "my-topbar:action",
      label: "My Action",
      location: "topbar",
      onClick: ({ topbar }) => topbar?.onExport?.("web")
    }
  ]
});

Note: ui.topbarMode = "custom" is gated by the topbarActions plan feature.

Customize export menu (SDK only)

You can customize the export button label/icon and override or hide dropdown items while keeping the native UI.

import { createFraczledEditor } from "@fraczled/sdk";
import { Download, FileText } from "lucide-react";

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  ui: {
    exportMenu: {
      buttonLabel: "Download",
      buttonIcon: Download,
      items: [
        { id: "web", label: "Quick PNG", description: "Optimized for web" },
        { id: "print_pdf", label: "PDF (Press Ready)", icon: FileText },
        { id: "print_png", hidden: true },
        { id: "json", label: "Save Project File" }
      ]
    }
  }
});

Custom new design modal (SDK only)

You can replace the Create New Design modal with your own UI:

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  ui: {
    newDesignModal: {
      render: ({ applySizePreset, onClose }) => (
        <div className="fixed inset-0 bg-black/40 flex items-center justify-center">
          <div className="bg-white rounded-xl p-6 space-y-3">
            <button
              onClick={() => {
                applySizePreset({ name: "Product Card", width: 1200, height: 1200, unit: "px", dpi: 72 });
                onClose();
              }}
            >
              New Product Card
            </button>
          </div>
        </div>
      )
    }
  }
});

Note: ui.newDesignModal.render is gated by the newDesignModal plan feature.

Custom template sizes (SDK only)

You can override the Social Media / Print size presets shown in the Create New Design modal:

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  ui: {
    newDesignModal: {
      sizePresets: {
        social: [
          { name: "Square Ad", width: 1200, height: 1200, unit: "px", dpi: 72 }
        ],
        print: [
          { name: "Box Sleeve", width: 8, height: 5, unit: "in", dpi: 300, bleed: 0.125 }
        ]
      }
    }
  }
});

Notes:

• unit can be px, in, mm, or pt. bleed and safeArea (optional) use the same unit.
• Size presets are gated by the templateSizes plan feature.

Hide built-in tabs (SDK only)

You can hide vanilla sidebar tabs in SDK embeds:

import { createFraczledEditor, ToolType } from "@fraczled/sdk";

createFraczledEditor({
  apiKey: "YOUR_LICENSE_KEY",
  projectId: "YOUR_PROJECT_ID",
  container: document.getElementById("editor"),
  ui: {
    hideDefaultPanels: true,
    // or hide specific tabs:
    // hiddenPanels: [ToolType.IMAGES, ToolType.BRAND, "my-product:approvals"]
  },
  customPanels: [
    {
      id: "my-product:approvals",
      label: "Approvals",
      render: ({ store }) => (
        <button onClick={() => store.exportJSON()}>Export JSON</button>
      )
    }
  ]
});

Notes:

• hiddenPanels applies to both default and custom panels by id.
• Removing the ui config restores the vanilla sidebar.
• Hiding tabs is UI-only; it does not disable underlying features.

Built-in panel IDs you can hide:

• ToolType.TEMPLATES (label: Create)
• ToolType.DESIGN
• ToolType.ELEMENTS
• ToolType.DRAW
• ToolType.TEXT
• ToolType.IMAGES
• ToolType.ICONS
• ToolType.BRAND
• ToolType.UPLOADS
• ToolType.QR_CODE
• ToolType.LAYERS

Support

• Documentation: fraczled.com/docs
• Email: [email protected]