@printine/designer

React online product designer for Printine-powered products. It provides the editor UI, Fabric canvas, 2D/3D preview and public design-data integration; the host application owns its own routing, authentication, uploads, user assets, saved templates and final design persistence.

Install

npm install @printine/designer

react and react-dom 18 or 19 are peer dependencies.

Quick start

Render the component from a browser-only React component. For Next.js App Router, place this in a Client Component ('use client'), or load it with next/dynamic({ ssr: false }).

'use client';

import { PrintineDesigner, type DesignerSaveInput } from '@printine/designer';
import '@printine/designer/styles.css';

export function ProductDesigner() {
  return (
    <PrintineDesigner
      productId="variant-id"
      basePlateId="model-id"
      locale="en-US"
      adapters={{
        uploadImage: async ({ file, purpose, metadata }) => {
          // Return complete URLs, never
        },
        assets: {
          list: async ({ page, pageSize }) => hostListAssets({ page, pageSize }),
          remove: async ({ id }) => hostDeleteAsset({ id }),
        },
        templates: {
          create: async ({ name, preview, content }) => hostCreateTemplate({ name, preview, content }),
          list: async () => hostListTemplates(),
          get: async ({ id }) => hostGetTemplate({ id }),
          remove: async ({ id }) => hostDeleteTemplate({ id }),
        },
      }}
      onSave={async (saveInput: DesignerSaveInput) => {}}
      onClose={() => router.back()}
      onError={(error) => reportDesignerError(error)}
    />
  );
}

Integration model

By default, the package uses the Printine production product API and the public Asset Center at https://assets.printine.dev. To use local, testing or staging services, pass domain-only overrides. The package adds the API paths itself and normalizes a trailing slash:

<PrintineDesigner
  productId="variant-id"
  basePlateId="model-id"
  apiBaseUrl="https://shop-api-staging.printine.com"
  assetBaseUrl="https://assets-staging.printine.dev"
/>

assetBaseUrl is the Asset Center service origin, not a CDN/static-image prefix. It is used only for the unauthenticated public fonts, preset colours, clipart and shapes APIs (/api/v1/*). It never sends a token or uses the shop API's 445 guest-token retry.

The following user-specific capabilities are always supplied by the host:

| Capability | Required adapter | Behaviour when omitted | | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | | Image upload | adapters.uploadImage | Upload controls are hidden. | | My images | adapters.assets.list | The image library is hidden. | | Delete an image | adapters.assets.remove | The image delete button is hidden. | | My designs | adapters.templates | “My designs” is hidden; public template categories remain available. Saving also requires adapters.uploadImage. | | Save the final design | onSave | Done is hidden in the preview. |

Uploads and assets

uploadImage receives a purpose of 'asset', 'design-data' or 'template-preview' and returns { url, thumbnailUrl?, thumbnailScale? }. All returned values must be complete URLs.

For purpose: 'asset', the host is responsible for its complete workflow: uploading the original image, optionally creating a thumbnail, and creating the host's asset record before resolving the promise. The package never calls a user-assets endpoint.

Saved templates

adapters.templates contains create, list and get; remove is optional. The package uploads a template preview through uploadImage with purpose: 'template-preview', then passes the preview URL and template content to templates.create.

Saving

onSave receives the prepared existing save payload:

type DesignerSaveInput = {
  variant_id: string;
  design_data: Record<string, unknown>;
  background_customized?: unknown;
  is_partially_customized?: 1;
};

The callback owns its request, business-error handling, analytics and any route change. When it rejects, the package only clears its own loading state and does not show another error message.

Styling

Import @printine/designer/styles.css once. The package ships its icons, empty states and editor styles, so no host static files or Tailwind content scanning are required.

Theme variables use the --printine- prefix and can be overridden globally:

:root {
  --printine-primary: #3540a5;
  --printine-background: #f3f5f6;
  --printine-foreground: #1c1c1e;
  --printine-border: #e0e0e5;
}

Public exports

The main entry exports PrintineDesigner and the TypeScript contracts needed for integration, including PrintineDesignerProps, DesignerAdapters, DesignerAsset, DesignerUserTemplate and DesignerSaveInput.

@printine/designer/full-designer is available for advanced integrations that already provide a PrintineDesigner runtime.

Documentation

• Integration API: component properties, callbacks and host-owned adapters.
• Host data contract: the minimum product, base-plate and Asset Center data read by the package.