penpot-export

penpot-export is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files.

Currently, it is able to export page components as CSS and SCSS declarations, and typography and colors assets as CSS, SCSS or JSON (following the Second Editor' Draft of the W3C Design Tokens Community Group format spec).

📦 Packages

@penpot-export/cli (npm package) is a CLI tool to use penpot-export through the command line. It features a configuration file where you declare what will be exported, where in the file system and what format will use.

@penpot-export/core (npm package) contains the core functionality to retrieve the Penpot data, transform it and output it to the filesystem.

demos is a demostrative private package that contains some examples of how to use @penpot-export/cli.

🧑‍💻 Usage

⬇️ Installation

The recommended way to install the penpot-export CLI is as a development dependency on a project:

# npm
npm install @penpot-export/cli --save-dev

# yarn
yarn add @penpot-export/cli --dev

🔧 Configuration

penpot-export uses the Penpot public API of a Penpot instance of your choice. Before you can use penpot-export, you'll need a way to authenticate to that API. Generate an access token and save that value in a safe place.

You'll also need the file ID of an existing Penpot file in that Penpot instance. Open the Penpot file in your browser and copy the URL. Then run:

penpot-export inspect <YOUR FILE URL HERE>

It'll output something similar to this:

The following details are the result of inspecting the provided URL:
    Penpot instance: https://design.penpot.app/
    Workspace id: f542b13d-6fc1-8116-8002-fc0aaa3627ae
    File id: 52961d58-0a92-80c2-8003-2fc8ab8b34dd
    Page id: 38f1e350-296d-80f1-8002-fd390f93b03d

Grab the file ID and the Penpot instance.

With this, set up a penpot-export.config.js file at the root of your project declaring how your Penpot designs will be exported.

Example config file

penpot-export.config.js:

// @ts-check
require('dotenv').config()

if (typeof process.env.PENPOT_ACCESS_TOKEN !== 'string') {
  throw new Error('Missing PENPOT_ACCESS_TOKEN environment variable')
}

/**
 * @type {import('@penpot-export/core').UserConfig}
 */
const config = {
  instance: process.env.PENPOT_BASE_URL || undefined,
  accessToken: process.env.PENPOT_ACCESS_TOKEN,
  files: [
    {
      fileId: '4a499800-872e-80e1-8002-fc0b585dc061',
      colors: [
        {
          format: 'scss',
          output: 'src/styles/colors.css', // 👈 Path where your colors SCSS file should be generated.
        },
      ],
      typographies: [
        {
          format: 'json',
          output: 'src/styles/typographies.css', // 👈 Path where your typographies JSON file should be generated.
        },
      ],
    },
    {
      fileId: 'abea3ef6-4c19-808a-8003-01370d9cb586',
      pages: [
        {
          pageId: '71b1702b-2eb1-81d6-8002-f82a5f182088',
          format: 'css',
          output: 'src/styles/ui.css', // 👈 Path where your page components CSS file should be generated.
        },
      ],
    },
  ],
}

module.exports = config

Configuration schema

Config schema:

property	type	notes
instance	(optional) string	Defaults to https://design.penpot.app
accessToken	string	The access token used to authenticate to the instance above
files	FileConfig object	A list of files to export, each with its own configuration

FileConfig schema:

property	type	notes
fileId	string	The UUID of the file where assets will be exported
colors	(optional) ColorsConfig	A list of outputs for color assets
typographies	(optional) TypographiesConfig	A list of outputs for typography assets
pages	(optional) PagesConfig	A list of outputs for page components

AssetConfig (ColorsConfig, TypographiesConfig, PagesConfig) schema:

property	type	notes
output	string	Relative route where your file should be generated
format	css	scss
fileId	string (only for PagesConfig)	The UUID of the page from where components will be exported

▶️ Usage

Once you've set up the penpot-export.config.js file, simply run the following command to generate your CSS files:

penpot-export

This will read your Penpot design file and generate the declared files.

⌨️ Development

Using Yarn Workspaces

This project is written in TypeScript and utilizes Yarn Workspaces to manage multiple packages within a single repository. This allows us to house the source code of the penpot-export modules and demos in separate packages, streamlining development and testing.

Why Yarn Workspaces?

Your dependencies can be linked together, which means that your workspaces can depend on one another while always using the most up-to-date code available. - Reference

Local Development

For the "demos" package to utilize the local version of the penpot-export command you're developing, it's essential first to compile the TypeScript code from the penpot-export package.

Handy Commands

To facilitate the development process, we've set up the following commands that can be run at the repository's root:

• yarn dev: Runs the CLI tool in development mode. Ideal for making changes and seeing real-time results.
• yarn build: Compiles the TypeScript code in production mode. Ensure you run this command before testing the tool in the demos package.
• yarn demo: Runs the penpot-export command within the demos package per demo. It's handy for quickly testing implementations after making changes to the source code.

We recommend following this workflow: make changes to the code, run yarn build, and then yarn demo to test your changes.