Registry / llm-agents / sunpeak

sunpeak

JSON →
library0.20.7jsnpmunverified

Sunpeak (current version 0.20.7) is an AI application framework, testing framework, and inspector specifically designed for building and debugging Multi-Platform (MCP) Apps, such as those for ChatGPT and Claude. It provides a convention-over-configuration approach to simplify wiring MCP servers, handling protocol messages, managing resource HTML bundles, and setting up dev environments with hot module replacement (HMR). Its key differentiators include a robust testing framework that simulates host runtimes and provides simulation fixtures for reproducible testing across various hosts, themes, and data states without relying on external accounts or API credits. It also offers a visual inspector for debugging. Sunpeak releases are frequent, primarily focusing on bug fixes, performance improvements, and feature enhancements within the 0.x.x minor version range, indicating active development.

npm install sunpeak
INSTALL
IMPORT
SIG · SUNPEAK
S
sunpeak
llm-agentsjavascriptv0.20.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

test
import { test, expect } from 'sunpeak/test';
const { test, expect } = require('sunpeak/test');
The testing utilities are designed for ESM. Use named imports. CommonJS `require` will fail in modern setups.
useToolData
import { useToolData, useAppState } from 'sunpeak/react';
These React hooks are essential for building interactive MCP Apps within the Sunpeak framework.
defineConfig
import { defineConfig } from 'sunpeak/test/config';
import { defineConfig } from 'sunpeak/test/live/config';
Used for Playwright test configurations. The path changed in v0.19.1; `sunpeak/test/live/config` is deprecated.

This quickstart demonstrates how to initialize a Sunpeak project and write an end-to-end test for an MCP App using the `sunpeak/test` framework, including mocking AI model interactions.

import { test, expect } from 'sunpeak/test'; import { createOpenAI } from '@ai-sdk/openai'; // To initialize a new Sunpeak project: // npx sunpeak new // Then, add a test file (e.g., tests/e2e/my-app.test.ts) // Mock your AI model for consistent testing const mockOpenAI = createOpenAI({ apiKey: process.env.OPENAI_API_KEY ?? 'mock-key' }); test('My MCP App loads and renders a tool', async ({ page, inspector, mcp }) => { // Render a specific tool within the Sunpeak inspector await inspector.renderTool({ name: 'my-awesome-tool', params: { query: 'test' } }); // Wait for the tool's UI to appear and interact with it await expect(page.locator('text=Welcome to My Awesome Tool')).toBeVisible(); // You can also mock tool calls to the MCP server mcp.useTool(async ({ name, params }) => { if (name === 'my-awesome-tool') { const result = await mockOpenAI.chat({ model: 'gpt-4o', messages: [{ role: 'user', content: params.query as string }], }); return { result: result.text }; } return { result: 'Unknown tool' }; }); // Simulate an interaction or assert on UI changes await page.locator('button', { hasText: 'Execute' }).click(); await expect(page.locator('text=Execution complete')).toBeVisible(); }); // To run the tests: // npx sunpeak test --e2e
Debug
Known issues
breakingThe test fixture API was redesigned, splitting the single `mcp` fixture into two: `mcp` (for MCP protocol methods) and `inspector` (for Sunpeak inspector rendering methods like `renderTool` and `host`). Code using `mcp.renderTool` will now fail.
fix
Update test files to use the new `inspector` fixture for rendering and hosting methods. For example, change `mcp.renderTool(...)` to `inspector.renderTool(...)`.
affects: >=0.20.1
breakingSignificant changes to the testing framework import paths and default fixtures. `sunpeak/test` became the primary module for the `mcp` fixture, replacing older `live` imports. `defineConfig()` moved from `sunpeak/test/live/config` to `sunpeak/test/config`.
fix
Review and update all test file imports. Change `import { mcp } from 'sunpeak/test/live'` to `import { mcp } from 'sunpeak/test'`. Update Playwright config imports from `sunpeak/test/live/config` to `sunpeak/test/config`.
affects: >=0.19.1
gotchaUnit tests were updated for ESM compatibility in v0.20.7, which might cause issues with older CommonJS-style test setups or specific module resolvers.
fix
Ensure your `vitest` or testing configuration is set up for ESM, especially if you encounter `require is not defined` errors. This might involve updating `package.json` to `"type": "module"` or configuring loaders.
affects: >=0.20.7
gotchaWhile direct `vitest run` or `playwright test` commands still function, the recommended way to run tests is via `npx sunpeak test`. Bypassing the CLI might lead to missing environment setups, configurations, or features managed by the `sunpeak` CLI.
fix
Update your `package.json` scripts to use `"test": "sunpeak test"`, `"test:unit": "sunpeak test --unit"`, etc., to leverage the `sunpeak` CLI's managed test environment.
affects: >=0.19.2
gotchaSunpeak has several peer dependencies, including `react`, `react-dom`, and the `@ai-sdk/*` packages. Incorrect versions or missing peer dependencies will lead to runtime errors or build failures.
fix
Ensure that `react` and `react-dom` (v18 or v19) are installed alongside `sunpeak`. Additionally, install the specific `@ai-sdk` packages (e.g., `@ai-sdk/openai`) you intend to use with compatible versions.
affects: All versions
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in a modern Sunpeak project, which primarily uses ESM.
fix
Convert `require()` statements to ES module `import` syntax. Ensure your project's `package.json` has `"type": "module"` or configure your build tools for ESM.
TypeError: mcp.renderTool is not a function
Using the deprecated `mcp.renderTool` method after the v0.20.1 breaking change, which moved rendering capabilities to the `inspector` fixture.
fix
Replace `mcp.renderTool(...)` with `inspector.renderTool(...)` in your test files. The `inspector` fixture needs to be destructured from the `test` parameters (e.g., `async ({ page, inspector }) => { ... }`).
Error: Cannot find module 'sunpeak/test/live' or 'sunpeak/test/live/config'
Attempting to import from old testing module paths that were deprecated and moved in v0.19.1.
fix
Update import paths: `sunpeak/test/live` is now `sunpeak/test` (for fixtures like `mcp`), and `sunpeak/test/live/config` is now `sunpeak/test/config` (for Playwright's `defineConfig`).
Error: Missing peer dependency "react"
The `react` or `react-dom` peer dependency is not installed, or its version is incompatible with Sunpeak.
fix
Install `react` and `react-dom` (versions ^18.0.0 || ^19.0.0) in your project: `npm install react react-dom` or `yarn add react react-dom`. Verify versions are compatible.
Upgrade
Version history
0.20.7latest on npm
Audit
Dependencies
reactrequiredRequired for building UIs with Sunpeak's App Framework and inspector rendering.
react-domrequiredDOM rendering for React components within Sunpeak apps.
airequiredCore AI SDK for interacting with various language models.
@ai-sdk/openaioptionalOpenAI provider for the AI SDK.
@ai-sdk/anthropicoptionalAnthropic provider for the AI SDK.
@ai-sdk/googleoptionalGoogle AI provider for the AI SDK.
Agent activity
20 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
sunpeak — npm install sunpeak · libregistry