@varianta/sdk
v0.1.6
Published
Multi-framework JavaScript SDK for product customization
Maintainers
tedydevReadme
@varianta/sdk
Multi-framework JavaScript SDK for product customization. Provides a simple, powerful API for integrating the Customizer Editor into your web application.
Features
- Framework Agnostic: Works with vanilla JavaScript, React, Vue, and other frameworks
- TypeScript First: Full TypeScript support with comprehensive type definitions
- Lightweight: ~33KB ESM, ~22KB UMD (minified + gzipped: ~9KB/~8KB)
- Multiple Formats: UMD, ESM, and CJS builds for maximum compatibility
- Zero Config: Works out of the box with sensible defaults
- Event-Driven: Rich event system for monitoring editor state
- Print-Ready: Generate high-quality proofs and print files
Installation
# npm
npm install @varianta/sdk
# yarn
yarn add @varianta/sdk
# pnpm
pnpm add @varianta/sdkFramework-Specific Dependencies
React:
npm install @varianta/sdk react react-domVue 3:
npm install @varianta/sdk vueQuick Start
Vanilla JavaScript
import { initCustomizer } from '@varianta/sdk';
const editor = initCustomizer('#editor-container', {
templateId: 'tshirt-001',
theme: 'light',
showCloseButton: false, // hide the built-in Close button
onReady: () => {
console.log('Editor ready!');
},
onChange: (design) => {
console.log('Design changed:', design);
},
});
// Get current design
const design = editor.getDesign();
// Finalize and generate print files
const result = await editor.finalize();
console.log('Print-ready files:', result);React
import { Customizer, useCustomizer } from '@varianta/sdk/react';
import { useRef } from 'react';
function App() {
const { customizerRef, undo, redo, canUndo, canRedo, finalize } = useCustomizer();
return (
<div style={{ width: '100vw', height: '100vh' }}>
<Customizer
ref={customizerRef}
templateId="tshirt-001"
theme="light"
onChange={(design) => console.log('Design changed:', design)}
/>
<div>
<button onClick={undo} disabled={!canUndo}>Undo</button>
<button onClick={redo} disabled={!canRedo}>Redo</button>
<button onClick={finalize}>Finalize Design</button>
</div>
</div>
);
}Vue 3
<template>
<div>
<div ref="editorRef" style="width: 100%; height: 600px;" />
<button @click="handleFinalize">Finalize Design</button>
</div>
</template>
<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { initCustomizer } from '@varianta/sdk';
import type { CustomizerInstance, DesignJSON } from '@varianta/sdk';
const editorRef = ref<HTMLElement>();
let editor: CustomizerInstance | null = null;
onMounted(() => {
if (editorRef.value) {
editor = initCustomizer(editorRef.value, {
templateId: 'tshirt-001',
theme: 'light',
onReady: () => console.log('Editor ready!'),
onChange: (design: DesignJSON) => console.log('Design changed:', design),
});
}
});
onUnmounted(() => {
editor?.destroy();
});
const handleFinalize = async () => {
const result = await editor?.finalize();
console.log('Finalized:', result);
};
</script>CDN Usage (UMD)
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.example.com/@varianta/[email protected]/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://cdn.example.com/@customizer/[email protected]/dist/customizer.css">
</head>
<body>
<div id="editor" style="width: 100vw; height: 100vh;"></div>
<script>
const editor = CustomizerSDK.initCustomizer('#editor', {
templateId: 'tshirt-001',
onReady: () => console.log('Ready!'),
});
</script>
</body>
</html>Documentation
- Vanilla JS Examples - Comprehensive vanilla JavaScript usage
- React Examples - React integration patterns and hooks
- Vue Examples - Vue 3 component usage
- API Reference - Complete API documentation
- Integration Guides - Shopify, WordPress, and standalone integration
API Overview
Core Methods
interface CustomizerInstance {
getDesign(): DesignJSON;
setDesign(design: DesignJSON): void;
undo(): void;
redo(): void;
canUndo(): boolean;
canRedo(): boolean;
finalize(): Promise<FinalizeResult>;
addTextLayer(text?: string): void;
addImageLayer(url: string): Promise<void>;
removeLayer(layerId: string): void;
selectLayer(layerId: string | null): void;
getSelectedLayerId(): string | null;
setTheme(theme: 'light' | 'dark'): void;
setMode(mode: 'edit' | 'preview'): void;
destroy(): void;
}Event System
initCustomizer('#editor', {
templateId: 'tshirt-001',
onReady: () => {},
onChange: (design) => {},
onLayerSelect: (layerId) => {},
onLayerAdd: (layerId) => {},
onLayerRemove: (layerId) => {},
onLayerUpdate: (layerId) => {},
onError: (error) => {},
onFinalize: (result) => {},
onClose: () => {},
onSave: (result) => {},
onViewChange: (viewName) => {},
});Configuration Options
interface CustomizerOptions {
templateId?: string; // Template to load (required unless productId is set)
productId?: string; // Product ID (loads all views/templates for the product)
apiUrl?: string; // Default: 'https://api.varianta.io'
theme?: 'light' | 'dark'; // Default: 'light'
mode?: 'edit' | 'preview'; // Default: 'edit'
debug?: boolean; // Default: false
className?: string; // Custom CSS class
initialDesign?: DesignJSON; // Pre-load a design
showCloseButton?: boolean; // Default: true
showSaveButton?: boolean; // Default: true
// ... event handlers
}TypeScript Support
The SDK is written in TypeScript and includes comprehensive type definitions:
import type {
CustomizerInstance,
CustomizerOptions,
DesignJSON,
FinalizeResult,
CustomizerError,
Scene,
Layer,
TextLayer,
ImageLayer,
} from '@varianta/sdk';Browser Support
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Opera 76+
License
ISC
Related Packages
- @customizer/editor - Core Web Component editor
- @customizer/scene-engine - 2D scene model
- @customizer/template - Template JSON specification