Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Core

Version 20.11.0GithubStorybook

Core contains all the packages from the Paste design system.


Guidelines

Guidelines page anchor

About Core

About Core page anchor

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.

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

Core vs. Individual Packages page anchor

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';

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" file(link 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

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!


yarn add @twilio-paste/core
import {Box} from '@twilio-paste/core/box';

const App = () => <Box />;

See Entire Changelog