Skip to content

Best practices

While it's easy to get started building a Pack, there are lots of options to explore and decisions to make as you go. This page includes some best practices we've learned through developing our own Packs that we encourage you to consider.

Formulas

  • Follow the guidance on formula naming.
  • Ensure each formula has a few examples defined. These show up in the generated documentation for the formula.
  • Set a suggested value for required parameters. This allows users to drag the formula from the side panel and see a result immediately.
  • For each formula that has only a single required parameter, consider exposing it as a column format. This makes it easier for users to use the functionality in a table.
  • Consider the caching behavior of your formulas. Use longer cache times for formulas where the results are deterministic, and shorter cache times for ones that fetch external data.

Actions

Column formats

  • Follow the guidance on column format naming.
  • For column formats that use a URL as input, add a matcher pattern. This allows Coda to apply the format automatically when a user adds a compatible URL to a table.

Sync tables

  • Follow the guidance on sync table naming.
  • Set the description field for each sync table. The description is shown on the Pack's listing page and helps a user understand what data it retrieves.
  • Add parameters to sync tables to allow for filtering. Filtering is particularly important when a table can return a large number of rows.
  • Consider the caching behavior of your sync tables. Most fetcher requests should have their caching reduced or disabled to ensure the latest results are synced.
  • For the schema property containing the row identifier use a descriptive name like {thing}Id instead of simply id.
  • Set a few featured columns on your schema, for the most commonly used properties.

Authentication

  • Set a meaningful account name by implementing the getConnectionName function. This helps users that connect to multiple accounts distinguish them.
  • Make sure to set the instructionsUrl field. Direct user to a help center article that provides information about where they can find the required tokens or credentials.

General

  • Throw a UserVisibleError for bad input or when an expected type of error occurs. This allows you to provide a more informative error message to the user.
  • If accepting or returning an index value, start counting at 1. Although JavaScript is 0-based, Coda formula language is 1-based.

Launching