penpot-export/README.md

# 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:

```bash
# 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`](./packages/demo/penpot-export.config.js) file at the root of your project. This file defines how your Penpot designs will be exported.

Configuration example:

```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: '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:

```bash
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](https://classic.yarnpkg.com/lang/en/docs/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](https://classic.yarnpkg.com/lang/en/docs/workspaces/#toc-why-would-you-want-to-do-this)

### Package Structure

- [**packages/core**](./packages/core/): This package contains the tool written in TypeScript. This is where the primary tool code resides.
- [**packages/cli**](./packages/cli/): This package contains the CLI tool written in TypeScript.
- [**packages/demo**](./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.