APIWebhooksAppsTeachfloor.jsAPI ReferenceGo to Teachfloor

App Manifest

The app manifest (teachfloor-app.json) defines your app's metadata, capabilities, permissions, and behavior.

Overview

The manifest is a JSON file at the root of your project:

  • Defines app name, description, and version
  • Specifies where your app displays (viewports)
  • Declares required permissions
  • Sets distribution type (public/private)
  • Configures post-installation actions

Basic Structure

Here's a minimal manifest:

{
  "id": "abc123def456",
  "version": "1.0.0",
  "name": "My App",
  "description": "A simple Teachfloor app",
  "distribution_type": "private"
}

Complete Manifest Example 

{
  "id": "abc123def456",
  "version": "1.2.0",
  "name": "Course Notes",
  "description": "Take notes while browsing courses and modules",
  "distribution_type": "public",

  "ui_extension": {
    "views": [
      {
        "viewport": "teachfloor.dashboard.course.detail",
        "component": "CourseNotesView"
      },
      {
        "viewport": "teachfloor.dashboard.course.module.detail",
        "component": "ModuleNotesView"
      }
    ],
    "permissions_policy": {
      "microphone": ["http://localhost:3000"],
      "purpose": "Enable speech-to-text for note taking"
    }
  },

  "permissions": [
    {
      "permission": "user_read",
      "purpose": "Display your name and profile"
    },
    {
      "permission": "course_read",
      "purpose": "Display course information in notes"
    }
  ],

  "post_install_action": {
    "type": "settings",
    "url": "https://example.com/setup"
  }
}

Field Reference

Required Fields

id (string)

Unique identifier for your app. Auto-generated during app creation.

"id": "abc123def456"

Rules:

  • Must be unique across all Teachfloor apps
  • Cannot be changed after creation
  • Automatically generated by CLI

version (string)

Semantic version of your app following semver format.

"version": "1.2.3"

Rules:

  • Must follow MAJOR.MINOR.PATCH format
  • Examples: 1.0.0, 2.1.5, 0.5.0-beta
  • Increment when uploading new versions

Versioning Guidelines:

  • MAJOR: Breaking changes
  • MINOR: New features, backward compatible
  • PATCH: Bug fixes, backward compatible

name (string)

Display name shown to users in the marketplace and dashboard.

"name": "Course Notes"

Rules:

  • Maximum 50 characters
  • Should be descriptive and unique
  • Used in app listings and UI

description (string)

Short description of what your app does.

"description": "Take notes while browsing courses and modules"

Rules:

  • Maximum 200 characters
  • Should clearly explain the app's purpose
  • Displayed in marketplace listings

Distribution

distribution_type (string)

Determines how your app is distributed.

"distribution_type": "public"

Values:

  • "private": Only your organization can install (default)
  • "public": Listed in marketplace for all organizations
See Deployment Guide for detailed information on private vs public distribution.

UI Extension

ui_extension (object, optional)

Defines where and how your app displays in the platform.

The ui_extension field is optional. Apps without it can function as backend integrations listening to platform events.
views (array)

List of views your app provides.

"ui_extension": {
  "views": [
    {
      "viewport": "teachfloor.dashboard.course.list",
      "component": "CourseListView"
    },
    {
      "viewport": "teachfloor.dashboard.course.detail",
      "component": "CourseDetailView"
    }
  ]
}

View Object:

  • viewport (string): Where the view displays (must be an exact match to an available viewport)
  • component (string): React component name (must match filename without extension)
Viewports require exact string matches. Wildcard patterns are not supported. See Viewports System for available viewports.
permissions_policy (object)

Browser permissions your app needs (microphone, camera, etc.).

"ui_extension": {
  "permissions_policy": {
    "microphone": ["http://localhost:3000", "https://app.teachfloor.com"],
    "camera": ["http://localhost:3000"],
    "purpose": "Enable video recording for assignments"
  }
}

Available Permissions:

  • microphone: Audio input
  • camera: Video input
  • geolocation: Location access
  • clipboard-write: Clipboard access

Fields:

  • Permission name: Array of allowed origins
  • purpose: User-facing explanation (required)

Permissions

permissions (array)

Platform permissions your app needs to access Teachfloor resources.

"permissions": [
  {
    "permission": "course_read",
    "purpose": "Display course information in widgets"
  },
  {
    "permission": "user_events_read",
    "purpose": "Track learning progress"
  }
]

Permission Object:

  • permission (string): Permission identifier
  • purpose (string): User-facing explanation of why you need it

Important:

  • Only request permissions you actually use
  • Provide clear, user-facing explanations
  • Users see permission requests during installation
  • Write permissions (*_write) automatically include read access
See Permissions Reference for the complete list of available permissions, their descriptions, and permission hierarchy.

Post-Install Action

post_install_action (object)

Defines what happens after a user installs your app.

"post_install_action": {
  "type": "settings"
}

Type: Settings Redirect to app settings page: 

{
  "type": "settings"
}

Type: External Redirect to external URL: 

{
  "type": "external",
  "url": "https://example.com/setup?user=123"
}

Use Cases:

  • Configuration wizard
  • Account connection
  • Welcome tutorial
  • Feature introduction

Manifest Validation

The CLI automatically validates your manifest before upload.

Validation Rules

Required Fields

  • id, version, name must be present

Version Format

  • Must match semver pattern: ^\d+\.\d+\.\d+(-[\w.]+)?$
  • Valid: 1.0.0, 2.1.5, 1.0.0-beta.1
  • Invalid: 1.0, v1.0.0, 1.0.0.0

Component Names

  • Must be valid React component names
  • PascalCase only
  • Valid: MyView, CourseDetailView
  • Invalid: myView, my-view, my_view

Viewport Names

Manual Validation

The manifest is automatically validated when you run:

teachfloor apps start
# or
teachfloor apps upload

Managing Manifests

Updating Metadata

Via CLI Commands

Update distribution type:

teachfloor apps set distribution

Add permission:

teachfloor apps grant permission

Remove permission:

teachfloor apps revoke permission

Add view:

teachfloor apps add view

Remove view:

teachfloor apps remove view

Manual Editing

  1. Open teachfloor-app.json in your editor
  2. Make changes
  3. Save the file
  4. Run teachfloor apps start or teachfloor apps upload

The CLI will validate and upload the updated manifest.

Version Management

Once a version is published, it becomes locked and cannot be modified. To release updates, increment the version number and upload again.

See Deployment Guide for complete information on version states, semantic versioning, and deployment process.

Multi-Environment Manifests

Use different manifests for development and production:

Development (teachfloor-app.dev.json):

{
  "id": "abc123",
  "version": "1.0.0-dev",
  "name": "My App (Dev)",
  "distribution_type": "private",
  "ui_extension": {
    "permissions_policy": {
      "microphone": ["http://localhost:3000"]
    }
  }
}

Production (teachfloor-app.json):

{
  "id": "abc123",
  "version": "1.0.0",
  "name": "My App",
  "distribution_type": "public",
  "ui_extension": {
    "permissions_policy": {
      "microphone": ["https://app.teachfloor.com"]
    }
  }
}

Start with custom manifest:

teachfloor apps start --manifest teachfloor-app.dev.json

Next Steps

→ Continue to Viewports System

Additional Resources