GitHub - Screenly/airtable-app: Display Airtable data on your Screenly digital signage screens

Displays data from an Airtable base on your Screenly digital signage screens.

Prerequisites

Bun 1.2+
Screenly CLI
An Airtable account with at least one base

Getting Started

Clone the repository and install dependencies:

gh repo clone Screenly/airtable-app -- --recurse-submodules
bun install

Development

This generates a mock-data.yml file (gitignored), starts the dev server, and starts a local CORS proxy on http://127.0.0.1:8080.

For local development without depending on the Screenly backend, use the mock-server. It simulates the Screenly OAuth service by running a local Authorization Code + PKCE flow against Airtable and serving the resulting tokens to the Edge App.

After mock-data.yml is generated, fill in your values under settings:

settings:
  base_id: '<your Airtable base ID>'
  display_errors: 'false'
  override_locale: ''
  override_timezone: ''
  refresh_interval: '30'
  screenly_oauth_tokens_url: 'http://localhost:3000/'
  view_id: '<your Airtable view ID>'

Building

Type Checking

Linting & Formatting

bun run lint
bun run format

Testing

Screenshots

Deployment

screenly edge-app create --name airtable-app --in-place
bun run deploy
screenly edge-app instance create

Configuration

Setting	Type	Required	Description
`access_token`	secret	No	For testing only. In production, the access token is fetched dynamically via the Screenly OAuth service.
`base_id`	string	Yes	Airtable base. Selected via dropdown in the Screenly dashboard.
`display_errors`	string	No	Display errors on screen for debugging (`true`/`false`). Default: `false`
`override_locale`	string	No	Override the locale for date formatting (e.g. `en-US`, `fr`). Defaults to GPS-based detection.
`override_timezone`	string	No	Override the timezone for date formatting (e.g. `America/New_York`). Defaults to GPS-based detection.
`refresh_interval`	string	No	How often (in seconds) to refresh Airtable data. Default: `30`
`view_id`	string	Yes	Airtable view. Selected via dropdown in the Screenly dashboard. Supports grid and kanban views.

Limitations

A maximum of 100 records are fetched per refresh. Tables with more than 100 records will be truncated.

Authentication

This app uses the Screenly OAuth service to obtain an Airtable access token at runtime. For local development, the mock-server acts as a stand-in for that service.

Finding Your IDs (Local Development)

When running locally, base_id and view_id must be set manually. Navigate to your view in Airtable. Both IDs are present in the URL:

https://airtable.com/appXXXXXXXXXXXXXX/tblXXXXXXXXXXXXXX/viwXXXXXXXXXXXXXX
                     ^^^^^^^^^^^^^^^^^^                     ^^^^^^^^^^^^^^^^^^
                     Base ID                                View ID

Prefix	Entity
`app`	Base
`viw`	View