PSD Import

The @polotno/psd-import package converts Photoshop .psd files into Polotno JSON format, enabling you to import PSD designs into Polotno for further editing — text stays editable text, vector shapes stay vector, raster layers stay images.

Installation

npm install @polotno/psd-import

Basic Usage

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

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

const json = await psdToJson({ psd: buffer });

// Load into Polotno store
store.loadJSON(json);

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

Browser Example

Read bytes from a file input:

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

async function handleFileUpload(file: File) {
  const buffer = await file.arrayBuffer();
  const json = await psdToJson({ psd: buffer });
  store.loadJSON(json);
}

Node.js Example

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 });
store.loadJSON(json);

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.

Platform Support

This package works both client-side (browser) and server-side (Node.js). All processing runs locally — no data is sent to any external server.

Demo

Related Imports

• SVG Import — @polotno/svg-import for SVG files
• PDF Import — @polotno/pdf-import for PDF and Adobe Illustrator files
• Import & Export overview

Troubleshooting

Import produces unexpected results:

• Try simplifying the PSD before importing (flatten unused groups, rasterize complex smart objects)
• Some advanced Photoshop features (3D layers, video layers, complex layer comps) aren't supported
• Check browser console for warnings

Missing fonts:

• Fonts are referenced by family name in the imported design; if the font isn't installed where the design renders, the editor or browser will fall back. Install or load the font before rendering for pixel-perfect output.

Large files:

• PSDs up to a few hundred MB usually parse fine in the browser. For very large files or bulk processing, run psdToJson() in Node.js where memory limits are higher.

Need help? Report issues and get support at community.polotno.com.