penpot-export

Description

penpot-export is a tool designed to export your design components created in Penpot directly to CSS files. With a simple penpot-export command, you can convert your designs into ready-to-use CSS declarations.

Installation

To install penpot-export, simply run:

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

# yarn
yarn add @penpot-export/cli

Configuration

Before you can use penpot-export, you need to set up a penpot-export.config.js file at the root of your project. This file defines how your Penpot designs will be exported.

Configuration example:

// @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: 'abea3ef6-4c19-808a-8003-01370d9cb586',
      pages: [
        {
          pageId: '71b1702b-2eb1-81d6-8002-f82a5f182088',
          output: 'src/styles/ui.css', // 👈 Path where your CSS file should be generated.
        },
      ],
    },
    {
      fileId: '4a499800-872e-80e1-8002-fc0b585dc061',
      colors: [
        {
          output: 'src/styles/colors.css', // 👈 Path where your CSS file should be generated.
        },
      ],
      typographies: [
        {
          output: 'src/styles/typographies.css', // 👈 Path where your CSS file should be generated.
        },
      ],
    },
  ],
}

module.exports = config

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 designs and generate CSS files in the places specified in your configuration file.

Development

Using Yarn Workspaces

This project 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 a demo 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

Package Structure

• packages/core: This package contains the tool written in TypeScript. This is where the primary tool code resides.
• packages/cli: This package contains the CLI tool written in TypeScript.
• packages/demo: This package serves as a demonstration environment. You can run the penpot-export command within this package to test out implementations in development.

Local Development

For the "demo" 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 "demo" package.
• yarn demo: Runs the penpot-export command within the "demo" package. 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.