Skip to content
Paste
UX Platform
Change the site theme
information:

Core

Core contains all the packages from the Paste design system.


Guidelines#

About Core#

The Core package includes all components and libraries in Paste.

We highly recommend accessing Paste components and libraries primarily through Core. To do this, install the Core package and use unbarreled imports to individually import the components and libraries used in each file.

After Core is installed, specific Paste packages in your project can be pinned to specific versions if needed by installing those packages individually.

Using Core#

In Paste, we use an "unbarreled" import mechanism, so the import statements 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 importing these components from @twilio-paste/core, specifying the import to a limited package keeps your bundles lean by only loading exactly what you need.

Unlike other bundled libraries, using Core and Icons this way 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.

Paste Core is able to do this because Paste also publishes each library and component as its own package.

Core vs. Individual Packages#

We recommend Core over solely using individual package installs to make maintaining Paste in your project easier. Using a non-Core approach will cause the package.json file to be full of individual package dependencies; keeping their versions in sync can be quite time consuming.

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

However, the individual package install is invaluable for pinning specific versions of specific packages. If updating Core would mean updating a package you aren't ready for, you can install that specific package and import from it directly.

For example, if you are about to update Core, and notice this update changes the Button component, a component you are not ready to update, this shouldn't stop you from updating Core! You can install @twilio-paste/button to the version that works for the project 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 specific version we installed
import {Theme} from '@twilio-paste/core/theme';

Import Differences#

You may have imported from other libraries like this:

import {Box, Anchor, Button, Theme} from '@twilio-paste/core'; // don't do this!

The problem with importing this way is that the referenced "main" filelink takes you to an external page in each of these packages has to bundle all the different pieces together. This causes everything in Paste Core or Paste Icons 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.

Do's and Don'ts#

Do

Use unbarreled imports

Don't

Don't import all of Core into your file

Do

Pin a specific version of a package by installing and importing it directly

Don't

Don't individually install and import every single package. Use Core!


API Guide#

Installation#

yarn add @twilio-paste/core

Usage#

import {Box} from '@twilio-paste/core/box';
const App = () => <Box />;

See Entire Changelog

Black lives matter.