Best Practices

Follow best practices to guarantee a good user experience for users.

Information density

Pine extensions have a width between 226 and 252 pixels. To make the most of the limited space, they should be designed with information density and minimize the use of extensive whitespace.

Extensions with their own navigation should follow a similar pattern described in the tutorial—keep navigation one level deep, with a back button to return to the main route.

We recommend using the @radix-ui/themes library because this is the same library that Pine uses internally.

Error handles

IPC communication can sometimes fail due to timeout errors, permissions errors, and more. You can handle IPC errors by first checking if it's an instance of Pine's IPCError class, and then handling the error appropriately based on the error code:

try {
  const theme = await client.context.getTheme();
  // ...
} catch (error) {
  if (error instanceof IPCError) {
    console.log(error.message);
    
    switch (error.code) {
      case "TIMEOUT":
        // handle timeout error
        break;
      case "FORBIDDEN":
        // handle timeout error
        break;
    }
  }
}

Code (`error.code`)	Message (`error.message`)
BAD_REQUEST	Request failed validation or is invalid.
UNAUTHORIZED	Access is denied due to missing or invalid credentials.
FORBIDDEN	Access to the resource is forbidden.
NOT_FOUND	Resource or endpoint is not found.
METHOD_NOT_SUPPORTED	API method is currently not supported.
TIMEOUT	Request has timed out.
CONFLICT	Request could not be completed due to a conflict.
PRECONDITION_FAILED	Specified precondition in the request failed.
PAYLOAD_TOO_LARGE	Request payload is too large.
UNPROCESSABLE_CONTENT	Request cannot be processed due to semantic errors.
TOO_MANY_REQUESTS	Rate limit exceeded due to too many requests.
CLIENT_CLOSED_REQUEST	Client closed the connection before completing the request.
INTERNAL_SERVER_ERROR	Request encountered an unexpected error.

Bundle size

In addition to the limits discussed in the backend best practices, the bundled index.html file is also limited to 2 megabytes. This helps minimize the time taken to download an extension for those on slower connections.

Security

Pine prioritizes security by running extensions within a sandboxed iframe element with the allow-downloads, allow-scripts, and allow-same-origin permissions.

Extensions are loaded from a different origin, making it safe to pair the allow-scripts and allow-same-origin permissions for this use case.

This means that extensions cannot display popups or navigate the top-level browsing context. Please consult the sandbox property to learn more about the different restrictions placed on extensions.

Automatic updates

Extensions are also automatically kept up to date when possible to minimize the risk of running out-of-date code. The only exception to automatic updates is when the permissions associated with an extension have changed, which requires the user to update the extension to approve the new permissions explicitly. This is why it's essential to choose appropriate permissions when creating your extension to avoid any disruptions for the user.

Rate limits

Rate limits help ensure a consistent developer experience for all integration users. By default, requests are limited to 120 requests every 30 seconds. When a request has been rate-limited, it will return a TOO_MANY_REQUESTS, with the message field containing the remaining milliseconds (as a string).

Integrations that continuously breach rate limits will be disconnected to protect against extensions that may have entered an infinite request loop that would slow down the entire application.