Skip to contentSkip to navigationSkip to topbar
Figma
Star

Quick Start for Paste

Instructions to create a new Paste project.


The quickest way to get started with Paste is to bootstrap a new React app using our template for Next.js(link takes you to an external page). This will create a new React app with Paste installed and ready for development.

Create an App

Create an App page anchor

You can use either Yarn(link takes you to an external page) or npm(link takes you to an external page) to bootstrap your project, but in these examples we will use Yarn.

Using create-next-app

Using create-next-app page anchor

Next.js is a framework for building React apps that use server-side rendering and create-next-app(link takes you to an external page) is an easy way to bootstrap a new Next app with minimal configuration.

Paste has a pre-made template for create-next-app that comes with @twilio-paste/core and @twilio-paste/icons as dependencies and uses TypeScript.

To create a new create-next-app app using the Paste template execute the following commands:

yarn create next-app --example https://github.com/twilio-labs/paste/tree/main/templates/paste-nextjs-template my-paste-app
cd my-paste-app
yarn dev

This starts your project in development mode and it can be seen at http://localhost:3000.

When you create the project, Paste is used in 2 files:

  • pages/_app.tsx: creates a MyApp component, which wraps all pages. This is where the Paste <Theme.Provider> is added which enables any child component to use tokens.
  • pages/index.tsx: a sample page with Paste components.

Scripts

Scripts page anchor
  • yarn dev: runs project in development mode, with hot reloading
  • yarn build: creates a production build of the project
  • yarn start: runs the project in production mode, need to run yarn build first

To read more in depth about how create-next-app works, check out their documentation(link takes you to an external page).

Using Twilio Flex with Paste

Using Twilio Flex with Paste page anchor

When creating a custom component or plugin for Twilio Flex, you can leverage Paste's UI components in your React app to build your user interface elements with ease. Paste's core and icons packages are dependencies in your plugin via the flex-ui package.

To avoid any potential issues during Paste upgrades, it's crucial to specify the version of Paste you want to use in your plugin's package.json file. You must either set the overrides (using npm), or the resolutions (using yarn, pnpm) key to override the version bundled with flex-ui. This will ensure that your plugin takes precedence over the version that is set via flex-ui.

Here's an example of how to configure your plugin's dependencies:

{
  "dependencies": {
    "@twilio-paste/core": "x.x.x",
    "@twilio-paste/icons": "x.x.x"
  },
  "resolutions": {
    "@twilio-paste/core": "x.x.x",
    "@twilio-paste/icons": "x.x.x"
  }
}

Be sure to follow the Twilio Flex plugin with Paste guide(link takes you to an external page) to set up the Providers and theme for your plugin, as Flex utilizes a proprietary approach to manage providers within a React plugin.

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

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.

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.