sw-app-sdk-js

sw-app-sdk-js — Shopware App JS/TS SDK Reference

When to Apply

• Setting up an app server in TypeScript (Node/Bun/Deno/Cloudflare Workers)
• Implementing /app/register + /app/register/confirm endpoints
• Validating shopware-shop-signature HMAC with WebCrypto
• Storing shops via InMemoryShopRepository, DynamoDB, Cloudflare KV, Deno KV, or SQLite
• Resolving Context (shop + payload + HttpClient) from POST/GET requests
• Using HttpClient to query the Shopware Admin API with OAuth2 auto-refresh
• Building type-safe Criteria for Admin API searches
• Using createNotificationResponse, createNewTabResponse, createModalResponse
• Wiring lifecycle hooks: onAuthorize / onAppInstall / onAppActivate / onAppDeactivate / onAppUpdate / onAppUninstall
• Setting up Hono integration with configureAppServer
• Uploading media files or sending admin notifications programmatically

Reference Files

File	Content
references/deep/01-overview.md	Package metadata, runtime support, export map, bootstrap pattern
references/deep/02-registration.md	AppServer, Configuration, Registration class, full handshake flow
references/deep/03-shop-repository.md	ShopInterface, ShopRepositoryInterface, all storage adapters
references/deep/04-authentication.md	WebCryptoHmacSigner, DualSignatureVerifier, signature mechanics
references/deep/05-context-resolver.md	ContextResolver.fromAPI / fromBrowser, Context class
references/deep/06-http-client.md	HttpClient, token cache, error classes
references/deep/07-hooks.md	Hooks class, all event classes, lifecycle flow
references/deep/08-helpers.md	Criteria, admin-api helpers, app-actions, media, notification
references/deep/09-integrations.md	Hono configureAppServer, all storage integrations
references/deep/10-types.md	All exported types (BrowserAppModuleRequest, ActionButtonRequest …)

Quick Bootstrap (Hono + Bun)

import { AppServer, InMemoryShopRepository } from "@shopware-ag/app-server-sdk";
import { configureAppServer } from "@shopware-ag/app-server-sdk/integration/hono";
import { Hono } from "hono";

const app = new Hono();

configureAppServer(app, {
    appName: "MyApp",
    appSecret: "my-secret",
    shopRepository: new InMemoryShopRepository(),
    authorizeCallbackUrl: "https://app.example.com/app/register/confirm",
});

// Custom webhook handler
app.post("/app/webhook/order-placed", async (c) => {
    const ctx = c.get("context");   // Context<SimpleShop, { source, data, meta }>
    const shop = c.get("shop");
    // use ctx.httpClient to call shop API
    return c.json({ success: true });
});

export default app;