DOCSEARCHbyAlgolia
Submit Docs

Quirrel Documentation

website·Indexed 33 days ago

https://docs.quirrel.dev/

Documentation for Quirrel, a tool for managing queues and CronJobs across various frameworks including Next.js, Remix, SvelteKit, Nuxt, Netlify, Vercel, Blitz.js, Redwood, and Express. Includes guides on local development, self-hosting via Docker, Railway, and Fly.io, and migration paths to v1.

Tokens
8.1K
Snippets
57
Records
75
Agent score
60%

What's inside Quirrel

  1. Overview of Quirrel job queueing service

    Quirrel is a job queueing service designed specifically for serverless environments. It is used to handle asynchronous tasks that are difficult to manage in serverless functions, such as delaying tasks, distributing large batches of tasks across multiple lambdas for parallel execution, scheduling delayed emails (e.g., a one-week follow-up after signup), and executing tasks on a cron schedule. It supports various frameworks, including Next.js and Blitz.

  2. Understand the Quirrel job execution lifecycle

    Quirrel operates as a scheduled callback service. The typical workflow is:

    1. The application sends a request to the Quirrel server specifying a delay, a callback URL (e.g., https://my-application.com/api/queues/myQueue), and a payload.
    2. Quirrel hands the job to its internal scheduler.
    3. Once the delay expires, the scheduler returns the job to the Quirrel server.
    4. The Quirrel server sends an HTTP request to the specified callback URL with the original payload.
    5. The application receives and executes the job.

  3. Create a job queue in a Netlify Function

    Use the Queue function from quirrel/netlify to create a job queue. The queue must be exported from a Netlify Function to operate correctly. The Queue function initializes a worker that processes job payloads asynchronously.
    import { Queue } from "quirrel/netlify";

export const handler = Queue(
  ".netlify/functions/someQueue",
  async (job, meta) => {
    // Process the job payload here
    console.log("Processing job:", job);
  }
);

export default handler;

  4. Complete the Quirrel server migration process

    After configuring the migration environment variables, follow these steps to finalize the transition:

    1. Run quirrel ci to transfer Cron Jobs to the new instance.
    2. Monitor the Stats page on https://ui.quirrel.dev to verify when the old instance has fully drained (all pending jobs are processed).
    3. Once the old instance is empty, remove the QUIRREL_MIGRATE_OLD_API_URL and QUIRREL_MIGRATE_OLD_TOKEN environment variables from your application.

  5. Access the Quirrel local admin interface

    During local development, you can launch a dedicated admin interface to manage and monitor your local Quirrel setup.
    quirrel ui

  7. Deploy Quirrel CronJobs via CI

    When using CronJobs(), you must run the quirrel ci command during your deployment process. Ensure that QUIRREL_API_URL, QUIRREL_TOKEN, and QUIRREL_BASE_URL are set in the environment when this command executes.
    "scripts": { "build": "npm run build && quirrel ci" }

  8. Create a job queue in SvelteKit

    Use the Queue function from quirrel/sveltekit to create a background job queue. The queue must be exported as a SvelteKit server route (e.g., in a +server.ts file) via export const POST or export default to be reachable by the worker.
    import { Queue } from "quirrel/sveltekit";

const queue = Queue(
  "greetingsQueue", // The route it's reachable on
  async (job, meta) => {
    // Job processing logic here
  }
);

export const POST = queue;
export default queue;

  9. Migrate Next.js project to Quirrel v1

    To migrate a Next.js project to Quirrel v1, you must replace the deprecated @quirrel/next package with quirrel/next and update Queue route strings to include the api/ prefix.
    # 1. Uninstall the deprecated package
npm uninstall @quirrel/next

# 2. Install the latest version
npm install --save-prod quirrel@latest
    // 3. Update imports and route strings in your Queue files
import { Queue } from "quirrel/next";

export default Queue(
  "api/someQueue", // Add 'api/' prefix to the route string
  async () => {
    // ...
  }
);

  10. Run the Quirrel local development server

    Quirrel provides a lightweight local server that runs entirely on your machine without requiring external databases or services. It automatically scans your project for CronJobs and detects the local server port of your framework (e.g., port 3000 for Next.js).
    # Install Quirrel
npm install quirrel

# Start the local server
quirrel

  11. Connect the Quirrel Development UI to a local instance

    The Quirrel development UI (ui.quirrel.dev) connects directly to a local development instance to display pending jobs. By default, the UI attempts to connect to localhost:9181. Real-time updates are handled via websockets by subscribing to an activity log.

  12. Register CronJobs during deployment

    While local Quirrel instances detect CronJob() calls by watching the source directory, production deployments require manual registration. Run the quirrel ci command during your deployment process to register cron jobs.
    quirrel ci