From 0896dfc0ef4356f750e9b5d913e3665884a485f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marina=20L=C3=B3pez?= Date: Tue, 12 Mar 2024 07:48:02 +0100 Subject: [PATCH] chore: update documentation --- README.md | 76 +++++++++++++++++++--------------- docs/create-api.md | 2 + docs/create-plugin.md | 22 ++++++++-- docs/plugin-usage.md | 4 +- libs/plugins-runtime/README.md | 10 ++--- 5 files changed, 69 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 8ea46f7..03ae51a 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,65 @@ -# PenpotPlugins +# Penpot Plugins - +## What can you find here? -✨ **This workspace has been generated by [Nx, a Smart, fast and extensible build system.](https://nx.dev)** ✨ +We've been working in an MVP to allow users to develop their own plugins and use the existing ones. -## Generate code +There are 2 important folders to keep an eye on: `apps` and `libs`. -If you happen to use Nx plugins, you can leverage code generators that might come with it. +In the `libs` folder you'll find: -Run `nx list` to get a list of available plugins and whether they have generators. Then run `nx list ` to see what generators are available. +- plugins-data-parser: useful functions to parse the data we get from penpot. + It has its own [README](libs/plugins-data-parser/README.md). +- plugins-runtime: here you'll find the code that initializes the plugin and sets a few listeners to know when the penpot page/file/selection changes. + It has its own [README](libs/plugins-runtime/README.md). +- plugins-styles: basic css library with penpot styles in case you need help for styling your plugins. -Learn more about [Nx generators on the docs](https://nx.dev/plugin-features/use-code-generators). +In the `apps` folder you'll find some examples that use the libraries mentioned above. -## Running tasks +- example-plugin or contrast-plugin: to run this example check Create a plugin from scratch -To execute tasks with Nx use the following syntax: +- example-styles: to run this example you should run ``` -nx <...options> +npm run start:styles-example ``` -You can also run multiple targets: +Open in your browser: `http://localhost:4202/` + +## Create a plugin from scratch or run the examples from the apps folder + +First of all it's necessary to have penpot running locally, you can check the steps [here](https://help.penpot.app/technical-guide/developer/devenv/) + +Once you've done the previous step, you'll need to move to the following [branch](https://github.com/penpot/penpot/tree/niwinz-poc-plugins) as we still have the penpot part WIP +Remember to run penpot: ``` -nx run-many -t +./manage.sh pull-devenv +./manage.sh run-devenv ``` -..or add `-p` to filter specific projects +Then, you need to run `npm start` in the penpot-plugins repository. + +At this point, you have 2 choices: + +- if you want to run the examples you should run: ``` -nx run-many -t -p +// for the example plugin +npm run start + +or + +npx nx run example-plugin:serve-static --port 4201 ``` -Targets can be defined in the `package.json` or `projects.json`. Learn more [in the docs](https://nx.dev/core-features/run-tasks). +or -## Want better Editor Integration? +``` +// for the contrast plugin +npx nx run contrast-plugin:serve-static --port 4201 +``` -Have a look at the [Nx Console extensions](https://nx.dev/nx-console). It provides autocomplete support, a UI for exploring and running tasks & generators, and more! Available for VSCode, IntelliJ and comes with a LSP for Vim users. +Open in your browser: `http://localhost:4201/` -## Ready to deploy? - -Just run `nx build demoapp` to build the application. The build artifacts will be stored in the `dist/` directory, ready to be deployed. - -## Set up CI! - -Nx comes with local caching already built-in (check your `nx.json`). On CI you might want to go a step further. - -- [Set up remote caching](https://nx.dev/core-features/share-your-cache) -- [Set up task distribution across multiple machines](https://nx.dev/nx-cloud/features/distribute-task-execution) -- [Learn more how to setup CI](https://nx.dev/recipes/ci) - -## Connect with us! - -- [Join the community](https://nx.dev/community) -- [Subscribe to the Nx Youtube Channel](https://www.youtube.com/@nxdevtools) -- [Follow us on Twitter](https://twitter.com/nxdevtools) +- if you want to create a new plugin, read the following [README](docs/create-plugin.md) diff --git a/docs/create-api.md b/docs/create-api.md index 8ca7028..6d35327 100644 --- a/docs/create-api.md +++ b/docs/create-api.md @@ -1,3 +1,5 @@ +# Create API + Add your API in `libs/plugins-runtime/src/lib/api/index.ts`. Try to use `zod` to validate the input an output, for example: diff --git a/docs/create-plugin.md b/docs/create-plugin.md index 2cb0667..c767ad2 100644 --- a/docs/create-plugin.md +++ b/docs/create-plugin.md @@ -1,6 +1,12 @@ -npx nx g @nx/web:application example-plugin --directory=apps/example-plugin +# Create plugin -Create a manifes.json in /public +To create the basic scaffolding run the following command. Remember to replace `example-plugin` with your own. + +``` +npx nx g @nx/web:application example-plugin --directory=apps/example-plugin +``` + +Create a `manifes.json` in `/public`. ```json { @@ -32,10 +38,18 @@ Add to `tsconfig.app.json` "include": ["src/**/*.ts", "../../libs/plugins-runtime/src/lib/index.d.ts"] ``` -Run static server `npx nx run example-plugin:serve-static --port 4201` +Then, run the static server -Go to penpot and load the plugin. +``` +npx nx run example-plugin:serve-static --port 4201 +``` + +Finally, go to penpot and load the plugin. Run the command in the console devtools from your browser. ```ts ɵloadPlugin({ manifest: 'http://localhost:4201/manifest.json' }); ``` + +### More about plugin development + +Check the [plugin usage](docs/plugin-usage.md) and the [create API](docs/create-api.md) documentation. diff --git a/docs/plugin-usage.md b/docs/plugin-usage.md index 172b7e1..4b5e195 100644 --- a/docs/plugin-usage.md +++ b/docs/plugin-usage.md @@ -1,4 +1,6 @@ -Open UI: +# Plugin usage + +If you want your plugin to be opened in a modal, then use open UI: ```ts penpot.ui.open('Plugin name', 'http://localhost:4201', { diff --git a/libs/plugins-runtime/README.md b/libs/plugins-runtime/README.md index 388016e..f7da5dc 100644 --- a/libs/plugins-runtime/README.md +++ b/libs/plugins-runtime/README.md @@ -1,9 +1,7 @@ -# plugins-runtime +# Plugins runtime -Go to to the [this branch](https://github.com/penpot/penpot/tree/niwinz-poc-plugins) in the Penpot local code. +The plugins-runtime is the responsible on generate the api and to load the plugin. -Run the penpot runtime with `npm start`. +Once you've run the example plugin or your own, you should see on the browser devtools the logs from this file `plugins-runtime/src/index.ts`. So every time there is a change in the page, file or selection in the penpot app, it'll show a log. -Now you can go to penpot and see the `log` of this file `plugins-runtime/src/index.ts`. - -See [this docs about how to install plugins](../docs/create-plugin.md). +See [this doc about how installing plugins](../docs/create-plugin.md).