Contributing

​

Local Development Setup

​

Clone the Repository

First, clone the Unhook repository and install dependencies:

git clone https://github.com/unhook-sh/unhook.git
cd unhook
npm install

​

Start the Development Server

Run the development server locally:

npm run dev

This will start:

• The CLI webhook service on port 3000
• The web dashboard on port 3001
• The webhook processing service on port 3002

​

Project Structure

unhook/
├── packages/
│   ├── cli/          # Command line interface
│   ├── core/         # Core webhook processing logic
│   ├── dashboard/    # Web dashboard (Next.js)
│   └── shared/       # Shared utilities and types
├── examples/         # Example integrations
└── docs/            # Documentation

​

Development Workflow

​

Running Tests

We use Jest for testing. Run the test suite with:

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests for a specific package
npm test -- packages/cli

​

Linting and Formatting

We use ESLint and Prettier to maintain code quality:

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

​

Building Locally

To build all packages:

npm run build

To build a specific package:

npm run build --workspace=@unhook/cli

​

Running Examples

We provide example integrations in the examples/ directory. To run an example:

# Navigate to an example
cd examples/stripe-webhook

# Install dependencies
npm install

# Start the example
npm run dev

​

Debugging

​

CLI Debugging

Run the CLI with debug logging:

# Using npm
npm run dev:cli -- --debug

# Direct binary
./packages/cli/bin/run --debug

​

Dashboard Debugging

The dashboard includes React Developer Tools and runs in development mode by default:

# Start dashboard in development mode
npm run dev:dashboard

​

Common Issues

​

Contributing

We welcome contributions! Here’s how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your branch: git push origin feature/amazing-feature
7. Open a Pull Request

​

Contribution Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation for changes
• Keep commits focused and atomic
• Write clear commit messages

​

Next Steps