Penpot/penpot-plugins
0
Fork 0
mirror of https://github.com/penpot/penpot-plugins.git synced 2025-01-08 07:50:44 -05:00
Code Issues Activity

Merge pull request #14 from penpot/chore/documentation

Browse source 
chore: update documentation
This commit is contained in:
Marina López 2024-03-14 12:46:51 +01:00 committed by GitHub
commit 4d3853f067
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 69 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
README.md
View file

@ -1,57 +1,65 @@
# PenpotPlugins # Penpot Plugins
<a alt="Nx logo" href="https://nx.dev" target="_blank" rel="noreferrer"><img src="https://raw.githubusercontent.com/nrwl/nx/master/images/nx-logo.png" width="45"></a> ## 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 <plugin-name>` 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 <a href="#create-a-plugin-from-scratch-or-run-the-examples-from-the-apps-folder">Create a plugin from scratch</a>
To execute tasks with Nx use the following syntax: - example-styles: to run this example you should run
``` ```
nx <target> <project> <...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 <target1> <target2> ./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 <target1> <target2> -p <proj1> <proj2> // 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? - if you want to create a new plugin, read the following [README](docs/create-plugin.md)
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)

2
docs/create-api.md
View file

@ -1,3 +1,5 @@
# Create API
Add your API in `libs/plugins-runtime/src/lib/api/index.ts`. Add your API in `libs/plugins-runtime/src/lib/api/index.ts`.
Try to use `zod` to validate the input an output, for example: Try to use `zod` to validate the input an output, for example:

22
docs/create-plugin.md
View file

@ -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 ```json
{ {
@ -32,10 +38,18 @@ Add to `tsconfig.app.json`
"include": ["src/**/*.ts", "../../libs/plugins-runtime/src/lib/index.d.ts"] "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 ```ts
ɵloadPlugin({ manifest: 'http://localhost:4201/manifest.json' }); ɵ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.

4
docs/plugin-usage.md
View file

@ -1,4 +1,6 @@
Open UI: # Plugin usage
If you want your plugin to be opened in a modal, then use open UI:
```ts ```ts
penpot.ui.open('Plugin name', 'http://localhost:4201', { penpot.ui.open('Plugin name', 'http://localhost:4201', {

10
libs/plugins-runtime/README.md
View file

@ -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 doc about how installing plugins](../docs/create-plugin.md).
See [this docs about how to install plugins](../docs/create-plugin.md).