From fc54e558ce95be0ad0180721a183a0f158ee0771 Mon Sep 17 00:00:00 2001 From: Michelle Bergeron Date: Mon, 2 Jun 2025 11:16:59 -0400 Subject: [PATCH 1/5] updates --- .../components/contributing/guidelines.mdx | 42 ++++++++++++------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/docs-v2/pages/components/contributing/guidelines.mdx b/docs-v2/pages/components/contributing/guidelines.mdx index 90ac12b4c56e3..e8ab4fb053491 100644 --- a/docs-v2/pages/components/contributing/guidelines.mdx +++ b/docs-v2/pages/components/contributing/guidelines.mdx @@ -116,7 +116,8 @@ scoped components are easier for users to understand and use. Registry [components](/components/contributing/api/#component-structure) require a unique `key` and `version`, and a friendly `name` and `description`. Action components require a `type` field to be set to `action` (sources will require a type to be -set in the future). +set in the future). Action components require the description to include a link to the +relevant documentation in the following format: \[See the documentation\](https://xxx) ```javascript export default { @@ -160,6 +161,9 @@ to the registry, the version should be `0.0.1`. If the action was at version `0.1.0` and you've fixed a bug, change it to `0.1.1` when committing your final code. +If you update a file, you must increment the versions of all components that +import or are affected by the updated file. + ### Folder Structure Registry components are organized by app in the `components` directory of the @@ -168,26 +172,28 @@ Registry components are organized by app in the `components` directory of the ```text /components /[app-name-slug] - /[app-name-slug].app.js + /[app-name-slug].app.mjs /actions /[action-name-slug] - /[action-name-slug].js + /[action-name-slug].mjs /sources /[source-name-slug] - /[source-name-slug].js + /[source-name-slug].mjs ``` - The name of each app folder corresponds with the name slug for each app - The app file should be in the root of the app folder (e.g., - `/components/[app_slug]/[app_slug].app.js`) + `/components/[app_slug]/[app_slug].app.mjs`) - Components for each app are organized into `/sources` and `/actions` subfolders - Each component should be placed in its own subfolder (with the name of the folder and the name of the `js` file equivalent to the slugified component name). For example, the path for the "Search Mentions" source for Twitter is - `/components/twitter/sources/search-mentions/search-mentions.js`. + `/components/twitter/sources/search-mentions/search-mentions.mjs`. - Aside from `app_slug`, words in folder and file names are separated by dashes (-) (i.e., in kebab case) +- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed withing a common + folder: `/common/common.mjs`. You can explore examples in the [components directory](https://github.com/PipedreamHQ/pipedream/tree/master/components). @@ -329,7 +335,7 @@ If users are required to enter sensitive data, always use App files contain components that declare the app and include prop definitions and methods that may be reused across components. App files should adhere to the -following naming convention: `[app_name_slug].app.js`. If an app file does not +following naming convention: `[app_name_slug].app.mjs`. If an app file does not exist for your app, please [reach out](https://pipedream.com/community/c/dev/11). @@ -402,18 +408,20 @@ with this approach is that it increases complexity for end-users who have the option of customizing the code for components within Pipedream. When using this approach, the general pattern is: -- The `.app.js` module contains the logic related to making the actual API calls +- The `.app.mjs` module contains the logic related to making the actual API calls (e.g. calling `axios.get`, encapsulate the API URL and token, etc). -- The `common.js` module contains logic and structure that is not specific to +- The `common.mjs` module contains logic and structure that is not specific to any single component. Its structure is equivalent to a component, except that it doesn't define attributes such as `version`, `dedupe`, `key`, `name`, etc (those are specific to each component). It defines the main logic/flow and relies on calling its methods (which might not be implemented by this component) to get any necessary data that it needs. In OOP terms, it would be the equivalent of a base abstract class. -- The component module of each action would inherit/extend the `common.js` +- The component module of each action would inherit/extend the `common.mjs` component by setting additional attributes (e.g. `name`, `description`, `key`, etc) and potentially redefining any inherited methods. +- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed withing a common + folder: `/common/common.mjs`. See [Google Drive](https://github.com/PipedreamHQ/pipedream/tree/master/components/google_drive) @@ -424,15 +432,13 @@ Please note that the name `common` is just a convention and depending on each case it might make sense to name any common module differently. For example, the [AWS sources](https://github.com/PipedreamHQ/pipedream/tree/master/components/aws) -contains a `common` directory instead of a `common.js` file, and the directory +contains a `common` directory instead of a `common.mjs` file, and the directory contains several modules that are shared between different event sources. ## Props -As a general rule of thumb, we should strive to only incorporate the 3-4 most -relevant options from a given API as props. This is not a hard limit, but the -goal is to optimize for usability. We should aim to solve specific use cases as -simply as possible. +As a general rule of thumb, we should strive to incorporate all +relevant options from a given API as props. ### Labels @@ -445,7 +451,7 @@ but its label is set to “Search Term”. ### Descriptions -Include a description for [props](/components/contributing/api/#user-input-props) if it helps +Include a description for [props](/components/contributing/api/#user-input-props) to help the user understand what they need to do. Use Markdown as appropriate to improve the clarity of the description or instructions. When using Markdown: @@ -781,6 +787,10 @@ know the content being returned is likely to be large – e.g. files — don't export the full content. Consider writing the data to the `/tmp` directory and exporting a reference to the file. +## Miscellaneous + +- Use cammelCase for all props, method names, and variables. + ## Database Components Pipedream supports a special category of apps called ["databases"](/workflows/data-management/databases/), From 4f86177a4247c6a79145bda002038a80c758a5e4 Mon Sep 17 00:00:00 2001 From: Michelle Bergeron Date: Mon, 2 Jun 2025 11:17:44 -0400 Subject: [PATCH 2/5] pnpm-lock.yaml --- pnpm-lock.yaml | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 973048a2c3d75..2a86d5959b035 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -367,8 +367,7 @@ importers: specifier: ^1.2.1 version: 1.6.6 - components/adtraction: - specifiers: {} + components/adtraction: {} components/adversus: dependencies: @@ -3739,8 +3738,7 @@ importers: components/dokan: {} - components/dolibarr: - specifiers: {} + components/dolibarr: {} components/domain_group: dependencies: @@ -7373,8 +7371,7 @@ importers: specifier: ^3.0.0 version: 3.0.3 - components/limoexpress: - specifiers: {} + components/limoexpress: {} components/line: dependencies: @@ -9884,8 +9881,7 @@ importers: specifier: ^1.5.1 version: 1.6.6 - components/pinghome: - specifiers: {} + components/pinghome: {} components/pingone: {} @@ -10380,8 +10376,7 @@ importers: components/procore_sandbox: {} - components/prodatakey: - specifiers: {} + components/prodatakey: {} components/prodpad: dependencies: @@ -15054,8 +15049,7 @@ importers: specifier: ^3.0.3 version: 3.0.3 - components/zenedu: - specifiers: {} + components/zenedu: {} components/zenkit: dependencies: From c29225ad4272a8e13d740760fd5eae15d9f68297 Mon Sep 17 00:00:00 2001 From: Michelle Bergeron Date: Mon, 2 Jun 2025 11:26:41 -0400 Subject: [PATCH 3/5] fix typo --- docs-v2/pages/components/contributing/guidelines.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-v2/pages/components/contributing/guidelines.mdx b/docs-v2/pages/components/contributing/guidelines.mdx index e8ab4fb053491..56849b5e6323b 100644 --- a/docs-v2/pages/components/contributing/guidelines.mdx +++ b/docs-v2/pages/components/contributing/guidelines.mdx @@ -789,7 +789,7 @@ exporting a reference to the file. ## Miscellaneous -- Use cammelCase for all props, method names, and variables. +- Use camelCase for all props, method names, and variables. ## Database Components From cd8c997ebdb3525974783088bdd16e507404ba7f Mon Sep 17 00:00:00 2001 From: michelle0927 Date: Mon, 2 Jun 2025 11:32:47 -0400 Subject: [PATCH 4/5] Update docs-v2/pages/components/contributing/guidelines.mdx Co-authored-by: Jorge Cortes --- docs-v2/pages/components/contributing/guidelines.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-v2/pages/components/contributing/guidelines.mdx b/docs-v2/pages/components/contributing/guidelines.mdx index 56849b5e6323b..d24ef99e1456c 100644 --- a/docs-v2/pages/components/contributing/guidelines.mdx +++ b/docs-v2/pages/components/contributing/guidelines.mdx @@ -117,7 +117,7 @@ Registry [components](/components/contributing/api/#component-structure) require `key` and `version`, and a friendly `name` and `description`. Action components require a `type` field to be set to `action` (sources will require a type to be set in the future). Action components require the description to include a link to the -relevant documentation in the following format: \[See the documentation\](https://xxx) +relevant documentation in the following format: \[See the documentation\](https://public-api.com) ```javascript export default { From c3fa374b71675afa349451e7f42d3ca78fd34cde Mon Sep 17 00:00:00 2001 From: Michelle Bergeron Date: Mon, 2 Jun 2025 11:34:44 -0400 Subject: [PATCH 5/5] typos --- docs-v2/pages/components/contributing/guidelines.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-v2/pages/components/contributing/guidelines.mdx b/docs-v2/pages/components/contributing/guidelines.mdx index d24ef99e1456c..79d58d3794d2d 100644 --- a/docs-v2/pages/components/contributing/guidelines.mdx +++ b/docs-v2/pages/components/contributing/guidelines.mdx @@ -192,7 +192,7 @@ Registry components are organized by app in the `components` directory of the `/components/twitter/sources/search-mentions/search-mentions.mjs`. - Aside from `app_slug`, words in folder and file names are separated by dashes (-) (i.e., in kebab case) -- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed withing a common +- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed within a common folder: `/common/common.mjs`. You can explore examples in the [components @@ -420,7 +420,7 @@ approach, the general pattern is: - The component module of each action would inherit/extend the `common.mjs` component by setting additional attributes (e.g. `name`, `description`, `key`, etc) and potentially redefining any inherited methods. -- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed withing a common +- Common files (e.g., `common.mjs`, `utils.mjs`) must be placed within a common folder: `/common/common.mjs`. See [Google