Engineering Guidelines for Paste

Quickstart#

The quickest way to get started with Paste is to bootstrap a new React app using one of our templates for popular React frameworks, Next.js and Create React App.

Both approaches will create a new React app with Paste installed and ready for development.

Using create-next-app#

Execute create-next-app with npm or Yarn to bootstrap a Next.js app using Paste:

npx create-next-app --example https://github.com/twilio-labs/paste/tree/main/packages/paste-nextjs-template my-paste-app
# or
yarn create next-app --example https://github.com/twilio-labs/paste/tree/main/packages/paste-nextjs-template my-paste-app

Using create-react-app#

To create a new CRA app using the Paste template execute the following command:

npx create-react-app --template @twilio-paste my-paste-app
# or
yarn create react-app --template @twilio-paste my-paste-app

Manual Installation#

Dependencies#

To start using Paste, you must first install the following third party dependencies:

Install them in your project folder using either of these terminal commands:

# yarn
yarn add react react-dom prop-types
# npm
npm install react react-dom prop-types

Paste Packages#

Paste is split into two main packages: @twilio-paste/core and @twilio-paste/icons. Everything provided by Paste is included into those two packages. A key distinction with Paste Core is that we include - not bundle - all of Paste; this means we expose sub-packages you can individually import. For example, you would install @twilio-paste/core and import the Button component from @twilio-paste/core/button rather than directly from @twilio-paste/core. This keeps your app lean by only including the code you use. You can read about how Paste keeps your bundles small down below.

Everything exposed inside Paste Core can also be installed individually; you could install @twilio-paste/button and import only that one package. However, we recommend using the Core package for ease of maintenance and only falling back to the individual packages if you need to pin to a specific version.

# yarn
yarn add @twilio-paste/core @twilio-paste/icons
# npm
npm install @twilio-paste/core @twilio-paste/icons

Setting up the Theme Provider#

For Paste components to be styled correctly, you must provide them with a theme. To do so you must wrap the root of your app with the theme provider and select a theme. We recommend the default theme.

import {Theme} from '@twilio-paste/core/theme';
// Wrap your root component with the Theme.Provider like so:
const App = () => (
  <Theme.Provider theme="default">
    <RestOfYourAppInHere />
  </Theme.Provider>
);

Usage#

Paste Components#

You can use the Paste components anywhere that is wrapped by the Theme Provider.

import {Box} from '@twilio-paste/core/box';
const Component = () => (
  <Box margin="space20" backgroundColor="colorBackground">
    Hello Paste!
  </Box>
);

Using Icons#

The Paste Icons package provides icon components. They can be used to enhance the appearance of a web interface and break up the monotony of text. Icons have to be imported individually.

// or from '@twilio-paste/icons/cjs/PlusIcon'
import {PlusIcon} from '@twilio-paste/icons/esm/PlusIcon';
const Component = () => (
  <Button variant="secondary" size="small" onClick={() => {}}>
    <PlusIcon decorative={true} />
    Add to cart
  </Button>
);

For more information about our icon system, checkout our usage guide here.

Jest / Testing#

Just like rendering Paste components in a web application, when rendering components for the purposes of testing you are required to wrap them in the Theme Provider. If you do not, your components may fail to render correctly.

It can sometimes be helpful to test Paste components without animation. To disable animations on Paste components, pass the disableAnimations boolean prop to the <Theme.Provider>.

<Theme.Provider theme="default" disableAnimations>
  {/* your content */}
</Theme.Provider>

Handling Icons in Jest#

Jest will often complain about using the esModules versions (/esm/) of Paste Icons, since it perfers the commonJS version. You'll often see an error similar to:

Test suite failed to run
  unknown: Unexpected token (1:660)
    This usually means that you are trying to import a file which
    Jest cannot parse, e.g. it's not plain JavaScript.
    ...

In order to fix these Jest errors, you'll need to configure Jest to correctly handle the esModules versions of Paste Icons.

You can use the transformIgnorePatterns option to tell Jest to not transform Paste Icons, which allows Jest to transpile these files. More information about transformIgnorePatterns can be found by reading the Jest documentation.

// jest.config.js
{
  "transformIgnorePatterns": [
    "/node_modules/@twilio-paste/icons/.*"
  ]
}

Global Styles#

Many apps/websites utilize global stylesheets. Even though Paste styles are scoped at the component level, global styles can creep in and cause some havoc. Make sure to thoroughly test Paste components to verify everything looks as they should.

Fonts#

Default theme#

Fonts for the default theme are available via the Twilio CDN and published from an internal git repository.

The best and most performant way to load the fonts is to include the following snippet in the <head /> of your web page.

<link rel="preconnect" href="https://assets.twilio.com" crossorigin />
<link rel="stylesheet" href="https://assets.twilio.com/public_assets/paste-fonts/main-1.2.0/fonts.css">

Alternatively, Paste will automatically load the fonts via JavaScript, so long as you wrap your application with the Theme.Provider and select the default theme. Though, you should note that this is not the most performant way.

Other themes#

If you are using any other theme, Paste leaves it up to you to load the fonts needed. Console uses Whitney ScreenSmart and SendGrid uses Colfax. More often than not with those themes, you are working within existing SendGrid and Twilio Console applications and these fonts are automatically loaded for you.

The Whitney font is loaded by the Typography.com service and is only allowed on *.twilio.com domains as well as localhost. Make sure to serve your app from the correct hostname if you're having issues with font loading.

If you are not working in an existing Twilio Console experience, you can include the following link element in your sites head to load these fonts if you are serving your application from *.twilio.com domains.

<link rel="stylesheet" type="text/css" href="//cloud.typography.com/6230892/752864/css/fonts.css">

Additional information#

Core package list#

You can install Paste packages individually to pin to a specific version in your project. Here's an list of all the packages included inside Paste Core:

How the Core package stays lean#

Unlike other bundled libraries, using Core and Icons won't load all of Paste into your product's bundle, it will only include the parts you are importing. This happens automatically, without any requirement for a tree-shaking config in your builds.

You may have imported from other libraries like this:

import {Box, Anchor, Button, Theme} from '@twilio-paste/core';
import {DisclosureIcon, DeleteIcon} from '@twilio-paste/icons';

The problem with importing this way is that the referenced "main" file in these packages has to bundle all the different pieces together. This causes everything to be loaded even if we only need one small feature. With over 50 icons in our Icon package and 40 components in Core - with more being added continuously - this can become very heavy very quickly.

In Paste, we use an "unbarreled" import mechanism, so the above would look like this:

import {Box} from '@twilio-paste/core/box';
import {Anchor} from '@twilio-paste/core/anchor';
import {Button} from '@twilio-paste/core/button';
import {Theme} from '@twilio-paste/core/theme';
import {DisclosureIcon} from '@twilio-paste/icons/esm/DisclosureIcon';
import {DeleteIcon} from '@twilio-paste/icons/esm/DeleteIcon';

While this has more import lines than the previous example, we are specifying the import to a limited package. This keeps your bundles lean by only loading exactly what you need.

Paste Core is able to do this because Paste publishes each library and component as its own package. For example the above can be written as:

import {Box} from '@twilio-paste/box';
import {Anchor} from '@twilio-paste/anchor';
import {Button} from '@twilio-paste/button';
import {Theme} from '@twilio-paste/theme';
// Paste Icons are not individually published
import {DisclosureIcon} from '@twilio-paste/icons/esm/DisclosureIcon';
import {DeleteIcon} from '@twilio-paste/icons/esm/DeleteIcon';

The reason we recommend Core over using individual package imports is because it makes maintaining Paste in your project easier. If using the above approach, your package.json file will be full of individual package dependencies and keeping their versions in sync can be quite time consuming.

However, the individual package import is invaluable for when updating Core also makes changes to a package you aren't ready for. You can then install that pinned package and import from it directly. For example let's assume we update our Core package and as a side effect, the Button component gets updated. We aren't ready to update Button, but that shouldn't stop us from updating the rest of Core! We can install @twilio-paste/button to the version that works and import it like this:

import {Box} from '@twilio-paste/core/box';
import {Anchor} from '@twilio-paste/core/anchor';
import {Button} from '@twilio-paste/button'; // This loads the version we installed
import {Theme} from '@twilio-paste/core/theme';