Skip to content


Switch branches/tags


Failed to load latest commit information.
Latest commit message
Commit time

lerna #-frontend-exp-core

This repository is the home for all of Toptal's reusable UI, split up into distinct monorepo packages distributed through NPM:


Please read our documentation here

Running storybook

In order to run storybook you need to execute yarn start which will spin up storybook server on http://localhost:9001.

Project commands

Command Description
build:package Build the packages
build:storybook Build Storybook as static website
commit Interactive conventional commits
generate:component Generate a new component template
generate:example Generate a new component component code example
generate:icons Generate JSX icon components from svgs
happo Run Happo locally and generate report on
happo:storybook Run Happo for Storybook on CI
lint Lint all files
start Start storybook instance and inspect components
test Run jest and cypress tests
test:integration Run cypress tests
test:integration:open Run cypress in development mode
test:unit Run unit tests
test:unit -u Update jest snapshots
test:unit:watch Run unit tests in watch mode
typecheck Validate typescript compilation


Add an icon

In Picasso, we keep icons in svg format and transform them into react components to make usage in react projects easier. This transformation is processed by the svgr tool.

To add a new Icon to Picasso library please follow these steps:

  1. Prepare your SVG:

    • Make sure that it has viewBox attribute specified
    • Make sure that viewBox size is 0 0 16 16 (be careful this isn't just a simple value set!)
    • Make sure all paths are expanded and strokes are not used
  2. Add your SVG file(s) to the Picasso project:


  3. Run the command

    yarn generate:icons

    This command will prepare corresponding react components for your icons and add export statements to packages/picasso/src/Icon/index.ts

After Picasso will be released with your changes you can start using your Icon as described in the Icons section.

Adding new packages

  1. Create a new folder under /packages and add to it:

    • package.json by running lerna add. Specify Toptal as the author and src/index.ts in the main key
    • using this template with paths to the node_modules of any used packages from the /packages directory
      "extends": "../../",
      "compilerOptions": {
        "outDir": "./build",
        "paths": {
          "@toptal/picasso/*": ["node_modules/@toptal/picasso/src/*"],
          "@toptal/picasso": ["node_modules/@toptal/picasso/src/index"]
      "include": ["./src/**/*"],
      "exclude": [
    • using this template (All notable changes to the package will be documented in this file automatically)
    # Change Log
    All notable changes to this project will be documented in this file.
    See [Conventional Commits]( for commit guidelines.
  2. Add the new package to:

    • the paths key in /tsconfig.json
    • the alias key in /.storybook/webpack.config.js
    • the imports variable in /.storybook/components/CodeExample/CodeExample.tsx
    • the new record to Dockerfile

Linking with other projects

In order to develop or debug Picasso in parallel with your project without the need to publish new Picasso versions, you need to link Picasso to your project. And once finished unlink it. You will probably notice that linking process links @toptal/picasso and react. It is due to React restriction of only once instance used in the project [1] [2], so we link to Picasso's react version.


To link Picasso follow these steps:

In Picasso project directory:

  1. Checkout Picasso project from GitHub
  2. Install Picasso dependencies with yarn install
  3. Build Picasso inside Picasso package folder (./packages/picasso/) with yarn build:package
  4. Create a link with running in the root path yarn symlink (creates all links to Picasso packages and React link)

In your project directory:

  1. Link Picasso and React with yarn link @toptal/picasso react
  2. Start your project and changes in Picasso will be visible in your project!


To unlink Picasso follow these steps:

In your project directory:

  1. Unlink Picasso with yarn unlink @toptal/picasso react
  2. Re-install dependencies with yarn install --force

(Optional) In Picasso project directory:

  1. Unlink with yarn symlink:off
  2. Re-install dependencies with yarn install --force

Tree shaking

If you use davinci to manage your application - tree shaking works by default when you build your project in the production mode.

In other cases when you use custom webpack build configuration you should check these three things to make sure you will have Picasso tree-shaked:

  1. You run your build in production mode
  2. You are not transforming your ES modules into commonjs during the build process. Usually, it's default behavior of popular babel presets - modules configuration
  3. You have sideEffects prop in your package.json set to false value or don't have it at all

Have a happy tree shaking! :)