Framework Integration

OqronKit is a pure TypeScript package that is fundamentally framework-agnostic and runtime-agnostic. It does not rely on Next.js, Express, Hono, or any specific framework context.

You can drop OqronKit into a Next.js custom server, an Express backend, or a raw Bun HTTP server, and it will run exactly the same way.

However, when deploying to modern Serverless or Edge environments (like Vercel Edge or Cloudflare Workers), you must adapt your architecture to respect the execution limits of those platforms.

The "Edge" Architecture Challenge

Edge platforms are request-bound. This means they freeze or kill CPU execution the millisecond the HTTP response is sent back to the user.

Because OqronKit relies on long-running polling loops (e.g., pulling jobs from Redis every few seconds for a Queue or Worker), calling await oqron.start() inside a Serverless or Edge API route will cause the workers to be suspended as soon as the HTTP response finishes.

The Solution: Publisher / Consumer Pattern

To use OqronKit effectively in a serverless framework like Next.js or TanStack Start, you should split your application into a Publisher (your Next.js API routes) and a Consumer (a dedicated background worker).

1. The Publisher (Next.js / Edge)

In your Next.js application, you import your queues and interact with them without starting the Oqron engine. This allows your Edge routes to instantly push jobs to Redis/Postgres and return the HTTP response without trying to keep background loops alive.

import { emailQueue } from "@/oqron/queues";

export async function POST(req: Request) {
  const body = await req.json();

  // Instantly pushes the job to the database/Redis
  await emailQueue.add({ to: body.email });

  return Response.json({ success: true });
}

Notice that we did not call new Oqron().start() here. OqronKit's module factories (Queue(), Worker(), Cron()) lazy-load their definitions and can act as pure publishers.

2. The Consumer (Background Worker)

You then deploy a separate, long-running Node.js or Bun process (like a Docker container on Render, Railway, AWS ECS, or Fly.io) that imports the exact same queues, registers the handlers, and calls oqron.start().

import { Oqron } from "oqronkit";
import "@/oqron/queues"; // Ensures your handlers are registered

const oqron = new Oqron({
  mode: "redis",
  redis: process.env.REDIS_URL,
});

// Boot persistence + module engines (starts the polling loops).
// This keeps the process alive forever to process background tasks.
await oqron.start();

Framework Examples

Raw Bun / Node (Monolith)

If you aren't deploying to Serverless, you can run everything in the same process!

import { Oqron, Queue } from "oqronkit";

// 1. Define modules
const queue = Queue<{ id: string }>({
  name: "reports",
  handler: async (ctx) => {
    console.log("Processing", ctx.data.id);
  },
});

// 2. Start the background engine
const oqron = new Oqron({ mode: "memory" });
await oqron.start();

// 3. Start your web server
const server = Bun.serve({
  port: 3000,
  async fetch() {
    await queue.add({ id: "123" });
    return new Response("Job queued!");
  },
});

Express.js

import express from "express";
import { Oqron } from "oqronkit";
import { myQueue } from "./queues.js";

const app = express();

app.post("/jobs", async (req, res) => {
  await myQueue.add({ task: "do something" });
  res.send("Queued");
});

const oqron = new Oqron({ mode: "redis", redis: process.env.REDIS_URL });

app.listen(3000, async () => {
  // Start the background processors when the server boots
  await oqron.start();
  console.log("Server and Background workers running on port 3000");
});

WinterCG Compliance

The core of OqronKit is designed to be highly portable. It relies almost exclusively on standard JavaScript primitives (setTimeout, setInterval, Promise) that run perfectly in Bun, Deno, and standard Edge environments.

We are constantly monitoring Edge/WinterCG compliance to ensure you can run OqronKit's publisher client anywhere.