JavaScript SDK

Use Merchify in any JavaScript environment - no React required.

Overview

The Merchify SDK is a lightweight JavaScript library for generating product mockups and fetching catalog data. It works in any JavaScript environment: vanilla JS, Node.js, Vue, Svelte, or any other framework.

The SDK handles authentication, URL signing, and provides TypeScript types for a great developer experience.

When to Use

Choose the right tool for your use case:

SDK (this guide)
  • • Building with vanilla JavaScript
  • • Using a non-React framework (Vue, Svelte, etc.)
  • • Server-side rendering or API routes
  • • Custom UI with full control over rendering
React Components
  • • Building a React application
  • • Want pre-built, styled components
  • • Need state management out of the box
REST API
  • • Building in a non-JavaScript language
  • • Need direct HTTP access
  • • Server-to-server integrations

Installation

Install the SDK package:

npm install merchify

Install the Merchify SDK

The package includes TypeScript definitions - no additional types package needed.

Quick Start

Generate a product mockup URL in just a few lines:

import { mockupUrl, config } from 'merchify';

// Configure your account (once at app startup)
config({
  accountId: 'YOUR_ACCOUNT_ID',
});

// Generate a signed mockup URL
const url = mockupUrl({
  productId: 'BEEB77',
  mockupId: 'FV1qjO',
  design: [
    {
      type: 'image',
      imageUrl: 'https://example.com/my-artwork.png',
      placement: 'Front',
      alignment: 'center',
    }
  ],
  width: 1000,
});

// Use the URL in an <img> tag, background-image, etc.
console.log(url);

The returned URL is a fully signed image URL that can be used anywhere - in an HTML img tag, as a CSS background, or passed to any image processing pipeline.

Vanilla JS Example

Here's a complete example showing how to use the SDK in a plain HTML page with vanilla JavaScript - no build tools or frameworks required:

<!DOCTYPE html>
<html>
<head>
  <title>Merchify Mockup Demo</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; }
    .mockup-container { max-width: 600px; margin: 0 auto; }
    .mockup-image { width: 100%; border-radius: 8px; }
    .artwork-input { width: 100%; padding: 0.5rem; margin: 1rem 0; }
    button { padding: 0.5rem 1rem; cursor: pointer; }
  </style>
</head>
<body>
  <div class="mockup-container">
    <h1>Product Mockup Preview</h1>

    <label>Artwork URL:</label>
    <input
      type="text"
      id="artworkUrl"
      class="artwork-input"
      placeholder="https://example.com/your-artwork.png"
    />
    <button onclick="updateMockup()">Update Mockup</button>

    <img id="mockupImage" class="mockup-image" alt="Product mockup" />
  </div>

  <!-- Load the SDK from CDN (or use your bundler) -->
  <script type="module">
    import { mockupUrl, config } from 'https://esm.sh/merchify';

    // Configure once at startup
    config({
      accountId: 'YOUR_ACCOUNT_ID',
    });

    // Make functions available globally for onclick handlers
    window.updateMockup = function() {
      const artworkUrl = document.getElementById('artworkUrl').value;
      if (!artworkUrl) return alert('Please enter an artwork URL');

      // Generate the mockup URL
      const url = mockupUrl({
        productId: 'BEEB77',      // Canvas print
        mockupId: 'FV1qjO',
        design: [{
          type: 'image',
          imageUrl: artworkUrl,
          placement: 'Front',
          alignment: 'center',
        }],
        width: 1200,
      });

      // Display the mockup
      document.getElementById('mockupImage').src = url;
    };
  </script>
</body>
</html>

You can also use the SDK with a bundler like Vite, Webpack, or esbuild. Here's a modular approach:

// mockup-service.js
import { mockupUrl, config, getProduct } from 'merchify';

// Initialize once
config({ accountId: 'YOUR_ACCOUNT_ID' });

export async function createMockupPreview(artworkUrl, productId = 'BEEB77') {
  // Fetch product data to get available mockups
  const product = await getProduct(productId);

  // Use the first mockup template
  const mockupId = product.mockups[0]?.id;

  // Generate the mockup URL
  return mockupUrl({
    productId,
    mockupId,
    design: [{
      type: 'image',
      imageUrl: artworkUrl,
      placement: 'Front',
      alignment: 'center',
    }],
    width: 1000,
  });
}

// Usage in your app:
// const url = await createMockupPreview('https://example.com/art.png');
// document.querySelector('img').src = url;

Next Steps

Mockup Generation
Learn about design elements, alignment options, and advanced mockup features
REST API Reference
Direct HTTP endpoints for non-JavaScript integrations