Local Development

Task endpoints you implement are plain HTTP endpoints, making local development and testing significantly simpler compared to traditional message queues and job scheduling systems. You can test your endpoints using familiar HTTP tools and test frameworks you're already using in your project.

Development Approaches

While basic testing is straightforward, this guide covers additional steps needed to test Taskhook's advanced features like scheduling, retries, and webhooks during development.

Taskhook supports several approaches for local development:

1. Direct HTTP Testing

   • Test your callback endpoints directly, bypassing Taskhook
   • Invoke scheduled tasks without workarounds or waiting for the scheduler
   • Use tools you already know (Postman, curl)

2. Localhost Tunneling

   • Enables full Taskhook functionality with webhooks
   • Handle real Taskhook calls on localhost
   • Recommended for local integration and end-to-end testing and debugging

3. Local Emulator (Coming soon)

   • Full Taskhook features in local environment
   • Simulates scheduling, retries, and delivery guarantees
   • For integration or e2e testing on CI/CD pipelines

Direct HTTP Testing

Instead of waiting for Taskhook to call your endpoints, test them directly. This approach is particularly useful for:

• Testing scheduled tasks without waiting for triggers
• Quick iteration during development
• Integration tests with your existing test suite
• Offline development and testing

Localhost Tunneling

For full webhook functionality during development, expose your local server using a tunneling service.

Using ngrok

1. Install ngrok:

npm install -g ngrok
# or
brew install ngrok

2. Start your tunnel:

ngrok http 3000  # Replace 3000 with your local server port

3. Use the provided URL in your client Taskhook configuration:

const client = new TaskhookClient('your_api_key', {
  taskhookBaseUrl: 'https://a1b2-c3d4.ngrok.io',
})

Using localtunnel

An alternative to ngrok:

npx localtunnel --port 3000 # Replace 3000 with your local server port

Use the provided URL in your client Taskhook configuration similar to above ngrok example.

Task Organization

Environment Tags

Use tags to separate different environments (learn more about tags):

const client = new TaskhookClient('your_api_key', {
  tags: 'development', // To apply to all tasks created by this client instance
})

client.tasks.create({
  ...
  tags: 'development', // To apply to a specific task
})

Trace IDs with Tags

Trace IDs help track related requests through your system. In Taskhook, implement trace IDs using tags:

// Add multiple tags to a task
client.createTask({
  ...
  tags: [
    'development',
    'payment-processing',
    'trace:order-123',
    'trace:customer-456',
  ],
})

Use the Taskhook dashboard to filter and search tasks by their trace IDs and other tags.

Best Practices

• Tag all requests with environment name
• Use trace IDs to keep track of complex workflows on the dashboard
• Use environment variables for configuration (API keys, URLs, environment tags)

Local Emulator

A local emulator that has full Taskhook features is coming soon. This will enable complete integration with automatic scheduling, delays, retries, etc. testing locally, or in CI/CD, offline.