App Manifest

An App Manifest tells Quip about the files & attributes of your application so it can be loaded and displayed.

id​

required

string

The ID of this application. This is generated automatically when running quip-cli init, or you can copy it from the application in the developer console.

name​

required

string

The name of this application - this is what will be displayed in the main menu to users and when inserting.

description​

required

string

A description of this application. It will be visible when inserting the application or viewing in various browse interfaces.

manifest_version​

required

integer

The version of the manifest format that this file is using. It will be set for you via quip-cli init.

version_name​

required

string

A (usually semver-compatible) name for this version. You should use this field to indicate changes and differentiate versions to your customers. This can be whatever you like, but is sorted by semver rules in the console. Unlike the version_number this does not necessarily need to change every build.

It is recommended to keep this in sync with your package.json version field, and both can be updated using quip-cli bump [increment].

version_number​

required

int

A version number for this build. Every time you want to upload a new version of your app, you MUST increase this number by at least one. To just bump it to the next version, use quip-cli bump.

sizing_mode​

required

string (enum)

To specify how the app will be sized must be one of the following options.

• fill_container - The app’s width is set to its container’s width and its height is determined by its contents. If fill_container_max_width is specified, the app’s width is set to that value when its container’s width is larger.

• scale - The app’s width is set to its initial_width and its height is determined by its contents. It is expected to always maintain a constant width/height aspect ratio and automatically scales down in smaller containers. It can also optionally be manually resizable.

• fit_content - The app’s width and height are both determined by its contents and are independent of its container’s width. If the app overflows past its container’s width, it will become horizontally scrollable.

initial_height​

required

integer

The height that this application should show as while loading the bundle. Applications should only change height as a response to user interaction, because it pushes other content on documents down when it changes. This hint allows the app to not cause the document to "jump" when it loads the final content.

use_color_theme​

optional

boolean

This will make your app automatically change background colors and update css variables when in dark mode. We recommend that all apps enable this option. More information on how to properly use color themes can be found here:

Since Quip now supports dark mode, is it possible to support dark mode for my Live App?

toolbar_color​

optional

string (enum, hex)

String representing the color that the main toolbar menu button should be colored. May be a hex code or one of the following values:

• red
• orange
• yellow
• green
• blue
• violet

If not provided, the toolbar color will be blue.

toolbar_icon​

optional

string

A relative path to an svg to use for the toolbar icon. It should be readable at 16px by 16px.

thumbnail​

optional

string

A relative path to an svg to use for the thumbnail when presenting in larger browse-style interfaces. It should look good when sized to 232w by 131h.

min_api_version​

optional

string

If you use API features that are released after a certain version, use this field to prevent Quip clients with older versions from loading your app. Use of this field is fairly rare.

initial_width​

optional

integer

Integer width in pixels for a newly created, empty instance of this app. This only applies to app with scale or fit_content sizing. For apps with fit_content sizing, this value is only used to determine the width of the loading placeholder when the app is created.

fill_container_max_width​

optional

integer

The maximum width of the app. This only applies to apps with "fill_container" sizing.

js_files​

optional

Array<string>

The list of JS files to be injected into the app frame. These are injected in the order they appear in this array. The paths specified here are relative to the manifest.json file.

css_files​

optional

Array<string>

The list of CSS files to be injected into the app frame. These are injected in the order they appear in this array. The paths specified here are relative to the manifest.json file.

other_resources​

optional

Array<string>

A list of relative file path patterns. Files in the package matching these patterns will be uploaded to Quip and will be available as resources to the app. These could include image or font resource files, for example.

migrations​

optional

Array<Migration>

A migration has the format

{
    "version_number": integer,
    "js_file": string,
}

Each migration is a js file that performs a unidrectional transformation to an app's root record. When an app previously had data from an older version and is loaded with the version indicated by version_number, the root record will be transformed before the app runs. This allows you to change your data model without having to support prior data models.

Example

import quip from "quip-apps-api";

quip.apps.registerMigration((rootRecord) => {
    if (rootRecord.get("newProperty") === undefined) {
        rootRecord.set("newProperty", "default value for old apps");
    }
    return rootRecord;
});

To create a new migration, use quip-cli migration [migration-name]. It will fill in this field for you and generate the necessary js file.

csp_sources​

optional

Dictionary<string, Array<string>>

Map of CSP directives that should be included in the app.

The keys are any of:

• connect_srcs
• font_srcs
• frame_srcs
• img_srcs
• media_srcs
• script_srcs
• style_srcs

The values are lists of domains/keywords that should be allowed for that CSP directive.

For example, "script_srcs": ["https://foo.com", "https://bar.com"] will generate the CSP header value "script-src https://foo.com https://bar.com;".

Specifying these will allow JS/CSS/images/fonts/etc to be fetched from remote servers, allow the app to make external AJAX requests, and/or allow the app to embed iframes of its own. However, they may cause the app to not work correctly in an offline native client. The domains must use https or be a known keyword, e.g. "'self'", "'none'".

More information about CSPs can be found in the Mozilla documentation

intercept_url_patterns​

optional

Array<string>

List of URL patterns that the editor should intercept when pasting a link and create an instance of this app instead. See initialization for how this data is passed to the app. These URL patterns may include * to represent a wildcard and are otherwise treated as prefixes (only a prefix match is necessary in order to match with a pasted URL).

These URL patterns must use a protocol of either http or https. Note that these will only work for apps that are globally available to Quip users, and they currently only work in the web version of Quip.

allow_tiny_size​

optional

boolean

We show an error if your app is below 50px tall/wide, as this is an odd user experience. You may set this to true to explicitly suppress this error.

disable_app_level_comments​

optional

boolean

Setting this to true will prevent commenting on the app as a whole (the comment bubble normally in the margin of the Quip document will not be shown)

requires_external_account​

optional

boolean

Setting this to true indicates that an external account is required to use this product. The name of the account will be the name of your Quip instance, and is only presented to admins during the install step.

toolbar_hide_label​

optional

boolean

Setting this to true will hide the toolbar label (as long as you have a toolbar icon).

Example​

{
    "id": "cSVfwAKVsWF",
    "manifest_version": 1,
    "name": "My Cool App",
    "version_name": "1.0",
    "version_number": 1,
    "use_color_theme": true,
    "sizing": "fit_content",
    "initial_height": 300,
    "initial_width": 800,
    "toolbar_icon": "assets/icons/toolbar.svg",
    "thumbnail": "assets/icons/thumbnail.svg",
    "disable_app_level_comments": true,
    "js_files": [
        "dist/app.js"
    ],
    "css_files": [
        "dist/app.css"
    ]
}