Develop a Custom App with AI

This guide has two parts: a short guide for the person building the app, followed by standalone instructions to give your AI coding agent.

Part 1: For the person building the app

What you need to know before starting

A Custom App is a reusable widget for Wallboard content. You decide what it displays, how it behaves, and which settings a content editor can change. Your AI agent builds it using the official Wallboard framework; the finished app is then installed and used in your customer account.

Use an AI coding workspace that can read and write project files, run Git and the required Node.js/npm commands, build the app, open a browser, and return its files. Wallboard MCP must already be connected. An MCP connection alone does not provide that development workspace. This article assumes those capabilities are available; to set up the MCP connection, see Connect an AI assistant (MCP).

Recommended AI tools

We recommend Claude Code from Anthropic or Codex from OpenAI / ChatGPT for this workflow. You can also use other AI coding tools that support MCP.

Support and responsibility

Custom App development and troubleshooting are not included in standard Wallboard support. If you build an app yourself, you are responsible for its behavior and compatibility; Wallboard is not responsible for issues caused by your code or other factors outside its control. Development and troubleshooting assistance is available only as paid support.

If you prefer not to build the app yourself, our Services team can deliver it as a paid development project, covering planning, design, implementation, testing, and handover. Contact [email protected] to discuss an end-to-end development project.

What you provide and decide

Give the agent a clear brief covering:

• What the app should display or do, its audience, and visual references
• Intended display sizes, orientations, devices, and interactions
• The data it should use, a synthetic sample, and the settings editors should control
• What should happen when data is missing, empty, invalid, or unavailable
• Whether this is a new app or an update; for an update, provide the existing source and explain what must remain compatible

Provide only assets and data you are permitted to use. Keep credentials and customer records out of prompts and sample files. Resolve decisions that materially affect the result before the agent starts major implementation.

From your brief to an app in content

1. Give the agent Part 2 and your brief. Let it retrieve the current project guidance and explain its approach before building.
2. Review the app. Check its appearance at the intended sizes, editable settings, data changes, failure states, and interactions. Ask what was tested and what still needs checking on the actual players.
3. Receive the files. The agent should return an accepted app ZIP for installation, a separate source ZIP for maintenance, and validation evidence. The source ZIP is not the file to upload as the app.
4. Approve and install. Confirm the server, customer, app, package, and proposed changes before any upload, replacement, enablement, datasource, or content change. In the intended Wallboard customer, use Settings → Apps to upload the accepted app ZIP and enable the app. Have someone with the required access perform the action — the Administrator role, on the Business or Enterprise package. If the menu or action is unavailable, verify the target environment and your access rather than inventing another upload route. The agent may do this only if it has a verified supported upload capability and your approval.
5. Find and configure the widget. Open the content designer, find the enabled app in the widgets sidebar under its assigned category, and add an instance to your content. Change its exposed settings and select or bind the required data separately; installing the app does not configure its data automatically.
6. Validate in use. Preview the content, test on representative target devices, and approve the intended content changes before putting them into use. Keep the source and a known-good package, especially when replacing an app used by existing content.

A request to build an app is not approval to change Wallboard. A successful local preview is not proof that the app works on the target players. If the agent cannot upload through a supported route, use the returned accepted package in the customer-admin workflow; do not substitute a media-library upload.

Copy the instructions for your AI

Copy all of Part 2, including its public links and packaging section, into your coding agent. Add your brief and any existing source archive. Part 2 contains its own context, so you do not need to include Part 1. Keep the agent's source, package, and validation evidence together for later changes.

Part 2: Instructions for your AI coding agent

Context

I want to build a Custom App widget for the Wallboard digital signage platform. Help me turn the app idea described below into a working, tested, correctly packaged Wallboard Custom App using the official framework. This is a widget that users add to content in the Wallboard editor, configure through its settings, and run on Wallboard players; it is not a standalone website or an HTML bundle. The Wallboard MCP connection is already available. Use it to discover current platform guidance and capabilities, and use the project workspace to implement and validate the app.

You are the AI coding agent building or updating a Wallboard Custom App widget for the user. Use the following instructions as your working context. Develop within the official framework, verify the result, and return maintainable source and an accepted installable package. Do not deploy or change Wallboard merely because the user requested development.

Your task and the user's brief

Use the user's supplied brief to establish the following. Ask about missing decisions that materially affect implementation or an update's compatibility; make minor assumptions explicit.

Goal: [what the app should display or do]
Audience and visual direction: [audience, references, branding, viewing distance]
Target placements: [sizes, orientations, devices, interaction]
Data and controls: [data source, synthetic sample, editable settings]
Required behavior: [timing, navigation, outputs, failure states]
Change type: [new app or existing app to update]
Existing project and permitted assets: [source archive, compatibility constraints, files]

Establish your workspace and source baseline

Wallboard MCP is assumed to be connected. Inspect the capabilities actually available to you. You also need source-file access, a shell, Git, the Node.js/npm tooling required by the checked-out project, repository and dependency access, a browser for validation, and a way to return generated files. MCP does not supply those local capabilities automatically, and a local file path is not automatically readable by a remote MCP server.

For a new app, start from the official Custom App boilerplate. For an update, start from the supplied app source archive and its matching instructions, dependencies, lockfile, brief, and delivery evidence. Do not silently replace that baseline with a newer scaffold.

Read full relevant documents and the installed SDK declarations or source when you need exact interfaces. Distinguish implementation guidance from platform-management contracts. Derive commands, schemas, APIs, and package rules from the current sources; do not invent them or rely on remembered versions.

App model and framework boundaries

A Custom App is a reusable application packaged as a configurable widget inside Wallboard content. The app package contains its implementation and editor configuration. A widget instance is one placement of that app, with its own settings and data bindings. A content editor should be able to use the controls you expose without editing the app's source.

The official boilerplate integrates a SolidJS application with the Wallboard SDK, which manages the widget inside the editor and player. Follow the architecture in the checked-out project rather than replacing it with a generic web-app scaffold.

Keep these responsibilities distinct:

• Runtime: the interface and behavior shown inside the widget's assigned area
• Editor configuration: the controls and optional editing interfaces used to configure an instance
• Data integration: the contract for the data the app consumes or produces, including bindings and failure states
• Platform management: installing and enabling the package, managing its customer-owned record, and using it in content

This workflow uses the official Custom App widget framework. A standalone website, generic HTML export, or the separate HTML bundle workflow is not a substitute for that framework's package contract.

Retrieve the instructions before implementing

The sources below have different jobs. Read them together; do not assume the MCP documentation contains the complete source-level development contract.

Source	What to obtain
Connected Wallboard MCP	Available guidance and documentation, authenticated environment and customer context, supported management capabilities, and current API contracts when needed
Official Custom App boilerplate	Project instructions, framework architecture, configuration and data contracts, maintained examples, development setup, validation, and delivery workflow
Custom Apps API documentation	The published customer-owned app management contract; verify that the target environment actually supports the required operations
Installed SDK declarations and source	Exact interfaces and signatures not fully described in project prose; restore the declared dependencies before inspecting them
User's brief and existing project	Intended behavior, visual requirements, permitted data and assets, target devices, and compatibility constraints for an update

Start with discovery

1. Inspect the tools actually exposed by the connected MCP. If the Custom App development guide tool (custom_app_guide) is available, request its complete guidance using the exposed schema (section: "all" in the current tool), including its workflow, checklist, and pitfalls. Its overview alone is not the framework manual.
2. Open the official boilerplate. Read AGENTS.md and README.md, then the framework documentation relevant to the requested settings, data, interactions, assets, testing, and delivery. Read complete relevant sections rather than relying on search snippets.
3. For an existing app, start with its source archive: read its matching README, agent instructions, framework docs, dependency declarations and lockfile, plus the supplied brief, data contract, and delivery manifest. Use those as the project baseline before consulting newer public instructions; do not silently upgrade it or mix scaffold revisions.
4. Derive current setup requirements, commands, SDK interfaces, schemas, package rules, and deployment operations from those sources. This article intentionally does not duplicate their changing values.
5. Reconcile conflicting instructions before relying on them. Use the checked-out project as the implementation baseline and the target environment's advertised tools and verified API support as deployment evidence. Do not copy an older command or assume every documentation source is synchronized.
6. Before coding, state the app's approach, sources consulted, and any missing decisions that would materially change the result.

Use MCP for documentation and authorized access to Wallboard; use the development environment for source files, builds, previews, and local tests. A local file path is not automatically readable by a remote MCP server.

If a source or capability is unavailable

Use the official repository and public documentation through an available supported route. If MCP documentation search only returns excerpts or does not cover customer app management, open the relevant full document or the public Custom Apps API reference linked above. Do not infer a tool's availability from a guide or invent an SDK call, endpoint, or transfer method. If a required contract still cannot be verified, identify the missing information and pause that part of the work. Continue only the independent work supported by the sources you can read.

Turn the request into an implementation brief

Resolve these decisions with the user before major implementation:

• Purpose and presentation: what the app should communicate, its audience, visual references, branding, and reading distance
• Placement: intended sizes, orientations, target devices, and whether interaction is required
• Data: where it comes from, its structure and ownership, refresh behavior, and what to show when it is unbound, empty, invalid, or unavailable
• Configuration: what content editors should control, sensible defaults, and which choices belong to shared data rather than per-instance settings
• Behavior: navigation, timing, transitions, input actions, and any proposed writes or external effects
• Change type: a new app or an update to an existing app, including settings and content that must remain compatible

Record the agreed decisions using the current repository's brief and validation mechanism. Ask about material ambiguity; make minor assumptions explicit. Use synthetic data with representative edge cases. Keep credentials, private operational data, and unnecessary personal information out of the source, prompts, fixtures, and distributable files.

Build within the framework

Implement the app-owned parts while preserving the scaffold's platform integration, lifecycle, validators, and delivery tooling. Follow the repository's boundaries for protected files and supported extensions. Do not bypass a failed check by weakening the framework or claiming evidence you did not obtain.

Keep the whole settings flow consistent: an editor control defines a value, the instance stores it, the app validates and normalizes it, and the runtime renders it. A control is complete only when changing it has the intended visible effect. Use the framework's supported reactive mechanisms so later settings and datasource updates reach the display.

Keep instance state isolated. Multiple placements must not overwrite one another's settings or DOM state. Release timers, listeners, subscriptions, and other owned resources when an instance is removed.

Treat data binding and app installation as separate concerns. Establish the expected data contract and use the documented integration path. Do not assume that uploading a package creates, selects, or binds the required datasources. A custom editor is an optional editing interface, not a place to hide credentials or introduce an undocumented storage mechanism.

Before adding a capability, look for the matching current framework guidance or maintained example. Verify packaged resources, media behavior, and device compatibility through the supported workflow rather than relying on a successful desktop preview.

Validate the result and report the evidence

Run the checks required by the current project and inspect the actual rendered output. At minimum, cover the relevant cases below:

• Defaults, editable controls, saved values, and live settings changes
• Bound and unbound data, empty or malformed input, long text, and live data changes
• Intended sizes and orientations, readable typography, and missing or failed media
• Interactions, timing, multiple instances, cleanup, and sustained playback
• Packaged asset loading, network-dependent behavior, and recovery from expected failures
• Installation and behavior in Wallboard content, followed by representative target-player tests

A successful build is one check. It does not establish visual quality, correct bindings, or device compatibility. Review screenshots you actually generated, and record which environments and behaviors were tested. If a browser or target device is unavailable, name the missing checks. A browserless handoff is unverified and must not be called upload-ready; target-device testing remains a separate requirement.

Package the app correctly

Use the checked-out boilerplate's delivery and identity instructions. Use its maintained workflow to build, validate, and create the archives. Do not ZIP the whole project or invent a packaging script. The supported delivery entry point in the current scaffold is:

npm run deliver -- <output-directory>

Confirm that command against the project instructions before running it. A normal accepted delivery produces an app ZIP, a separate source ZIP, and evidence files. Upload the app ZIP identified by app.zipFile in delivery-manifest.json. Keep the source ZIP for maintenance. The source archive preserves the project instructions and framework documentation included in that project; the runtime app ZIP is not a developer-documentation bundle. Installed dependencies such as node_modules are excluded and must be restored using the project's dependency declarations and lockfile.

App ZIP structure

For this Custom App widget scaffold, the ZIP contains the contents of the built dist/ directory at its root:

assets/
  app.js
  app-chrome-49.js
editor-assets/
  config.json
  icon.png
  placeholder.png

Additional generated runtime assets belong under their emitted paths. Referenced custom editors and datasource files are included by the build when applicable. The tree above shows the required baseline, not permission to omit other generated files.

The source file src/editor-assets/properties.json is transformed into editor-assets/config.json. Do not upload the source configuration as a substitute, move the built configuration to the ZIP root, or add a generic index.html to imitate an HTML bundle.

Avoid the nested-folder trap

The archive must open directly to assets/ and editor-assets/. Paths such as dist/editor-assets/config.json or my-project/dist/editor-assets/config.json mean an extra enclosing directory was included. Do not upload the repository ZIP, _source.zip, the whole delivery folder, or an _UNVERIFIED package as an accepted app.

Inspect the finished archive before uploading

• List and integrity-test the actual ZIP, for example with unzip -l and unzip -t or equivalent archive tools; confirm the root structure above
• Check that the built configuration is valid JSON and its name and version agree with the delivery manifest and intended installation
• Confirm that the required scripts and real PNG images are present; check that resourceList covers every emitted runtime asset and that each entry resolves to the expected relative path inside the ZIP
• Check that generated media, fonts, workers, custom editor files, and datasource assets needed by the app were included
• Confirm that source files, dependencies, credentials, and delivery sidecars were not accidentally added to the runtime ZIP
• Verify the delivery's acceptance result; a normal upload-ready delivery records acceptance.status: "accepted" and acceptance.uploadReady: true

The normal package checks validate the build output before compression. The archive review above is an additional check of the final file; do not assume those earlier checks reopened and tested the ZIP.

The manifest, generation brief, and visual-review record stay beside the ZIPs as delivery evidence. Do not manually add them to the runtime package. If inspection or validation fails, correct the source or build and regenerate the delivery instead of patching the ZIP by hand.

Deploy with approval and preserve compatibility

Verify the authenticated identity, target server and customer, advertised app-management capabilities, and permissions before proposing a deployment. Do not infer access or server support from this article, a tool name, or another environment.

Before changing Wallboard, show the user the target server and customer, the new or existing app, the package, and the intended upload, replacement, enablement, data, or content changes. Obtain approval for those actions. A request to develop an app does not authorize deployment or changes to existing content.

Updates and identity constraints

For an update, inspect the installed app, its source and package, existing placements, and the current identity and compatibility rules before changing anything. The catalog display name is separate from the package's internal name and version; verify their exact types and accepted values in the checked-out project and target contract.

Keep the internal identity for a compatible replacement. Check the customer's effective catalog for identity conflicts. A new or incompatible identity must be planned as a distinct installation; changing it does not migrate existing widget instances automatically. Replacing a shared app can affect every placement that uses it. Preserve compatible settings and bindings, retain a known-good package and source, and agree on any migration explicitly.

Discover the currently supported upload method and confirm that the process performing it can access the package bytes. A generic media-file upload tool or JSON-only write tool is not evidence that app-package upload is supported. If automation is unavailable, hand over the accepted package for the supported customer-admin upload workflow. Verify the resulting installed state, required bindings, and content behavior after an authorized deployment. Do not report success merely because an upload was attempted.

Return the handoff and respect support boundaries

Return the source project and source ZIP, the accepted app ZIP identified by the delivery manifest, the manifest and review evidence, inspected screenshots, required data and binding setup, and a short report separating completed checks from remaining target-device tests. Keep source, runtime package, and delivery sidecars distinguishable. Report verified installed state only after an authorized deployment; otherwise identify the supported next step for the user.

Custom App development and troubleshooting assistance is paid support, outside standard Wallboard support. The user is responsible for their app's behavior and compatibility; Wallboard is not responsible for issues caused by custom code or factors outside its control. Do not promise free Custom App development or troubleshooting, and do not confuse these boundaries with ordinary Wallboard product support. For a commissioned end-to-end development project, the Services team offers paid planning, design, implementation, testing, and handover; the contact is [email protected]. Do not invent fees, service levels, or guarantees.