How to upload files

Got a mockup, a screenshot, or an HTML prototype on disk? Upload it directly to Stitch and turn it into a screen — no manual import, no browser, no base64 encoding headaches.

Upload a file

import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");

const result = await project.upload("./mockup.png", {
  title: "Home Screen",
});

if (result.success) {
  const [screen] = result.screens;
  console.log(`Screen created: ${screen.id}`);
  const html = await screen.getHtml();
  const imageUrl = await screen.getImage();
}

The SDK reads the file from disk and posts it directly to the Stitch REST API. No output token limits apply — unlike agent-driven MCP calls that choke on base64-encoded payloads.

Supported formats

Extension	Type	Screen type
.png	Image	IMAGE
.jpg / .jpeg	Image	IMAGE
.webp	Image	IMAGE
.html / .htm	Document	DOCUMENT

HTML files are uploaded as document screens — useful for importing static snapshots of existing web pages or prototypes.

Options

Option	Type	Default	Description
title	string	—	Display title for the screen in Stitch
createScreenInstances	boolean	true	Whether to add the screen to the canvas

Upload HTML prototypes

Upload a self-contained HTML file to import an existing design:

const result = await project.upload("./prototype.html", {
  title: "Landing Page Prototype",
});

The SDK detects .html and .htm extensions automatically and sets the screen type to DOCUMENT.

Handle results

upload() never throws. It returns a discriminated result object:

const result = await project.upload("./mockup.png");

if (result.success) {
  console.log(`Created ${result.screens.length} screens`);
} else {
  console.error(`${result.error.code}: ${result.error.message}`);
}

Error codes

Code	Meaning
FILE_NOT_FOUND	File doesn’t exist at the given path
UNSUPPORTED_FORMAT	Extension isn’t .png, .jpg, .jpeg, .webp, .html, or .htm
AUTH_FAILED	Invalid or missing API key
UPLOAD_FAILED	Server rejected the upload
UNKNOWN_ERROR	Unexpected failure

Bulk upload

Upload multiple files in a loop:

import fs from "fs/promises";
import path from "path";

const project = stitch.project("your-project-id");
const files = await fs.readdir("./designs");

for (const file of files) {
  if (/\.(png|jpe?g|webp|html?)$/i.test(file)) {
    const result = await project.upload(
      path.join("./designs", file),
      { title: path.parse(file).name },
    );
    if (result.success) {
      console.log(`Uploaded ${file} → ${result.screens[0].id}`);
    }
  }
}