This guide will show the anatomy of a FrontPanel application project. A typical FrontPanel application is built using common tools such as Webpack, Typescript and the React user interface development library.

FrontPanel Apps are built as Node.js projects. The project will be used to contain all of the sources and additional assets required. Once complete, the project will then create a deployable application package similar to how many web apps are created and deployed. Instead of deploying to a cloud host, the package will be executed by the FrontPanel Platform.

A typical FrontPanel app project has the following structure:

my-frontpanel-app/
├── .vscode/
│   ├── launch.json
│   ├── tasks.json
├── assets/
│   ├── bitfiles/
│   │   ├── XEM8320-AU25P
│   │   │   └──*.bit
│   │   └── ...
│   ├── favicon.ico
│   ├── frontpanel-app-icon.svg
│   └── ...
├── scripts/
│   └── package-fpapp.js
├── src/
│   ├── index.html
│   ├── index.tsx
│   ├── index.css
│   ├── App.tsx
│   ├── App.css
│   └── declarations.d.ts
│   └── ...
├── frontpanel-app.json
├── APP-INFO.md
├── package.json
├── tsconfig.json
├── webpack.common.js
├── webpack.dev.js
└── webpack.prod.js

The sections below cover each part in detail.

The src/ directory contains your application code and follows standard React and TypeScript conventions.

• index.html — The HTML entry point loaded by the FrontPanel Platform.
• index.tsx — The React entry point that mounts the <App /> component.
• index.css — Base/global styles applied across the app.
• App.tsx — The root React component, where device logic and top-level UI typically live.
• App.css — Styles scoped to the App component.
• declarations.d.ts — TypeScript ambient module declarations for non-code imports (e.g. *.png), so assets can be imported directly into TypeScript source.

For details on using the FrontPanel Platform API within your application, see the API documentation.

FrontPanel apps specify the information to display in the app info dialog in an APP-INFO.md file located at the root of the project. This information typically includes content such as an application description, usage instructions, version history, compatibility information, etc. The FrontPanel App Launcher presents this information in an app info dialog.

Note: The contents of this file is formatted using markdown.

Your application description goes here. This file is bundled with your app and
displayed in the FrontPanel Platform launcher.

## Usage

Describe how to use your application.

## Version History

* 1.0.0
  * Initial release of FrontPanel Platform app.Code language: Markdown (markdown)

The APP-INFO.md file needs to be included in the final application package that is installed in the app launcher, and must be located in the assets/text directory within the built package. (assets/text/APP-INFO.md)

In order to package the APP-INFO.md file in the assets/text directory of the package, a step in the webpack.common.js file is specified to copy the file from the source location and place it in the proper location in the app package.

    new CopyWebpackPlugin({
      patterns: [
        { from: 'frontpanel-app.json', to: 'frontpanel-app.json' },
        { from: 'APP-INFO.md', to: 'assets/text' },
        { from: 'assets/frontpanel-app-icon.svg', to: 'assets/images' }
      ],
    }),
Code language: CSS (css)

This step ensures the npm run pack command will produce the app.fpp package with this file included. When this app is installed in the launcher, displaying the application information for the app will display the contents of the APP-INFO.md file.

FrontPanel Platform apps are designed to share basic information with the App Launcher for both presentation and practical purposes. This information is provided in the app bundle in the form of a JSON file such as the one below:

{
    "appGuid": "f201a5d2-75fa-4762-a2d3-13a840756670",
    "name": "Counters",
    "version": "1.0.0",
    "author": "Opal Kelly Incorporated",
    "summary": "Basic example with counting LEDs and virtual instrument control.",
    "icon": { "source": "assets/images/counters-app-logo.svg" },
    "permissions": { },
    "compatibleDevices": [
        "XEM8320-AU25P",
        "XEM8310-AU25P",
        "SZG-HUB1450-AU10P"
    ],
    "initialContentSize": {
        "width": 660,
        "height": 420
    }
}
Code language: JSON / JSON with Comments (json)

• appGuid – A string containing a UUID to identify the app. This should be unique to each FrontPanel Platform App, but you should keep this UUID the same for different releases (or versions) of the app.
• name – The name of the app as it will be shown in the app card on the launcher.
• version – Basic version string. We recommend a common format: major, minor, sub-minor.
• author – The name of the individual or organization that authored the app.
• summary – The summary should be brief (e.g. one sentence) so that it fits neatly within the app card in the launcher.
• icon – A resource for the application icon SVG with a square aspect ratio. This is shown in the application launcher.
• permissions – Set of requested permissions for your app within the Platform.
  • network – Set to true if your application needs HTTP, HTTPS, or WebSocket access to external servers.
• compatibleDevices (FP6.1+) – A list of compatible device names. If this isn’t specified, the platform will attempt to infer a list based on the bitfiles in the assets folder.
• initialContentSize – The default size of the app window when launched from the app launcher as specified by a key/value pair.

The assets/ folder holds static files bundled with your app, such as the application icon, favicon, images, fonts, and FPGA bitfiles.

Our sample applications place FPGA bitfiles under assets/bitfiles/, organized into subfolders named after the target product (for example XEM8320-AU25P/, XEM7310-A75/).

Note: Files under assets/ aren’t packaged automatically, webpack copies them into dist/ based on the rules in webpack.common.js.

This script bundles the contents of the dist/ directory into a .fpp zip archive. It is invoked by the npm run pack and npm run pack:dev scripts.

You generally don’t need to modify this file.

The scripts section of package.json defines the commands used to build and package your app. The four most relevant to FrontPanel app development are:

  "pack:dev": "webpack --config webpack.dev.js && node ./scripts/package-fpapp.js ./dist ./output/app-dev.fpp",
  "pack": "webpack --config webpack.prod.js && node ./scripts/package-fpapp.js ./dist ./output/app.fpp",
  "build:dev": "webpack --config webpack.dev.js",
  "build": "webpack --config webpack.prod.js"
Code language: JavaScript (javascript)

• pack:dev — Runs build:dev, then packages dist/ into output/app-dev.fpp.
• pack — Runs build, then invokes scripts/package-fpapp.js to zip dist/ into output/app.fpp.
• build:dev — Runs webpack with the development configuration (includes source maps) to dist/.
• build — Runs webpack with the production configuration, emitting the built app to dist/.

The build is split across three webpack configuration files

• webpack.common.js — Shared configuration used by both development and production builds.
• webpack.dev.js — Produces an unminified build with inline source maps for debugging.
• webpack.prod.js — Enables webpack’s built-in optimizations such as minification and tree-shaking for a smaller, distribution-ready build.

• TypeScript | webpack
• Output Management | webpack
• Asset Management | webpack
• Production | webpack

The .vscode/tasks.json file defines a set of tasks that speed up the build-and-test cycle by letting you package and launch your app from within VSCode. Run any task through the command palette (Ctrl+Shift+P / Cmd+Shift+P) with Tasks: Run Task.

The following tasks are provided:

• Package FrontPanel App (production) — runs npm run pack.
• Package FrontPanel App (development) — runs npm run pack:dev.
• Launch FrontPanel App (production) — starts the FrontPanel Platform with output/app.fpp loaded.
• Launch FrontPanel App (development) — starts the FrontPanel Platform with output/app-dev.fpp loaded.
• Package and Launch FrontPanel App (production) — runs the Package and Launch production tasks in sequence.
• Package and Launch FrontPanel App (development) — runs the Package and Launch development tasks in sequence.

The Launch tasks start the Platform with remote debugging hosted on port 9222, allowing Chrome DevTools to be attached for debugging.

Note: On macOS, the Launch tasks assume FrontPanel Platform is installed at /Applications/FrontPanel Platform.app. This can be done by dragging and dropping the FrontPanel Platform icon to the /Applications/ folder. If you installed it elsewhere, update the osx.command path in tasks.json.

When you run npm run pack (or npm run pack:dev), the pieces described above come together as follows:

1. Webpack compiles the TypeScript sources, bundles them with their dependencies, processes imported CSS and assets, and emits all of the resulting application files into the dist/ directory — including the supporting files (frontpanel-app.json, APP-INFO.md, and the app icon) copied in by CopyWebpackPlugin.
2. The packaging script (scripts/package-fpapp.js) zips the contents of dist/ into a .fpp archive and writes to the output/ directory.
3. The FrontPanel Platform loads the .fpp package, reads frontpanel-app.json for metadata, runs the app.

For next steps, see:

• Building with NPM Create — Build and run your first FrontPanel app.
• Work Queue — Manage single-threaded device communication in an asynchronous environment.
• Debug with Chrome DevTools — Debug live apps using the built-in developer tools.