Engineering Guidelines for Paste
Installation and usage instructions for using Paste.
Installation#
Dependencies#
To start using Paste, you must first install the following third party dependencies:
Package | Version |
---|---|
react | ^16.8.6 |
react-dom | ^16.8.6 |
prop-types | ^15.7.2 |
Install them in your project folder using either of these terminal commands:
# yarnyarn add react react-dom prop-types# npmnpm 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.
Package | Version |
---|---|
@twilio-paste/core | 4.3.0 |
@twilio-paste/icons | 3.12.0 |
# yarnyarn add @twilio-paste/core @twilio-paste/icons# npmnpm 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>);
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>
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.
You can view and play with icons on our icon list. Our icon set is still limited, and more will be added over time. Please file an icon request or follow the guide on how to add an icon.
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:
Show full package list
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 publishedimport {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 installedimport {Theme} from '@twilio-paste/core/theme';