Copy page

Core Concepts

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:

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

Complete Manifest Example

Code
{
  "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.

Code
"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.

Code
"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.

Code
"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.

Code
"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.

Code
"distribution_type": "public"

Values:

• "private": Only your organization can install (default)
• "public": Listed in marketplace for all organizations

UI Extension

ui_extension (object, optional)

Defines where and how your app displays in the platform.

views (array)

List of views your app provides.

Code
"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)

permissions_policy (object)

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

Code
"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.

Code
"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

Post-Install Action

post_install_action (object)

Defines what happens after a user installs your app.

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

Type: Settings Redirect to app settings page:

Code
{
  "type": "settings"
}

Type: External Redirect to external URL:

Code
{
  "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

• Must match known viewport patterns
• See Viewports documentation

Manual Validation

The manifest is automatically validated when you run:

Code
teachfloor apps start
# or
teachfloor apps upload

Managing Manifests

Updating Metadata

Via CLI Commands

Update distribution type:

Code
teachfloor apps set distribution

Add permission:

Code
teachfloor apps grant permission

Remove permission:

Code
teachfloor apps revoke permission

Add view:

Code
teachfloor apps add view

Remove view:

Code
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.

Multi-Environment Manifests

Use different manifests for development and production:

Development (teachfloor-app.dev.json):

Code
{
  "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):

Code
{
  "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:

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

Next Steps

→ Continue to Viewports System

Additional Resources

• Best Practices - Naming, descriptions, permissions, and versioning guidelines
• Troubleshooting Guide - Common manifest errors and solutions
• Examples - Complete manifest examples
• Permissions Reference
• CLI Commands