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 Design Format: { 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, color strokes, inner glow, 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. Linear and radial gradient overlays are both baked in; angle, reflected and diamond overlays are skipped.
• Groups become Polotno groups with their opacity and blend mode, so the layer hierarchy survives.
• 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.
• Adjustment layers (levels, curves, exposure, invert, posterize, threshold, hue/saturation, brightness/contrast, black & white, gradient map) are baked into the layers they reach.

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

Error Handling

If a file can't be parsed, the importer throws a plain Error with code: 'IMPORT_FAILED' and details.format: 'psd'; the low-level parser error is chained as error.cause. A file cut short before its final composite image also carries details.reason: 'truncated' (truncation inside the composite, which has no declared length, is not detected), so you can ask the user for a complete copy. A complete file whose compressed image data does not decompress, or a file with the PSD signature (8BPS) whose header names neither the PSD nor the PSB version, carries details.reason: 'corrupt', and a valid file the parser cannot read (Lab, Duotone or Multichannel color, or more than 16 channels) carries details.reason: 'unsupported'. A file whose decoded layer pixels would exceed the parser's 2 GiB memory budget carries details.reason: 'too-large'; flattening or cropping the document, or reducing its size or bit depth, in Photoshop avoids it. Other parser errors have no details.reason. See Error Handling.

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. Decoded layer pixels past the parser's 2 GiB budget fail with details.reason: 'too-large' in either runtime.

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