Skip to content
Back to search

stitch-sdk

Generate UI screens from text prompts and extract their HTML and screenshots programmatically.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google-labs-code--stitch-sdk/badge.svg)](/listings/google-labs-code--stitch-sdk)

HTML

<a href="/listings/google-labs-code--stitch-sdk"><img src="/api/listings/google-labs-code--stitch-sdk/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Set your API key and generate a screen:

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

// STITCH_API_KEY must be set in the environment
const project = stitch.project("your-project-id");
const screen = await project.generate(
  "A login page with email and password fields",
);
const html = await screen.getHtml();
const imageUrl = await screen.getImage();

`html` is a download URL for the screen's HTML. `imageUrl` is a download URL for the screenshot.

Need to create a project first? Use the tool client:

const result = await stitch.callTool("create_project", { title: "My App" });

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # @google/stitch-sdk
  2. [![npm version](https://img.shields.io/npm/v/@google/stitch-sdk)](https://www.npmjs.com/package/@google/stitch-sdk)
  3. Generate UI screens from text prompts and extract their HTML and screenshots programmatically.
  4. ## Quick Start
  5. Set your API key and generate a screen:
  6. ```ts
  7. import { stitch } from "@google/stitch-sdk";
  8. // STITCH_API_KEY must be set in the environment
  9. const project = stitch.project("your-project-id");
  10. const screen = await project.generate(
  11. "A login page with email and password fields",
  12. );
  13. const html = await screen.getHtml();
  14. const imageUrl = await screen.getImage();
  15. ```
  16. `html` is a download URL for the screen's HTML. `imageUrl` is a download URL for the screenshot.
  17. Need to create a project first? Use the tool client:
  18. ```ts
  19. const result = await stitch.callTool("create_project", { title: "My App" });
  20. ```
  21. ## Install
  22. ```bash
  23. npm install @google/stitch-sdk
  24. ```
  25. To use `stitchTools()` with the [Vercel AI SDK](https://sdk.vercel.ai/), install `ai` as well:
  26. ```bash
  27. npm install @google/stitch-sdk ai
  28. ```
  29. ## Working with Projects and Screens
  30. ### List existing projects
  31. ```ts
  32. import { stitch } from "@google/stitch-sdk";
  33. const projects = await stitch.projects();
  34. for (const project of projects) {
  35. console.log(project.id, project.projectId);
  36. const screens = await project.screens();
  37. console.log(` ${screens.length} screens`);
  38. }
  39. ```
  40. ### Reference a project by ID
  41. If you already have a project ID, reference it directly:
  42. ```ts
  43. const project = stitch.project("4044680601076201931");
  44. // Call methods on it — each method fetches data as needed
  45. const screens = await project.screens();
  46. ```
  47. ### Edit a screen
  48. ```ts
  49. const screen = await project.generate("A dashboard with charts");
  50. const edited = await screen.edit("Make the background dark and add a sidebar");
  51. const editedHtml = await edited.getHtml();
  52. ```
  53. ### Generate variants
  54. ```ts
  55. const variants = await screen.variants("Try different color schemes", {
  56. variantCount: 3,
  57. creativeRange: "EXPLORE",
  58. aspects: ["COLOR_SCHEME", "LAYOUT"],
  59. });
  60. for (const variant of variants) {
  61. console.log(variant.id, await variant.getHtml());
  62. }
  63. ```
  64. `variantOptions` fields:
  65. | Field | Type | Default | Description |
  66. | --------------- | ---------- | ----------- | ------------------------------------------------------------------------- |
  67. | `variantCount` | `number` | 3 | Number of variants (1–5) |
  68. | `creativeRange` | `string` | `"EXPLORE"` | `"REFINE"`, `"EXPLORE"`, or `"REIMAGINE"` |
  69. | `aspects` | `string[]` | all | `"LAYOUT"`, `"COLOR_SCHEME"`, `"IMAGES"`, `"TEXT_FONT"`, `"TEXT_CONTENT"` |
  70. ## Tool Client (Agent Usage)
  71. For agents and orchestration scripts that need direct MCP tool access:
  72. ```ts
  73. import { stitch } from "@google/stitch-sdk";
  74. // List available tools
  75. const { tools } = await stitch.listTools();
  76. for (const tool of tools) {
  77. console.log(tool.name, tool.description);
  78. }
  79. // Call a tool directly
  80. const result = await stitch.callTool("create_project", {
  81. title: "Agent Project",
  82. });
  83. ```
  84. For explicit configuration (custom API key, base URL), use `StitchToolClient` directly:
  85. ```ts
  86. import { StitchToolClient } from "@google/stitch-sdk";
  87. const client = new StitchToolClient({ apiKey: "your-api-key" });
  88. const result = await client.callTool("create_project", {
  89. title: "Agent Project",
  90. });
  91. await client.close();
  92. ```
  93. The client auto-connects on the first `callTool` or `listTools` call. No explicit `connect()` needed.
  94. ## AI SDK Integration
  95. Drop Stitch tools directly into the [Vercel AI SDK](https://sdk.vercel.ai/):
  96. ```ts
  97. import { generateText, stepCountIs } from "ai";
  98. import { google } from "@ai-sdk/google";
  99. import { stitchTools } from "@google/stitch-sdk/ai";
  100. const { text, steps } = await generateText({
  101. model: google("gemini-2.5-flash"),
  102. tools: stitchTools(),
  103. prompt: "Create a project and generate a modern dashboard with a stat card",
  104. stopWhen: stepCountIs(5),
  105. });
  106. // The model autonomously calls create_project, generate_screen, get_screen
  107. const toolCalls = steps.flatMap((s) => s.toolCalls);
  108. console.log(`Model called ${toolCalls.length} tools`);
  109. ```
  110. Filter to specific tools:
  111. ```ts
  112. const tools = stitchTools({
  113. include: ["create_project", "generate_screen_from_text", "get_screen"],
  114. });
  115. ```
  116. ## ADK Integration
  117. Use Stitch tools with the [Google Agent Development Kit (ADK) for TypeScript](https://adk.dev/get-started/typescript/):
  118. ```ts
  119. import { stitchAdkTools } from "@google/stitch-sdk/adk";
  120. import { LlmAgent } from "@google/adk";
  121. // Get all Stitch tools formatted as ADK FunctionTools
  122. const tools = stitchAdkTools();
  123. // You can now pass these tools to your ADK agents
  124. const designerAgent = new LlmAgent({
  125. name: "Designer",
  126. model: "gemini-2.5-pro",
  127. instruction: "You are a designer. Create a project and generate a screen.",
  128. tools,
  129. });
  130. ```
  131. Filter to specific tools:
  132. ```ts
  133. const tools = stitchAdkTools({
  134. include: ["create_project", "generate_screen_from_text", "get_screen"],
  135. });
  136. ```
  137. ## API Reference
  138. ### `Stitch`
  139. The root class. Manages projects.
  140. | Method | Parameters | Returns | Description |
  141. | ------------- | ------------ | -------------------- | --------------------------------------- |
  142. | `projects()` | — | `Promise<Project[]>` | List all accessible projects |
  143. | `project(id)` | `id: string` | `Project` | Reference a project by ID (no API call) |
  144. ### `Project`
  145. A Stitch project containing screens.
  146. | Property | Type | Description |
  147. | ----------- | -------- | --------------------------------------- |
  148. | `id` | `string` | Alias for `projectId` |
  149. | `projectId` | `string` | Bare project ID (no `projects/` prefix) |
  150. | Method | Parameters | Returns | Description |
  151. | ---------------------------------- | ------------------------------------------- | ------------------------- | --------------------------------------------- |
  152. | `generate(prompt, deviceType?)` | `prompt: string`, `deviceType?: DeviceType` | `Promise<Screen>` | Generate a screen from a text prompt |
  153. | `screens()` | — | `Promise<Screen[]>` | List all screens in the project |
  154. | `getScreen(screenId)` | `screenId: string` | `Promise<Screen>` | Retrieve a specific screen by ID |
  155. | `createDesignSystem(designSystem)` | `designSystem: object` | `Promise<DesignSystem>` | Create a design system for this project |
  156. | `listDesignSystems()` | — | `Promise<DesignSystem[]>` | List all design systems in this project |
  157. | `designSystem(id)` | `id: string` | `DesignSystem` | Reference a design system by ID (no API call) |
  158. `DeviceType`: `"MOBILE"` \| `"DESKTOP"` \| `"TABLET"` \| `"AGNOSTIC"`
  159. ### `Screen`
  160. A generated UI screen. Provides access to HTML and screenshots.
  161. | Property | Type | Description |
  162. | ----------- | -------- | -------------------- |
  163. | `id` | `string` | Alias for `screenId` |
  164. | `screenId` | `string` | Bare screen ID |
  165. | `projectId` | `string` | Parent project ID |
  166. | Method | Parameters | Returns | Description |
  167. | --------------------------------------------------------- | ------------------------------------------ | ------------------- | ---------------------------------------- |
  168. | `edit(prompt, deviceType?, modelId?)` | `prompt: string` | `Promise<Screen>` | Edit the screen with a text prompt |
  169. | `variants(prompt, variantOptions, deviceType?, modelId?)` | `prompt: string`, `variantOptions: object` | `Promise<Screen[]>` | Generate design variants |
  170. | `getHtml()` | — | `Promise<string>` | Get the screen's HTML download URL |
  171. | `getImage()` | — | `Promise<string>` | Get the screen's screenshot download URL |
  172. `getHtml()` and `getImage()` use cached data from the generation response when available. If the screen was loaded from `screens()` or `getScreen()`, they call the `get_screen` API automatically.
  173. `modelId`: `"GEMINI_3_8_FLASH"` \| `"GEMINI_3_5_FLASH_LITE"` (optional, defaults to backend default)
  174. ### `DesignSystem`
  175. A visual theme or branding applied to projects and screens.
  176. | Property | Type | Description |
  177. | ----------- | -------- | ----------------------------------- |
  178. | `id` | `string` | Alias for `assetId` |
  179. | `assetId` | `string` | Bare asset ID (no `assets/` prefix) |
  180. | `projectId` | `string` | Parent project ID |
  181. | Method | Parameters | Returns | Description |
  182. | -------------------------------- | ----------------------------------- | ----------------------- | ----------------------------------- |
  183. | `update(designSystem)` | `designSystem: object` | `Promise<DesignSystem>` | Update the design system's theme |
  184. | `apply(selectedScreenInstances)` | `selectedScreenInstances: object[]` | `Promise<Screen[]>` | Apply this design system to screens |
  185. `selectedScreenInstances` is an array of `{ id: string, sourceScreen: string }` objects. Get these from `project.data.screenInstances`.
  186. ### `StitchToolClient`
  187. Low-level authenticated pipe to the Stitch MCP server. Use this when you need direct tool access (e.g., in an AI agent).
  188. ```ts
  189. const client = new StitchToolClient({ apiKey: "..." });
  190. const result = await client.callTool<any>("tool_name", { arg: "value" });
  191. await client.close();
  192. ```
  193. | Method | Parameters | Returns | Description |
  194. | ------------------------- | ------------------------------------------- | -------------------- | ---------------------------------------------- |
  195. | `callTool<T>(name, args)` | `name: string`, `args: Record<string, any>` | `Promise<T>` | Call an MCP tool |
  196. | `listTools()` | — | `Promise<{ tools }>` | List available tools |
  197. | `connect()` | — | `Promise<void>` | Explicitly connect (auto-called by `callTool`) |
  198. | `close()` | — | `Promise<void>` | Close the connection |
  199. ### `stitchTools()`
  200. Returns all Stitch MCP tools as Vercel AI SDK `Tool` objects. Import from `@google/stitch-sdk/ai`. Drop into `generateText()` or `streamText()` — the model calls tools autonomously.
  201. ```ts
  202. import { generateText, stepCountIs } from "ai";
  203. import { stitchTools } from "@google/stitch-sdk/ai";
  204. const { text } = await generateText({
  205. model: yourModel,
  206. tools: stitchTools(),
  207. prompt: "Create a login page",
  208. stopWhen: stepCountIs(5),
  209. });
  210. ```
  211. | Option | Type | Default | Description |
  212. | --------- | ---------- | ---------------- | ------------------------------- |
  213. | `apiKey` | `string` | `STITCH_API_KEY` | Override env var |
  214. | `include` | `string[]` | all tools | Only expose specific tool names |
  215. Each tool's `execute` function calls `StitchToolClient.callTool()` under the hood. The client is lazily initialized via the singleton.
  216. ### `StitchProxy`
  217. An MCP proxy server that forwards requests to Stitch. Use this to expose Stitch tools through your own MCP server.
  218. ```ts
  219. import { StitchProxy } from "@google/stitch-sdk";
  220. import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
  221. const proxy = new StitchProxy({ apiKey: "..." });
  222. const transport = new StdioServerTransport();
  223. await proxy.start(transport);
  224. ```
  225. ### `stitch` Singleton
  226. A pre-configured `Stitch` instance that reads `STITCH_API_KEY` from the environment. Lazily initialized on first use.
  227. ```ts
  228. import { stitch } from "@google/stitch-sdk";
  229. // No setup needed — just use it
  230. const projects = await stitch.projects();
  231. ```
  232. ## Configuration
  233. ### Environment Variables
  234. | Variable | Required | Description |
  235. | ---------------------- | ------------------ | ------------------------------------------- |
  236. | `STITCH_API_KEY` | Yes (or use OAuth) | API key for authentication |
  237. | `STITCH_ACCESS_TOKEN` | No | OAuth access token (alternative to API key) |
  238. | `GOOGLE_CLOUD_PROJECT` | With OAuth | Google Cloud project ID |
  239. | `STITCH_HOST` | No | Override the MCP server URL |
  240. ### Explicit Configuration
  241. ```ts
  242. import { Stitch, StitchToolClient } from "@google/stitch-sdk";
  243. const client = new StitchToolClient({
  244. apiKey: "your-api-key",
  245. baseUrl: "https://stitch.googleapis.com/mcp",
  246. timeout: 300_000,
  247. });
  248. const sdk = new Stitch(client);
  249. const projects = await sdk.projects();
  250. ```
  251. | Option | Type | Default | Description |
  252. | ------------- | -------- | ----------------------------------- | -------------------- |
  253. | `apiKey` | `string` | `STITCH_API_KEY` | API key |
  254. | `accessToken` | `string` | `STITCH_ACCESS_TOKEN` | OAuth token |
  255. | `projectId` | `string` | `GOOGLE_CLOUD_PROJECT` | Cloud project ID |
  256. | `baseUrl` | `string` | `https://stitch.googleapis.com/mcp` | MCP server URL |
  257. | `timeout` | `number` | `300000` | Request timeout (ms) |
  258. Authentication requires either `apiKey` or both `accessToken` and `projectId`.
  259. ## Error Handling
  260. All domain class methods throw `StitchError` on failure:
  261. ```ts
  262. import { stitch, StitchError } from "@google/stitch-sdk";
  263. try {
  264. const project = stitch.project("bad-id");
  265. await project.screens();
  266. } catch (error) {
  267. if (error instanceof StitchError) {
  268. console.error(error.code); // "UNKNOWN_ERROR"
  269. console.error(error.message); // Human-readable description
  270. console.error(error.recoverable); // false
  271. }
  272. }
  273. ```
  274. Error codes: `AUTH_FAILED`, `NOT_FOUND`, `PERMISSION_DENIED`, `RATE_LIMITED`, `NETWORK_ERROR`, `VALIDATION_ERROR`, `CLARIFICATION_REQUIRED`, `UNKNOWN_ERROR`.
  275. ### Answering a clarifying question
  276. `generate()`, `edit()`, `variants()`, and `apply()` can end with Stitch asking a question instead of producing screens. That throws a recoverable `StitchError` with code `CLARIFICATION_REQUIRED`, and `error.clarification` holds the question and suggested replies. To answer, call the method again with your answer as the prompt:
  277. ```ts
  278. import { stitch, StitchError } from "@google/stitch-sdk";
  279. const project = stitch.project("4044680601076201931");
  280. try {
  281. await project.generate("An app that picks your morning espresso");
  282. } catch (error) {
  283. if (error instanceof StitchError && error.code === "CLARIFICATION_REQUIRED") {
  284. console.log(error.clarification?.question);
  285. const reply = error.clarification?.suggestions[0] ?? "Keep it simple";
  286. const screen = await project.generate(reply);
  287. console.log(screen.id);
  288. } else {
  289. throw error;
  290. }
  291. }
  292. ```
  293. ---
  294. ## Disclaimer
  295. This is not an officially supported Google product. This project is not
  296. eligible for the [Google Open Source Software Vulnerability Rewards
  297. Program](https://bughunters.google.com/open-source-security).
  298. ## License
  299. Apache 2.0 — see [LICENSE](LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.