Sealos App Builder

Sealos App Builder

Overview

Use this skill to turn a generic web app into a Sealos app that runs inside Sealos Desktop, or to scaffold a new Sealos app from scratch. Focus on the repeatable parts: SDK initialization, session access, language sync, business-data integration, local debugging through a Desktop test app, and publish readiness.

Prefer a simple, teachable implementation that a beginner can understand and extend.

Core Workflow

1. Identify the starting point

Classify the request into one of these paths:

1. Create a new Sealos app from scratch. 2. Adapt an existing web app to run inside Sealos Desktop. 3. Add Sealos identity and business-data integration to an app that already renders. 4. Produce documentation or a tutorial instead of code changes.

If the repository already contains Sealos-related code, inspect local sources first. In particular:

1. Look for packages/client-sdk or equivalent SDK sources. 2. Look for existing provider apps under providers/ or similar directories. 3. Reuse the repository's established framework and routing patterns when they are already in place.

If the repository does not contain local Sealos sources, use the bundled references in this skill as the baseline.

2. Integrate the Sealos app SDK

Treat Sealos Desktop integration as a root-level concern.

Before using any starter template, install the SDK first:

pnpm add @labring/sealos-desktop-sdk

Use npm install @labring/sealos-desktop-sdk or yarn add @labring/sealos-desktop-sdk when the project uses a different package manager.

1. Initialize the SDK once in a client-only root component. 2. Fetch getSession() and getLanguage() early. 3. Store session, language, loading state, and desktop availability in a shared context or store. 4. Listen for language changes through EVENT_NAME.CHANGE_I18N when the app needs runtime language sync. 5. Add a graceful fallback when the app is opened outside Sealos Desktop.

Read references/minimal-app-template.md before implementing the root integration. If the app uses Next.js App Router, also read references/nextjs-app-router.md.

Use one of these starter templates:

1. assets/templates/react/sealos-provider.tsx for React. 2. assets/templates/vue/use-sealos.ts for Vue.

3. Connect Sealos identity to business data

For most apps, the key integration is not the iframe itself but the user mapping.

1. Use session.user.id as the stable app-level user identifier. 2. Persist display-friendly fields such as name, avatar, k8sUsername, and nsid when useful. 3. Keep business data in the app's own database and API routes. 4. Model Sealos user identity as input to your business logic, not as your entire backend.

Read references/data-integration-patterns.md when you need schema or API guidance.

4. Prepare local debugging in the real runtime

Do not assume a successful browser render means Sealos integration works.

The app usually needs to be opened by Sealos Desktop in an iframe for SDK calls like getSession() to succeed. When local debugging is part of the task, read references/local-debug-and-test-app.md.

Use these rules:

1. Explain clearly when a page is outside Sealos Desktop. 2. Prefer a test app inside Sealos Desktop for end-to-end verification. 3. Avoid server-side SDK calls.

5. Prepare for publishing

When the user wants deployment or launch readiness:

1. Verify environment variables. 2. Verify database connectivity and migrations. 3. Confirm the app works when launched from Sealos Desktop. 4. Confirm any cross-app navigation or event usage is valid. 5. Summarize the remaining manual registration or platform configuration steps.

Use references/publish-checklist.md as the release checklist.

Implementation Rules

Keep the integration simple

Default to the smallest viable Sealos integration:

1. One root provider or store. 2. One business identity mapping pattern. 3. One fallback path for non-Desktop access.

Avoid spreading SDK initialization across multiple pages or components.

Prefer the repository's real SDK surface

If the current workspace contains actual Sealos SDK sources or existing Sealos apps:

1. Inspect those sources. 2. Follow the real exported APIs and types. 3. Call out repository-specific differences from generic examples.

Use the official SDK package name

Use @labring/sealos-desktop-sdk in generated examples and starter code by default.

Only deviate from that if the target repository already has an established local workspace alias and the user explicitly wants to preserve it.

Decision Guide

If the user asks for "How do I build a Sealos app?"

Provide:

1. A short explanation of the runtime model. 2. A minimal SDK integration example. 3. A business-data mapping example. 4. Local debugging guidance through a Sealos Desktop test app.

If the user asks to modify an existing app

Do this order:

1. Inspect the current app entry point. 2. Add or refactor a single root Sealos provider. 3. Wire business APIs to session.user.id. 4. Verify fallback behavior outside Desktop.

If the user asks for documentation or a tutorial

Structure the output around:

1. What a Sealos app is. 2. How to initialize the SDK. 3. How to obtain and use the session. 4. How to integrate business data. 5. How to debug through a Desktop test app. 6. How to publish and verify.

References

Read only the files needed for the task:

1. references/sdk-capabilities.md for available SDK APIs and runtime behavior. 2. references/minimal-app-template.md for the recommended root integration pattern. 3. references/nextjs-app-router.md for a concrete Next.js App Router placement example. 4. references/data-integration-patterns.md for user mapping, database schemas, and API shapes. 5. references/local-debug-and-test-app.md for iframe-based debugging and Desktop test app setup. 6. references/publish-checklist.md for launch-readiness steps.

Data Integration Patterns

Use this reference when wiring Sealos identity into an app's own business data.

Core principle

Sealos provides runtime identity. Your app still owns its own database, business rules, and APIs.

For most apps:

1. Use session.user.id as the stable application user key. 2. Store display fields such as name and avatar as convenient denormalized data. 3. Keep business records in your own tables.

Recommended user mapping

Persist a user record that mirrors the most useful Sealos fields:

1. id 2. name 3. avatar 4. k8sUsername 5. nsid

This makes later joins, ownership checks, and display logic simpler.

Common schema patterns

Pattern A: App users + records

Use when the app has reusable user profiles plus separate business entities.

Example:

1. users 2. posts 3. votes 4. projects 5. records

Pattern B: Single-purpose table

Use when the app is simple and only needs one business table keyed by user.

Good for:

1. surveys 2. feature flags 3. profile preferences 4. user-scoped settings

API pattern

Typical write flow:

1. Read session.user in the client. 2. Send the relevant identity fields plus the business payload to your API route. 3. Upsert the user row. 4. Insert or upsert the business row.

Typical read flow:

1. Query business data from the server. 2. Order and limit for the UI. 3. Return a display-ready response.

When creating starter code, prefer a business-neutral route shape over a demo-specific endpoint.

Guardrails

1. Do not hardcode database connection strings. 2. Do not make the whole backend depend on raw Sealos session objects. 3. Keep Sealos fields narrow and intentional. 4. If authentication requirements become stricter, move validation into the server later without changing the core data model.

Local Debug and Test App

Use this reference when SDK calls work inconsistently during development.

Why direct browser access is misleading

A Sealos app can render normally in a browser tab and still fail to integrate with Desktop.

That usually happens because:

1. the app is not inside the Sealos Desktop iframe 2. Desktop is not present to answer SDK requests 3. calls such as getSession() or getLanguage() time out or reject

Local debugging checklist

1. Start the app locally. 2. Confirm the root Sealos provider initializes only in the browser. 3. Open the app through a Sealos Desktop test app, not only through the raw URL. 4. Verify getSession() succeeds inside Desktop. 5. Verify the standalone fallback is readable outside Desktop.

Test app guidance

For end-to-end Sealos debugging, create a test app in Sealos Desktop that points to the local or preview URL of your app.

Use it to verify:

1. session retrieval 2. language retrieval 3. runtime language change handling 4. business API writes tied to the Sealos user 5. cross-app event behavior, if any

Failure patterns

getSession() fails outside Desktop

This is expected. Show a user-facing fallback instead of treating it as a mysterious bug.

Session works only after reload

Check whether the SDK is being initialized more than once or from multiple entry points.

Event listeners behave strangely

Look for duplicate createSealosApp() calls or repeated event subscriptions without cleanup.

Minimal App Template

Use this reference when a Sealos app needs the smallest stable integration pattern.

Recommended shape

Put the Sealos integration in one client-only root provider.

Install first

Install the official SDK package before copying any template code:

pnpm add @labring/sealos-desktop-sdk

Equivalent commands:

npm install @labring/sealos-desktop-sdk
yarn add @labring/sealos-desktop-sdk

The provider should own:

1. SDK initialization. 2. Session loading. 3. Language loading. 4. Desktop availability state. 5. Optional language-change subscription.

Recommended state shape

type SealosContextValue = {
  session: SessionV1 | null;
  language: string;
  loading: boolean;
  error: string | null;
  isInSealosDesktop: boolean;
};

Root integration rules

1. Call createSealosApp() once. 2. Fetch getSession() and getLanguage() early. 3. Store the results centrally. 4. Clean up listeners on unmount. 5. Show a clear fallback if Desktop is unavailable.

Best practices

Use a single provider

Prefer one provider or store near the app root over repeated per-page initialization.

Make the fallback explicit

If the app is opened outside Sealos Desktop, set:

1. isInSealosDesktop = false 2. loading = false 3. a friendly error or info message

Keep the business layer unaware of iframe details

Page-level components should consume:

1. session 2. language 3. isInSealosDesktop

They should not care about raw postMessage plumbing.

Starter file

Use one of these starter files:

1. ../assets/templates/react/sealos-provider.tsx for React. 2. ../assets/templates/vue/use-sealos.ts for Vue.

Next.js App Router

If the app uses Next.js App Router, read nextjs-app-router.md and keep the provider inside a client component that is mounted from the root layout.

Next.js App Router

Use this reference when the target app uses Next.js App Router and you need a concrete placement example for the Sealos integration.

Recommended structure

Use a small client-only wrapper for providers, then mount it from app/layout.tsx.

Example layout:

app/
  layout.tsx
  providers.tsx
components/
  sealos-provider.tsx

Why this structure works

1. app/layout.tsx can remain a server component. 2. app/providers.tsx becomes the client boundary for SDK initialization. 3. components/sealos-provider.tsx contains the reusable Sealos context logic.

Minimal example

components/sealos-provider.tsx

Use ../assets/templates/react/sealos-provider.tsx.

app/providers.tsx

'use client';

import type { ReactNode } from 'react';
import { SealosProvider } from '@/components/sealos-provider';

export function Providers({ children }: { children: ReactNode }) {
  return <SealosProvider>{children}</SealosProvider>;
}

app/layout.tsx

import type { ReactNode } from 'react';
import { Providers } from './providers';

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Rules

1. Do not call createSealosApp() directly from app/layout.tsx if it is a server component. 2. Keep SDK initialization in a client component such as providers.tsx or the provider itself. 3. Expose session, language, and isInSealosDesktop through context or a store so route segments stay simple.

Publish Checklist

Use this reference when preparing a Sealos app for handoff, preview, or production launch.

Functional checks

1. The app loads correctly when opened by Sealos Desktop. 2. The app handles direct browser access gracefully. 3. getSession() succeeds inside Desktop. 4. Business data writes are tied to the correct Sealos user. 5. Business data reads render correctly for real records.

Configuration checks

1. Environment variables are documented and present. 2. Database migrations or schema setup are complete. 3. The package name and SDK imports match the target workspace. 4. Any required Desktop-side event names are confirmed.

Release checks

1. The app has a stable URL or deployment target. 2. A Sealos Desktop test app is already verified against that URL. 3. Manual registration or platform configuration steps are written down. 4. Beginner-facing docs explain the Desktop runtime requirement.

Recommended final summary

When handing off the work, summarize:

1. what was implemented 2. how to run it 3. how to validate it inside Sealos Desktop 4. which steps remain manual

SDK Capabilities

Use this reference when you need a concise explanation of the app-side Sealos SDK surface.

Runtime model

A Sealos app is typically a web app loaded inside Sealos Desktop through an iframe. The app SDK communicates with Desktop through postMessage.

Install

Install the official package before using the SDK in starter code:

pnpm add @labring/sealos-desktop-sdk

Implications:

1. The SDK must be initialized in the browser. 2. Session-dependent calls usually succeed only when the page is opened by Sealos Desktop. 3. Repeated initialization can create noisy listeners or stale instances.

Common imports

Use the official package name in examples:

import { EVENT_NAME } from '@labring/sealos-desktop-sdk';
import { createSealosApp, sealosApp } from '@labring/sealos-desktop-sdk/app';

If a specific repository already exposes the SDK through a local workspace alias, preserve that only when the repository clearly depends on it.

Core app-side APIs

createSealosApp()

Initialize the SDK in a client-only context.

Typical behavior:

1. Register the message listener. 2. Create the request-response bridge to Desktop. 3. Return a cleanup function when supported by the implementation.

Use it once near the app root.

sealosApp.getSession()

Fetch the current Sealos session.

Typical useful fields:

type SessionUser = {
  id: string;
  name: string;
  avatar: string;
  k8sUsername: string;
  nsid: string;
};

Use session.user.id as the stable business key unless the repository uses a stronger existing convention.

sealosApp.getLanguage()

Fetch the current Desktop language.

Typical response:

{ lng: 'en' }

sealosApp.addAppEventListen(EVENT_NAME.CHANGE_I18N, handler)

Listen for language changes emitted by Desktop.

Use this only when runtime language changes matter. Many simple apps can read language once and stop there.

sealosApp.getWorkspaceQuota()

Fetch workspace quota information. Use this when the app creates or provisions resources that should respect workspace limits.

sealosApp.getHostConfig()

Fetch host configuration and feature flags, such as subscription availability or cloud-domain details.

sealosApp.runEvents(name, data)

Send an event to Desktop.

Important limitation:

This is only useful when Desktop actually implements the named event. Treat event names such as openDesktopApp as platform conventions, not universally guaranteed APIs.

Practical rules

1. Never call the SDK from the server. 2. Expect failure when the app is opened directly in a browser tab. 3. Keep one root integration layer. 4. Prefer a user-facing fallback message instead of silent failure.