Nuxt

since: 1.7

@runwisp/js runs scheduled tasks inside your Nuxt server, in nuxi dev and in the built .output/server. It needs a process that keeps running, so nuxi build fails with serverless, edge or static presets, and so does nuxi generate.

It works with Nuxt 3.7 or later, including Nuxt 4, on Node.js or on Bun. Nitro’s scheduled tasks need Nitro 2.9 or later, which every fresh Nuxt 3 install gets.

Set up

npm install @runwisp/js

Add the module:

nuxt.config.ts

export default defineNuxtConfig({
    modules: ["@runwisp/js/nuxt"],
});

The module copies the runwisp binary into the build, and lets running tasks finish before the built server exits.

To set new RunWisp() options, put them under the runwisp key:

nuxt.config.ts

export default defineNuxtConfig({
    modules: ["@runwisp/js/nuxt"],
    runwisp: { data: "/var/lib/my-app/runwisp", port: 9500 },
});

The options are written into the server build, so the module takes every option except password, log and exitOnSignal. Set the password with RUNWISP_PASSWORD where the server runs.

Define tasks

Register tasks in a Nitro plugin. Nitro runs it once when the server starts:

server/plugins/tasks.ts

import { RunWisp } from "@runwisp/js";
import { options } from "#runwisp/nuxt";

export default defineNitroPlugin(() => {
    // nuxi build runs the plugins to prerender pages.
    if (import.meta.prerender) return;
    const runwisp = new RunWisp(options);

    runwisp.task("cleanup-sessions", { cron: "0 * * * *" }, async () => {
        const removed = await cleanupSessions();
        console.log(`removed ${removed} expired sessions`);
    });
});

options holds the module’s options, so every plugin gets the same RunWisp. The server prints the dashboard address on startup. Callbacks can use server utils and useRuntimeConfig(). See the JavaScript SDK for every task option.

When you edit server code in dev, Nitro reloads the plugin with the new code. RunWisp keeps running and keeps the run history.

Nitro scheduled tasks

With the module, Nitro’s scheduledTasks run under RunWisp instead of Nitro’s scheduler. Keep your config and your server/tasks/ files as they are:

nuxt.config.ts

export default defineNuxtConfig({
    modules: ["@runwisp/js/nuxt"],
    nitro: {
        experimental: { tasks: true },
        scheduledTasks: { "0 * * * *": ["db:cleanup"] },
    },
});

Each scheduled Nitro task becomes a RunWisp task with the same name. What it prints goes to the run’s log, and a task that throws fails the run. A task listed under a second schedule is named db:cleanup-2, and so on.

As under Nitro’s scheduler, times missed while the server was down are not run late, and a run that comes while the task is still running is skipped. The tasks get catch_up = 0 and on_overlap = "skip".

Build for production

Build on the platform you deploy to, for example inside your Docker image. The binary is installed for the machine that runs npm install.

The data directory is .runwisp in the directory you start the server from. Start node .output/server/index.mjs from the project root, or set data, since nuxi build replaces .output and anything in it.

Bun

Build with the bun preset and start the server with Bun:

NITRO_PRESET=bun nuxi build
bun .output/server/index.mjs