From 9865ab2d2d52c2d96921b5871f9c499ede7b2bcb Mon Sep 17 00:00:00 2001 From: corb3nik Date: Sun, 5 Jan 2025 13:14:34 -0500 Subject: [PATCH 1/2] Add configuration guide --- .vitepress/sidebars/guides.ts | 4 ++ src/guides/config.md | 87 +++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 src/guides/config.md diff --git a/.vitepress/sidebars/guides.ts b/.vitepress/sidebars/guides.ts index c799da1..2425ec1 100644 --- a/.vitepress/sidebars/guides.ts +++ b/.vitepress/sidebars/guides.ts @@ -8,6 +8,10 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ text: "Getting Started", link: "/guides/", }, + { + text: "Configuring your Plugin", + link: "/guides/config", + }, ], }, { diff --git a/src/guides/config.md b/src/guides/config.md new file mode 100644 index 0000000..65eef44 --- /dev/null +++ b/src/guides/config.md @@ -0,0 +1,87 @@ +# Configuring your Package + +Caido packages are configured using the `caido.config.ts` file. This file is located in the root of your plugin's directory. +This file is used by the `caido-dev` CLI to build your plugin into a `plugin_package.zip` file. + +If you've created a new package with `pnpm create @caido-community/plugin`, the `caido.config.ts` file will be created for you. + +Here's what a typical `caido.config.ts` file looks like: + +```ts +import { defineConfig } from "@caido-community/dev"; + +export default defineConfig({ + id: "my-plugin", + name: "My Plugin", + description: "A plugin for Caido", + version: "0.0.0", + author: { + name: "Caido Labs Inc.", + email: "dev@caido.io", + url: "https://caido.io" + }, + plugins: [ + { + kind: "frontend", + id: "my-frontend", + name: "My Frontend", + backend: { + id: "my-backend" + } + }, + { + kind: "backend", + id: "my-backend", + name: "My Backend", + } + ] +}); +``` + +## Updating Package Details + +Most plugins will only need to update the `id`, `name`, `description`, `author`, and `version` fields. + +### ID + +The `id` field is a unique identifier used to identify your plugin in Caido. This must be a string that is unique across all plugins. + +### Name + +The `name` field is the name of your plugin. This is the name that will be displayed when a user installs your plugin. + +Keep your names concise, and avoid using the term "Caido" in the name. (e.g. "Auth Tester" instead of "Caido Auth Tester") + +### Description + +The `description` field is a short description of your plugin. This will be displayed when a user installs your plugin. + +### Author + +The `author` field is an object comprised of a `name`, `email`, and `url`. + +- `name` is the name of the author. +- `email` is a contact email address for the author. +- `url` is a URL that links to the author's website. + +### Version + +The `version` field is a string that represents the version of your plugin using [Semantic Versioning](https://semver.org/). + +When creating a new release of your plugin, you should increment this version number. + +## Updating Plugin Details + +Packages are comprised of one or more plugins that may need to be configured differently. You can find more information about plugins in the [Plugin Architecture](/concepts/essentials/package) page. + +These options usually don't need to be updated, but you can if needed. + +### Frontend Plugins + +For frontend plugins, `caido-dev` uses [Vite](https://vitejs.dev/) to build your plugin. This means you can specify additional Vite options in your `caido.config.ts` file. + +If you created your package with `pnpm create @caido-community/plugin`, the `caido.config.ts` file will be created with a default set of Vite options. We suggest you start with these options, and then update them if needed. + +### Backend Plugins + +For backend plugins, `caido-dev` uses [tsup](https://tsup.egoist.dev/) to build your plugin. The `tsup` options are not currently configurable. From ec54e80758ab172e39a80d8ae4c18554489e594c Mon Sep 17 00:00:00 2001 From: corb3nik Date: Sun, 5 Jan 2025 13:37:37 -0500 Subject: [PATCH 2/2] Add config reference --- .vitepress/sidebars/guides.ts | 2 +- .vitepress/sidebars/reference.ts | 8 ++- src/guides/config.md | 4 ++ src/guides/distribution/repository.md | 2 +- src/reference/config.md | 73 +++++++++++++++++++++++++++ src/reference/index.md | 2 + 6 files changed, 87 insertions(+), 4 deletions(-) create mode 100644 src/reference/config.md diff --git a/.vitepress/sidebars/guides.ts b/.vitepress/sidebars/guides.ts index 2425ec1..7af5aac 100644 --- a/.vitepress/sidebars/guides.ts +++ b/.vitepress/sidebars/guides.ts @@ -9,7 +9,7 @@ export const guidesSidebar: DefaultTheme.SidebarItem[] = [ link: "/guides/", }, { - text: "Configuring your Plugin", + text: "Configuring your Package", link: "/guides/config", }, ], diff --git a/.vitepress/sidebars/reference.ts b/.vitepress/sidebars/reference.ts index 3e078cf..6a99e86 100644 --- a/.vitepress/sidebars/reference.ts +++ b/.vitepress/sidebars/reference.ts @@ -31,13 +31,17 @@ export const referenceSidebar: DefaultTheme.SidebarItem[] = [ text: "Files", items: [ { - text: "manifest.json", - link: "/reference/manifest.md", + text: "caido.config.ts", + link: "/reference/config.md", }, { text: "plugin_packages.json", link: "/reference/plugin_packages.md", }, + { + text: "manifest.json", + link: "/reference/manifest.md", + }, ], }, ]; diff --git a/src/guides/config.md b/src/guides/config.md index 65eef44..eaeabfd 100644 --- a/src/guides/config.md +++ b/src/guides/config.md @@ -25,6 +25,7 @@ export default defineConfig({ kind: "frontend", id: "my-frontend", name: "My Frontend", + root: "packages/my-frontend", backend: { id: "my-backend" } @@ -33,11 +34,14 @@ export default defineConfig({ kind: "backend", id: "my-backend", name: "My Backend", + root: "packages/my-backend", } ] }); ``` +You can find more information about the `caido.config.ts` file in the [Config Reference](/reference/config) page. + ## Updating Package Details Most plugins will only need to update the `id`, `name`, `description`, `author`, and `version` fields. diff --git a/src/guides/distribution/repository.md b/src/guides/distribution/repository.md index 11956f6..fcd8c48 100644 --- a/src/guides/distribution/repository.md +++ b/src/guides/distribution/repository.md @@ -101,7 +101,7 @@ Now that your repository and key-pair are ready, it’s time to create a release 1. [Create a Github Action Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `PRIVATE_KEY` with the content of the private key generated in [step 3](#3-generate-a-key-pair). 1. Go to the `Actions` tab of your repository and trigger the `Release` workflow. -This will create a release with the version specified in your project's [manifest.json](/reference/manifest) file. +This will create a release with the version specified in your project's [caido.config.ts](/guides/config#version) file. Store release Github Workflow diff --git a/src/reference/config.md b/src/reference/config.md new file mode 100644 index 0000000..14cd834 --- /dev/null +++ b/src/reference/config.md @@ -0,0 +1,73 @@ +# caido.config.ts + +The `caido.config.ts` file is used to configure your package. + +```ts +import { defineConfig } from "@caido-community/dev"; + +export default defineConfig({ + id: "my-plugin", + name: "My Plugin", + description: "A plugin for Caido", + version: "0.0.0", + author: { + name: "Caido Labs Inc.", + email: "dev@caido.io", + url: "https://caido.io" + }, + plugins: [ + { + kind: "frontend", + id: "my-frontend", + name: "My Frontend", + root: "packages/my-frontend", + backend: { + id: "my-backend" + } + }, + { + kind: "backend", + id: "my-backend", + name: "My Backend", + root: "packages/my-backend", + } + ] +}); +``` + +## Global Options + +| Option | Type | Required | Description | +| --- | --- | --- | --- | +| id | `string` | Yes | Must be unique and must only consist of lowercase letters, numbers, hyphens and underscores (the order of which must satisfy the regex: `^[a-z]+(?:[_-][a-z0-9]+)*$`). | +| name | `string` | Yes | The name of your plugin. This is the name that will be displayed when a user installs your plugin. | +| description | `string` | Yes | The description of your plugin. This is the description that will be displayed when a user installs your plugin. | +| version | `string` | Yes | Represents the version of your plugin using [Semantic Versioning](https://semver.org/). | + +## Author Options + +| Option | Type | Required | Description | +| --- | --- | --- | --- | +| name | `string` | Yes | The name of the author of your plugin. | +| email | `string` | No | The email of the author of your plugin. | +| url | `string` | No | The URL of the author of your plugin. | + +## Frontend Plugin Options + +| Option | Type | Required | Description | +| --- | --- | --- | --- | +| kind | `"frontend"` | Yes | The kind of plugin. | +| id | `string` | Yes | The id of the plugin. | +| name | `string` | No | The name of the plugin. Defaults to the id. | +| root | `string` | Yes | The root directory of the frontend plugin. (e.g. `packages/my-frontend`) | +| backend.id | `string` | Yes | The id of the backend plugin that this frontend plugin is associated with. | +| vite | [`ViteConfig`](https://vite.dev/config/) | No | Additional Vite configuration for the frontend plugin. | + +## Backend Plugin Options + +| Option | Type | Required | Description | +| --- | --- | --- | --- | +| kind | `"backend"` | Yes | The kind of plugin. | +| id | `string` | Yes | The id of the plugin. | +| name | `string` | No | The name of the plugin. Defaults to the id. | +| root | `string` | Yes | The root directory of the backend plugin. (e.g. `packages/my-backend`) | diff --git a/src/reference/index.md b/src/reference/index.md index 4471cca..43dd19c 100644 --- a/src/reference/index.md +++ b/src/reference/index.md @@ -12,4 +12,6 @@ If you need a refresher on how a function works, or whether a certain feature is ## Files +- **[caido.config.ts](./config.md)** - caido.config.ts field definitions +- **[plugin_packages.json](./plugin_packages.md)** - plugin_packages.json field definitions - **[manifest.json](./manifest.md)** - Manifest.json field definitions