Frequently Asked Questions (FAQ)

This page offers answers to some of the most common questions about Sidequest.js. If you have a question that isn't covered here, we ask you to take a closer look at the documentation - usually your question is answered there. However, if you still haven't got an answer to your doubt, please feel free to open an issue.

What is Sidequest.js?

Sidequest is an open-source, modern, scalable distributed background job processor for Node.js applications.

What is a Queue?

Each queue is a separate logical channel, with its own concurrency, priority, and state configuration.

More info: Queues Documentation

What is a Job?

A job in Sidequest.js is a unit of work that can be executed asynchronously. Jobs are stored in a backend (database) and processed by workers in a queue-based system.

More info: Jobs Documentation

Can I use Sidequest without a dashboard?

Absolutely. To do so, pass a configuration object to the Sidequest.start with the dashboard.enabled property set to false.

await Sidequest.start({
  dashboard: {
    enabled: false,
  },
});

More info: Dashboard Documentation

Can I use Sidequest without processing jobs - no workers?

Yes, you can start Sidequest without processing jobs by using Sidequest.configure(...). This will enable you to enqueue jobs without starting any workers.

More info: Engine Documentation

Can I start only the Dashboard?

Of course. Here's an example of how to start only the Dashboard:

import { SidequestDashboard } from "@sidequest/dashboard";

const dashboard = new SidequestDashboard();

await dashboard.start({
  enabled: true,
  port: 8678,
  backendConfig: {
    driver: "@sidequest/postgres-backend",
    config: "postgresql://localhost:5432/sidequest",
  },
});

More info: Starting only the Dashboard

Can I use Sidequest without a database?

No. You need a database to store information about jobs, queues, and their states.

More info: Backend Documentation

Which databases are supported by Sidequest.js?

PostgreSQL, MongoDB, MySQL, and SQLite. We recommend PostgreSQL for production use.

More info: Backend Documentation

How does Sidequest load my job script?

Sidequest.js uses dynamic imports to load your job scripts. By specifying the job's type during Sidequest.build, Sidequest will automatically find the script and load it.

More info: Job Script Detection

How do I avoid the automatic job script detection?

If you want to control the importing/exporting of job classes manually, you can use the Manual Job Resolution feature. By adding a sidequest.jobs.js file that exports all your job classes, you can avoid the chain of ../../../ relative paths.

Can I run a function directly as a job?

No. Sidequest requires you to create a job class that extends the Job base class. This ensures that your job has the necessary structure and methods to be processed correctly.

More info: Job Class

Sidequest is not finding my job script, what do I do?

Well, in this case, maybe your job is compiled and bundled differently than expected. If you are using Nuxt, Next.js, or something similar, the tool might be bundling your job into a script where it is inaccessible. For now, Sidequest does not support these frameworks out of the box. You can work around it by creating a separate module or package for your jobs, compiled without those frameworks or doing a few shenanigans to make it work.

You can probably find a few workarounds like this in the issues section of our repository.

My Sidequest instances are running jobs from all queues, how do I restrict them?

There is no way to restrict a Sidequest instance to only process jobs from specific queues. However, you can achieve this by starting multiple Sidequest instances, each with a different database. This feature will be included in Sidequest Pro though 🙂

My lower priority queues are not being processed, what do I do?

Sidequest processes jobs based on their priority. If you have high-priority queues with a lot of jobs, they may be consuming all the available worker capacity, leaving no room for lower-priority queues. Sidequest Pro will implement a few strategies to mitigate this issue.

How do I see the result of a job?

You can use the job operations from the Sidequest class to fetch the job and check its result.

const job = await Sidequest.job.get(jobId);
console.log(job.result);

More info: Using Sidequest.job and Sidequest.queue

I have jobs in the running state, but no workers are running. What do I do?

Sidequest will automatically clear stale jobs in the running state after a certain timeout. This timeout is configurable via config options passed to Sidequest.start or Sidequest.configure. You can also manually clear them if you like.

More info: Stale Job Recovery

What is a scheduled/recurring job?

A scheduled/recurring job is a job that is set to run at specific intervals or times, defined by a cron expression. This allows you to automate tasks that need to be performed regularly without manual intervention.

However, scheduled jobs are a bit different from regular jobs. When you call Sidequest.build(MyJob).schedule("* * * * *"), Sidequest creates a cron that, when executed, will enqueue a new instance of MyJob. This means that the scheduled job itself is not the one doing the work; instead, it acts as a trigger to create and enqueue the actual job you want to run.

Scheduled jobs (crons) are not persisted in the database, even though the jobs they create are. If you restart your Sidequest instance, you will need to re-register your scheduled jobs to ensure they continue to run as expected.

More info: .schedule

Can I run TypeScript jobs directly?

Yes, but only if you are using Node.js >= v23.6.0 which has native support for TypeScript. If you are using an older version of Node.js, you will need to compile your TypeScript jobs to JavaScript before running them with Sidequest.

Is Sidequest.js free to use?

Yes, Sidequest.js is 100% free and open-source under the LGPL-3.0 license.

How can I contribute to Sidequest.js?

Great question! We welcome contributions from the community. You can contribute by reporting issues, suggesting features, or submitting pull requests on our GitHub repository. Check out our contributing guidelines for more details.

But Senpai, I have a question that isn't answered here!

If your question isn't covered in this FAQ, please take a closer look at the documentation. Try using the search functionality up top as well. If you still haven't got an answer to your doubt, feel free to open an issue, but please make sure to check if your question has already been asked before.