PSD Import

Convert Photoshop .psd files into editable Ydesign designs.

🚧 Planned: @ydesign/psd-import is not published yet. This page describes the target API and capability boundaries so you can evaluate integration early. The package will land in this shape; details may still change.

@ydesign/psd-import parses a PSD into Ydesign design JSON (the same structure consumed by store.loadJSON() / the Fabric canvas): text stays editable text, vectors stay vectors where possible, and raster layers become images.

Beta expectations: The first release will cover common layer types. Complex smart objects, advanced effects, and some blend modes may be rasterized or degraded. Real-world PSD samples help us prioritize fixes.

---

Installation (planned)

pnpm add @ydesign/psd-import
# or
npm install @ydesign/psd-import

---

Basic usage

psdToJson accepts an ArrayBuffer or Uint8Array of PSD bytes and returns design JSON you can pass straight to the Store.

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

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

// Load into the editor
store.loadJSON(json);

The return value matches the design JSON shape ({ width, height, fonts, pages, unit, dpi, ... }) and can be consumed by store.loadJSON from @ydesign/react-editor.

---

Browser example

Read bytes from a file input:

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

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

Fits the “user uploads a PSD → opens the editor” flow. Parsing runs fully locally — nothing is uploaded to Ydesign servers.

---

Node.js example

Read bytes from disk:

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

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

// Write into a template library, batch-convert to JSON, or hand off to cloud / Node render

Useful for backend conversion, template ingestion, and CI. Prefer Node for very large files (higher memory limits).

---

How it works

The goal is not to flatten the PSD into a single image, but to map layers into separate, still-editable Ydesign elements:

PSD layer	Mapping
Text	Editable text — family, weight, style, size, color, alignment, line height, letter spacing preserved where possible
Shape / vector	SVG / vector elements — fills, gradients, strokes preserved where possible
Raster	Image elements. Effects the schema cannot express natively (gradient overlays, hue/saturation, brightness/contrast, …) are baked into that layer’s pixels; other layers stay separate
Masks / group effects	Applied to content underneath so the document is not collapsed
Blend modes	Passed through when the schema supports them; unsupported modes are flattened only with the layers they depend on

The PSD’s pre-rendered composite is intentionally not used as the final design — each element should stay selectable and editable.

---

Platform support

Environment	Support
Browser (client)	✅ Planned
Node.js (server)	✅ Planned

All processing is local; no external render service is required. For high-res output later, pass the resulting JSON to the Cloud Render API or server-side image generation.

---

Error handling (planned)

On parse failure the importer throws a structured Error:

try {
  const json = await psdToJson({ psd: buffer });
  store.loadJSON(json);
} catch (err) {
  // err.code === 'IMPORT_FAILED'
  // err.details?.format === 'psd'
  // err.cause → underlying parser error
  console.error(err);
}

Exact error codes will land in the package changelog / README and stay aligned with other import packages.

---

Related import / export

Capability	Notes
PDF export	Client / server PDF
Large format & HD	Print-grade resolution
Cloud Render API	Hosted server render
SVG / PDF import	Separate packages later, alongside PSD import

---

Troubleshooting

Result doesn’t match Photoshop?

• Simplify the PSD before import (flatten unused groups, rasterize complex smart objects)
• 3D layers, video layers, and complex layer comps are out of scope for v1
• Check browser / Node console warnings

Missing fonts / fallbacks?

• Imported JSON references fonts by family name; if the font isn’t installed or loaded where you render, the editor falls back
• Before export, declare font URLs via store.addFont / the cloud render fonts field — see Font consistency

Large files?

• PSDs up to a few hundred MB usually parse in the browser; for huge files or bulk jobs, run psdToJson() in Node.js
• After import, watch browser canvas limits for HD export — use Cloud Render when needed

Relationship to Fabric?

• @ydesign/psd-import only does PSD → design JSON
• Putting it on the canvas is @ydesign/core (Fabric) + @ydesign/react-editor loadJSON
• Browser and Node share one conversion path — no separate adapters

---

Roadmap

Stage	Scope
Now	Freeze docs / API shape; integrate via hand-written or other-tool JSON
First release	@ydesign/psd-import: text / raster / common vectors & masks
Later	Richer effects & blend modes, smart-object strategy, template-library hooks

Have PSD samples or product scenarios? Reach out via the pricing page or community channels — we prioritize high-traffic cases first.