📦 Publishing a Package

This guide walks you through publishing a quality package on Beepack.

Before You Publish: Check for Duplicates

Before publishing a new package, always search first to check if a similar package already exists:

beepack search "your package description"

If a similar package exists, consider using the suggestion system to propose improvements instead of publishing a duplicate:

beepack suggest existing-package "Add support for feature X"

This keeps the ecosystem clean and helps existing packages improve rather than fragmenting effort.

Requirements

• English only - All package names, descriptions, READMEs, and documentation must be written in English. This ensures discoverability for the global community.
• displayName required - Your HIVE.yaml must include a displayName field with a human-readable name for your package (e.g., displayName: "Notion Sync").
• A GitHub account created more than 14 days ago
• Beepack CLI installed: npm install -g @actabi/beepack

Recommended Structure

my-package/
├── HIVE.yaml          # Configuration (REQUIRED)
├── README.md          # Documentation (highly recommended)
├── src/
│   ├── index.ts       # Entry point
│   └── utils.ts       # Utilities
├── tests/
│   └── index.test.ts  # Tests
├── examples/
│   ├── basic.ts       # Simple example
│   └── advanced.ts    # Advanced example
└── LICENSE            # License (optional, MIT-0 by default)

1. Create the HIVE.yaml

The most important file. See the complete format guide.

name: my-api
displayName: "My API"
version: 1.0.0
description: Clear and concise description

keywords:
  - keyword-1
  - keyword-2

capabilities:
  - main_action
  - other_action

requires:
  env:
    - REQUIRED_API_KEY

compatible:
  - cursor
  - copilot
  - claude

2. Write a Good README

A quality README significantly increases adoption. Include:

• Description - What does it do?
• Installation - How to install
• Configuration - Environment variables
• Examples - Working code
• API - Function reference

3. Add Tests

Packages with tests get a "tested" badge and inspire more trust.

# In HIVE.yaml
tests:
  command: npm test
  coverage_min: 70

4. Publish

# Login (once)
beepack login

# Publish
beepack publish

Best Practices

✅ Do

• Use descriptive names
• Declare ALL required env vars
• Include working examples
• Write tests
• Update changelog with each version

❌ Don't

• Hardcode secrets
• Forget to document
• Publish untested code
• Use undeclared dependencies
• Publish duplicates - use beepack suggest to improve existing packages
• Write descriptions in languages other than English
• Omit the displayName field in HIVE.yaml

Contributing to Existing Packages

If you find a package that could be improved, use the suggestion system instead of publishing a duplicate:

# Suggest an improvement
beepack suggest package-slug "Description of your suggestion"

# View suggestions for a package
beepack suggestions package-slug

The package author will be notified and can accept or decline your suggestion. Other users can like or dislike suggestions to help prioritize them.

Security Scanning

When you publish a package, it goes through Beepack's 3-layer security pipeline automatically:

1. Static scan (immediate) - Your code is analyzed for dangerous patterns such as eval(), child_process usage, credential harvesting, and data exfiltration. If malicious patterns are detected, the publish is blocked immediately and you will receive an error message explaining why.
2. LLM evaluation (async) - After successful publish, an AI-powered analysis runs in the background to detect more subtle threats like obfuscated code, hidden network calls, or social engineering patterns. If issues are found, your package may be flagged for manual review.
3. Community reports (ongoing) - After publishing, the community can report suspicious behavior. If 3 independent users report your package, it is automatically hidden pending review.

You can check your package's security status at any time:

GET https://beepack.ai/api/v1/packages/{slug}/security

After Publishing

Your package is immediately available:

# Others can install it
beepack install your-username/my-package

# And find it via search
beepack search "your package description"