Local Development

This guide walks you through setting up and using the DispatchedJS CLI for local development environments. For more information, follow the CLI documentation.

Getting Started

Installation

Install the DispatchedJS CLI globally using npm:

npm install -g @dispatchedjs/cli

Basic Configuration

Start the local development server with the following command:

dispatchedjs listen --secret="dev-webhook-secret" --forward="http://localhost:3000/webhook"

Key configuration options:

• --secret: Webhook verification secret (use a development-specific value, can be anything like abc123)
• --forward: Your local webhook endpoint URL of your application
• --port: Port for the CLI server (defaults to 3100)

Common Development Scenarios

API Keys when dispatching jobs

For local development, API keys are ignored. You can use any value for the Authorization when dispatching jobs.

Testing Webhook Processing

// Example webhook handler
app.post('/webhook', (req, res) => {
  // Verify webhook secret
  const authHeader = req.headers.authorization;
  if (authHeader !== `Bearer ${process.env.WEBHOOK_SECRET}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process webhook payload
  const { jobId, payload } = req.body;
  console.log(`Processing local job ${jobId}`, payload);

  res.status(200).json({ success: true });
});

Consider using our JavaScript SDK for easier integration.

Local Environment Setup

1. Create a .env.local file:

WEBHOOK_SECRET=dev-webhook-secret

2. Configure your development server:

require('dotenv').config({ path: '.env.local' });

const express = require('express');
const app = express();

app.use(express.json());

Consider using our JavaScript SDK for easier integration.

Important Notes

Local Processing Behavior

When using the local development server:

• Scheduled jobs are processed immediately
• There is not re-trying mechanism
• Webhook timeouts are not enforced
• API keys are not validated when dispatching jobs (or for any API calls)

Security Considerations

For local development:

• Use different secrets than production
• Don't commit development secrets
• Be cautious with sensitive data

Best Practices

1. Environment Separation

const config = {
  webhookSecret: process.env.NODE_ENV === 'development'
    ? process.env.DEV_WEBHOOK_SECRET
    : process.env.PROD_WEBHOOK_SECRET
};

2. Error Handling

app.post('/webhook', async (req, res) => {
  try {
    await processWebhook(req.body);
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Local webhook processing failed:', error);
    res.status(500).json({
      error: isDevelopment ? error.message : 'Internal error'
    });
  }
});

Consider using our JavaScript SDK for easier integration.

3. Request Validation

const validateWebhook = (payload) => {
  const required = ['jobId', 'payload', 'attemptId'];
  const missing = required.filter(field => !(field in payload));

  if (missing.length > 0) {
    throw new Error(`Missing required fields: ${missing.join(', ')}`);
  }
};

Consider using our JavaScript SDK for easier integration. Validation comes out of the box.

Troubleshooting

Common Issues

1. CLI Server Won't Start

• Check port availability
• Verify CLI installation
• Confirm Node.js version

2. Webhook Not Received

• Verify forward URL
• Check network settings
• Confirm webhook secret

3. Processing Failures

• Enable verbose logging
• Check payload format
• Verify handler logic

Next Steps

• Review the Troubleshooting Guide for more debugging tips
• Explore API Documentation for integration details

CLI Reference

Complete CLI options:

dispatchedjs [action]

Actions:
  listen [options]      Start the local development server

Options:
  --secret    Webhook verification secret
  --forward   Local webhook endpoint URL
  --port      Server port (default: 3100)
  --verbose   Enable detailed logging
  --help      Show help information