@polotno/psd-import — PSD to editable Polotno JSON

Parse a Photoshop .psd file and convert it into a JSON document that matches the Polotno schema. Works in the browser and in Node.

Works without the editor. The converter returns plain Polotno design JSON.

Runtime: Browser and Node.js. Conversion runs locally.

Documentation · Try PSD to JSON in your browser

License: Non-production use is free, with no time limit. Production use requires a valid Polotno subscription. Read the license.

Install

npm install @polotno/psd-import

Usage

psdToJson accepts an ArrayBuffer or Uint8Array of PSD bytes and returns a Polotno-schema JSON document.

Browser — read bytes from a file input:

import { psdToJson } from '@polotno/psd-import';

const file = input.files[0];
const buffer = await file.arrayBuffer();
const json = await psdToJson({ psd: buffer });

// Optional: load into a Polotno store
store.loadJSON(json);

Node.js — read bytes from disk:

import { readFile } from 'node:fs/promises';
import { psdToJson } from '@polotno/psd-import';

const buffer = await readFile('./design.psd');
const json = await psdToJson({ psd: buffer });

The returned object matches the Polotno JSON schema: { width, height, fonts, pages, unit, dpi }.

How it works

The goal is to keep as many of the PSD's layers as separate, editable elements as possible, instead of flattening the file into a single image. Each PSD layer is mapped to the closest equivalent in the Polotno schema:

• Text layers stay as editable text — font family, weight, style, size, color, alignment, line height, and letter spacing carry over.
• Shape and vector layers become SVG elements with their fills, gradients, and strokes preserved.
• Raster layers become images. When a layer uses effects the schema can't represent natively (gradient/color overlays, gradient maps, hue/saturation, brightness/contrast, …), the effect is baked into that layer's pixels so it still looks right while every other element remains separate.
• Masks and group effects are applied to the layers underneath them, so masked content and folder-level overlays render correctly without collapsing the document.
• Blend modes pass through where the schema supports them; unsupported modes are flattened only with the layers they depend on.

The PSD's pre-rendered composite image is intentionally not used — every element stays selectable and editable.

License

See LICENSE.md.