diff --git a/README.md b/README.md index 971282d..2df4fb7 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,61 @@ # penpot-export -## Description +`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files. -`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. +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](https://second-editors-draft.tr.designtokens.org/format/) of the [W3C Design Tokens Community Group](https://github.com/design-tokens/community-group) format spec). -## Installation -To install `penpot-export`, simply run: +## 📦 Packages + +[`@penpot-export/cli`](./packages/cli/) ([npm package](https://www.npmjs.com/package/@penpot-export/cli)) 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`](./packages/core/) ([npm package](https://www.npmjs.com/package/@penpot-export/core)) contains the core functionality to retrieve the Penpot data, transform it and output it to the filesystem. + +[demos](./packages/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: ```bash # npm npm install @penpot-export/cli --save-dev # yarn -yarn add @penpot-export/cli +yarn add @penpot-export/cli --dev ``` -## Configuration +### 🔧 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. +`penpot-export` uses the Penpot public API of [a Penpot instance of your choice](https://help.penpot.app/user-guide/introduction/quickstart/). Before you can use `penpot-export`, you'll need a way to authenticate to that API. [Generate an access token](https://help.penpot.app/technical-guide/integration/#access-tokens) and save that value in a safe place. -Configuration example: +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: +```sh +penpot-export inspect +``` + +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`: ```js // @ts-check require('dotenv').config() @@ -37,25 +71,28 @@ 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. + format: 'scss', + output: 'src/styles/colors.css', // 👈 Path where your colors SCSS file should be generated. }, ], typographies: [ { - output: 'src/styles/typographies.css', // 👈 Path where your CSS file should be generated. + 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. }, ], }, @@ -64,8 +101,39 @@ const config = { module.exports = config ``` +
-## Usage +
+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`|`json` | Desired format to be generated +`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: @@ -73,34 +141,29 @@ Once you've set up the `penpot-export.config.js` file, simply run the following penpot-export ``` -This will read your Penpot designs and generate CSS files in the places specified in your configuration file. +This will read your Penpot design file and generate the declared files. -## Development + +## ⌨️ 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. +This project is written in TypeScript and 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 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](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. +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 "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. +- **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. diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..0fcb0dc --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,7 @@ +# @penpot-export/cli + +`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files. + +This package houses the code for the CLI tool to use `penpot-export` through the command line. + +Refer to the [full documentation](https://github.com/penpot/penpot-export) for usage notes. diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..959d3cb --- /dev/null +++ b/packages/core/README.md @@ -0,0 +1,7 @@ +# @penpot-export/core + +`penpot-export` is a tool designed to export your design tokens created in Penpot into ready-to-use code or parseable data files. + +This package houses the code for the core functionality of `penpot-export`. + +Refer to the [full documentation](https://github.com/penpot/penpot-export) for usage notes.