Connect an Edge machine to an app - Stardeck Documentation

Pairing an Edge machine connects it to your organization. Granting controls which apps in that organization may use it.

Grant the machine

Open the app's integrations

Open the app in Stardeck, go to Settings, and select Integrations.

Grant an Edge machine

Under Edge Devices, choose the paired machine and select Grant.Only machines in the same organization are available.

Choose a default

If the app can use more than one Edge machine, select the star beside the machine it should use by default.The default is used when the app sends a job without naming a particular machine or printer.

You can grant the same Edge machine to multiple apps. Removing a grant stops only that app from using it; the machine remains paired to your organization.

Pair a printer alias

An alias is a stable role used by the app, such as front-counter, kitchen, or customer-receipt. The alias points to a physical printer. This lets you replace a printer later without changing app code.

Open Printer Pairings

In the app’s Settings → Integrations, find Printer Pairings.

Enter an alias

Use lowercase letters, numbers, hyphens, or underscores. Keep the name tied to the printer’s job, not its model.

Choose the physical printer

Select a configured printer on one of the machines granted to this app, then select Pair.

Test the app flow

Run the app action that prints to this alias and confirm the job reaches the expected printer.

If hardware is removed or the machine grant is revoked, Stardeck keeps the alias and marks it as broken. Re-pair the alias to restore the app without rebuilding it.

Customize receipt branding

Under Receipt Branding in the same app settings:

upload a PNG, JPEG, or WebP logo
review the exact black-and-white print preview
replace or remove the current logo
turn the Powered by Stardeck footer mark on or off

Simple, high-contrast artwork prints best. Stardeck converts the image to a one-color thermal printer format before storing it.

Ask the agent to build an Edge feature

Once the grant exists, describe the behavior you want in the app’s project chat:

Print a receipt on the front-counter printer after a successful cash payment,
then open the attached cash drawer.

The agent uses the Edge SDK and the granted connection automatically. Tell it which alias to use if the app has more than one printer role.

For developers

Server-side app code can use @stardeck-customer-apps/edge-sdk. Stardeck injects the required connection settings into sandboxes and deployments, so no device secret needs to be copied into the app.

import { createEdgeClient } from "@stardeck-customer-apps/edge-sdk/server";

const edge = createEdgeClient();

await edge.print({
  alias: "front-counter",
  receipt: {
    header: { lines: ["My Shop"] },
    items: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }],
    total: 80,
    footer: { lines: ["Thank you"] },
  },
  openDrawer: true,
});

Use listPeripherals() and testPrint() to build an in-app pairing screen for location staff. Handle offline and broken-binding errors by showing a retry or re-pairing action instead of a generic failure.

Control the receipt layout

For alignment, bold, text size, rules, spacing, or a different section order, send an ordered list of blocks instead of the fixed fields:

await edge.print({
  alias: "front-counter",
  receipt: {
    blocks: [
      { type: "text", text: "MY SHOP", align: "center", bold: true, size: "large" },
      { type: "separator" },
      { type: "items", rows: [{ name: "Coffee", quantity: 1, unitPrice: 80, total: 80 }] },
      { type: "separator" },
      { type: "columns", left: "TOTAL", right: "80.00", bold: true, size: "large" },
      { type: "barcode", format: "qr", data: "https://example.com/r/1234", widthPercent: 50 },
    ],
  },
});

Available blocks: text, columns, separator, spacer, items, and barcode. Set paperWidth on the receipt to lay out for 58mm or 80mm regardless of the printer. A QR prints at the printer’s default size unless the block sets widthPercent (5–100), the share of the paper width it should take. The printed width is quantised to whole dots per cell and rounded down, so the code lands on the nearest size at or below the request — and the preview draws that size, not the request. More data means a denser symbol at the same width, so shorten a long URL rather than shrinking the code further.

Show an accurate preview in the app

getCapabilities() reports what the target printer can do — paper width and characters per line, whether text prints as characters or as an image, Thai and Unicode coverage, supported barcodes, cutter, and cash drawer. renderReceiptPreviewHtml() lays the receipt out with the same code the printer uses, so an on-screen preview matches the paper.

import { renderReceiptPreviewHtml } from "@stardeck-customer-apps/edge-sdk";

const capabilities = await edge.getCapabilities({ alias: "front-counter" });
const html = renderReceiptPreviewHtml(receipt, capabilities, { widthPx: 320 });

Capabilities are available even when the machine is offline, so previews keep working while the hardware is down.

Set up an Edge display

Show a fixed page or let the app change a screen live.

​Grant the machine

​Pair a printer alias

​Customize receipt branding

​Ask the agent to build an Edge feature

​For developers

​Control the receipt layout

​Show an accurate preview in the app