guide ยท hono
Background jobs for Hono.
Return the HTTP response now, do the slow work later. This guide wires bunqueue into Hono: enqueue from routes, process in a worker, check job status, shut down cleanly.
This guide shows how to run background jobs, work your server does after the HTTP response is sent, inside a Hono app. Everything runs in one process using bunqueue's **embedded mode**, configured with `dataPath` so jobs are stored in a local SQLite file instead of a separate queue server.
:::note[Runtime]
This guide runs Hono on Bun with the Bun `bunqueue` package; embedded mode is Bun-only. Running Hono on Node.js or Deno? Start a bunqueue server and use `bunqueue-client` instead, the route and worker code is otherwise the same (see [SDKs](/guide/sdks/)).
:::
## Minimal working app
Copy, run with `bun run app.ts`, done:
```typescript
import { Hono } from 'hono';
import { Queue, Worker, shutdownManager } from 'bunqueue/client';
// Queue: where jobs wait. Worker: runs your function on each job.
const storage = { embedded: true, dataPath: './data/bunq.db' } as const;
const emails = new Queue('emails', storage);
new Worker(
'emails',
async (job) => {
console.log('sending to', job.data.to);
// await sendEmail(job.data);
return { sent: true };
},
{ ...storage, concurrency: 3 }
); // 3 jobs in parallel
const app = new Hono();
app.post('/api/send-email', async (c) => {
const body = await c.req.json();
const job = await emails.add('send', body, {
attempts: 3, // retry up to 3 times on failure
backoff: 5000, // wait 5s (then longer) between retries
});
return c.json({ queued: true, jobId: job.id });
});
process.on('SIGINT', () => {
shutdownManager();
process.exit(0);
});
export default app;
```
The route responds immediately. The worker sends the email in the background and retries automatically if it throws.
:::caution[Embedded mode required]
Every example uses `embedded: true`. Without it, bunqueue tries to connect to a TCP server. Also create each `Queue` once at module level, not inside a request handler.
:::
## Common tasks
### Let clients check job status
Return the job id from the enqueue route, then expose a status endpoint. `job.progress` is a 0-100 number your worker sets, `returnvalue` is what your worker returned, `failedReason` is the last error message:
```typescript
app.get('/api/jobs/:id', async (c) => {
const job = await emails.getJob(c.req.param('id'));
if (!job) return c.json({ error: 'Job not found' }, 404);
return c.json({
id: job.id,
name: job.name,
progress: job.progress,
result: job.returnvalue ?? null,
error: job.failedReason ?? null,
});
});
```
### Report progress from the worker
```typescript
new Worker(
'reports',
async (job) => {
await job.updateProgress(10, 'Fetching data');
const data = await fetchData(job.data);
await job.updateProgress(80, 'Rendering PDF');
const url = await renderPdf(data);
return { url };
},
{ embedded: true, dataPath: './data/bunq.db' }
);
```
### Expose queue stats
`getJobCounts()` is synchronous in embedded mode and returns counts per state (`waiting`, `active`, `completed`, `failed`, `delayed`):
```typescript
app.get('/api/queues/emails/stats', (c) => c.json(emails.getJobCounts()));
```
### React to job results
```typescript
const worker = new Worker('emails', processor, {
embedded: true,
dataPath: './data/bunq.db',
});
worker.on('completed', (job, result) => console.log('done', job.id));
worker.on('failed', (job, err) => console.error('failed', job.id, err.message));
```
### Share queues through typed middleware
For larger apps, put queues on Hono's context so every route gets them typed:
```typescript
import { Hono } from 'hono';
import type { MiddlewareHandler } from 'hono';
import { Queue } from 'bunqueue/client';
const queues = {
emails: new Queue('emails', { embedded: true, dataPath: './data/bunq.db' }),
reports: new Queue('reports', { embedded: true, dataPath: './data/bunq.db' }),
};
type Env = { Variables: { queues: typeof queues } };
const queueMiddleware: MiddlewareHandler