🤝 Contributing to Packages

The Suggestion System

Instead of forking or publishing a duplicate package, you can submit a suggestion to the package owner. Suggestions can include a title, a description of the improvement, and optionally a code diff showing the proposed changes.

This keeps the ecosystem clean by consolidating effort on existing packages rather than fragmenting it across duplicates.

Submitting a Suggestion

Via the CLI

beepack suggest notion-sync "Add support for database relations"

Via the API

POST /api/v1/packages/notion-sync/suggestions
Content-Type: application/json

{
  "title": "Add support for database relations",
  "description": "Currently the sync only handles simple properties. This adds support for relation and rollup fields, enabling linked database workflows.",
  "codeDiff": "--- a/src/sync.ts\n+++ b/src/sync.ts\n@@ -45,6 +45,12 @@\n+  if (prop.type === 'relation') {\n+    return resolveRelation(prop.relation);\n+  }"
}

The codeDiff field is optional but highly encouraged - it makes your suggestion actionable and easier for the package owner to review.

Reviewing Suggestions (Package Owners)

As a package owner, you receive notifications when someone submits a suggestion. You can accept or reject it:

Via the CLI

# View suggestions for your package
beepack suggestions my-package

# Accept a suggestion
beepack suggestion accept <suggestion-id>

# Reject a suggestion
beepack suggestion reject <suggestion-id>

Via the API

PATCH /api/v1/suggestions/:id
Content-Type: application/json

{
  "status": "accepted"
}

Valid status values are "accepted" and "rejected". Accepted suggestions signal to the community that the improvement will be incorporated.

The Like/Dislike System

Every package on Beepack can be rated by the community using likes and dislikes. This helps surface high-quality packages and gives feedback to authors.

# Like a package
beepack like notion-sync

# Dislike a package
beepack dislike notion-sync

Likes and dislikes influence search rankings - packages with more community support appear higher in results.

Duplicate Detection

When you attempt to publish a package, Beepack's server automatically checks for similar existing packages. If a close match is found, the server returns a 409 Conflict response:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "Similar package already exists",
  "similar": {
    "slug": "notion-sync",
    "description": "Bidirectional sync with Notion API",
    "similarity": 0.92
  },
  "suggestion": "Consider using 'beepack suggest notion-sync' to propose improvements instead."
}

This prevents ecosystem fragmentation and encourages collaboration on existing packages.

Best Practices

Before Publishing a New Package

• Search first - Run beepack search "your idea" to check if a similar package already exists
• Suggest improvements - If a similar package exists but lacks a feature you need, use beepack suggest instead of publishing a duplicate
• Include a code diff - When submitting a suggestion, include a codeDiff to make it easy for the owner to act on your idea

As a Package Owner

• Review suggestions promptly - Timely responses encourage more community contributions
• Accept good ideas - Even if the code diff needs adjustments, accepting the suggestion signals your intent to improve
• Acknowledge contributors - Mention contributors in your changelog or README