@lexoraxiom/appscreenz-sdk

Browser helpers (TypeScript), a Node API to write screenshots for sync, and the appscreenz CLI.

Install

npm install @lexoraxiom/appscreenz-sdk

Published installs include built output under dist/node/ for @lexoraxiom/appscreenz-sdk/node (no post-install build). If you depend on a git checkout of this repo, run pnpm run build in packages/sdk first.

Imports

• @lexoraxiom/appscreenz-sdk — browser-only APIs, shipped as TypeScript. Use from a bundler (e.g. Vite, Next.js) with your usual TS setup. Not intended for plain Node without a TS loader.
• @lexoraxiom/appscreenz-sdk/node — compiled ESM + types. Use from Node to write PNGs and manifest.json where the CLI expects them.

import { writeScreenshotsToAppscreenzOutput } from '@lexoraxiom/appscreenz-sdk/node';

await writeScreenshotsToAppscreenzOutput({
  clean: true,
  screenshots: [
    {
      fileName: 'home-ios.png',
      data: pngBuffer,
      id: 'home',
      label: 'Home',
      platform: 'ios',
    },
  ],
});

Defaults: rootDir is process.cwd(); output goes to .appscreenz/screenshots under that root. With clean: true, existing *.png and manifest.json in that folder are removed first.

You can also generate those PNGs with the CLI (see below) or call runGenerateScreenshots from @lexoraxiom/appscreenz-sdk/node (same manifest format as writeScreenshotsToAppscreenzOutput).

CLI: init, generate, connect, sync

Local only (no Firebase)

From your project root, with the app already running at a known URL:

npm install -D @lexoraxiom/appscreenz-sdk
npx playwright install chromium
npx appscreenz init --url http://localhost:8081 --route / --route /paywall
npx appscreenz generate

• init creates .appscreenz/project.json and .appscreenz/screenshots/ (no manual folders). Requires --url and at least one --route. Use --force to overwrite an existing config.
• generate uses Playwright (Chromium) with fixed iPhone and Android viewports, full-page PNGs per route, and writes PNGs + manifest.json under the configured screenshots directory. generate does not use Firebase.

Optional: AppScreenz sync

After local screenshots exist, link the folder to a dashboard project and upload:

npx appscreenz connect --project <projectId>
npx appscreenz sync
npx appscreenz status

If you already ran init (or edited project.json), connect merges into that file: it keeps baseUrl and routes unless you pass --url or --route on connect to override or add paths.

Firebase configuration (connect, sync, and remote status only)

The CLI talks to your AppScreenz Firebase project (Firestore + Storage). Add a .env, .env.local, or apps/web/.env.local (searched upward) containing:

| Variable | Purpose | |----------|---------| | NEXT_PUBLIC_FIREBASE_API_KEY | | | NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | | | NEXT_PUBLIC_FIREBASE_PROJECT_ID | | | NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET | | | NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID | | | NEXT_PUBLIC_FIREBASE_APP_ID | | | NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID | Optional | | NEXT_PUBLIC_APPSCREENZ_ACCOUNT_ID | Optional; defaults to a demo id if omitted |

Use appscreenz connect --env /path/to/.env when the file is not in a default location.

Web vs native (generate)

generate runs Playwright Chromium against HTTP(S) URLs. It captures web pages (e.g. Next.js, Vite, Expo web). It does not capture native iOS/Android UI. For those, write PNGs with writeScreenshotsToAppscreenzOutput, then appscreenz sync if needed.

Use --dir on init, connect, or sync if screenshots should live somewhere other than .appscreenz/screenshots.

networkidle and SPAs

generate waits for networkidle after each navigation. Apps with long-lived connections (polling, WebSockets) may never reach idle on some routes; use simple, public routes for best results.

Config files

• .appscreenz/project.json — screenshotsDir, baseUrl, routes[], optional projectId / sourceId / accountId after connect, plus sync metadata when applicable.
• .appscreenz/screenshots/ — PNGs and manifest.json from generate or writeScreenshotsToAppscreenzOutput

Node API reference

| Export | Purpose | |--------|---------| | writeScreenshotsToAppscreenzOutput(options) | Creates the folder, optionally cleans, writes PNGs + manifest.json | | runGenerateScreenshots(options) | Playwright full-page capture per route × mobile preset; writes the same folder layout as above | | isLinkedToSaaS, mergeRoutes, normalizeBaseUrl, normalizeRoutePath, mergeGenerateConfigIntoProject, resolveScreenshotsRelativeDir, routePathToSlug | Helpers for .appscreenz/project.json | | MOBILE_VIEWPORT_PRESETS | Fixed iphone / android viewport sizes used by runGenerateScreenshots | | assertScreenshotBasenamePng(fileName) | Validates a safe basename (no paths or ..) | | DEFAULT_APPSCREENZ_SCREENSHOTS_RELATIVE_PATH | '.appscreenz/screenshots' |

Each screenshot item: fileName (basename, .png), data (Buffer / Uint8Array / base64), optional id, label, platform.

manifest.json (optional)

If present next to the PNGs, screens[] can list fileName, id, label, platform. If missing or invalid, sync still uploads PNGs and infers keys from filenames.

Browser entry (@lexoraxiom/appscreenz-sdk)

Includes DOM capture, PNG downscaling, data URL helpers, and promo-related helpers. Import names from this package in app code processed by your bundler.

Monorepo demo

From this repo’s packages/sdk:

pnpm run demo:write-output

Runs the example under examples/ (not shipped on npm).