added nextjs 13 app router native support & docs improvements.

[KevinEdry]

Summary

This PR aims to revise and add two main things:

• Bring native support for Nextjs 13 app router to Quirrel - Bring Native support for Next.js App Directory #1138
• Improve the docs experience since the hosted version of Quirrel isn't available anymore

Nextjs 13 App Router

Because Nextjs 13 now expects a named method function as a route handler (POST, GET etc..), we need to provide it as part of the Queue and CronJob methods, we also want the queue instances themselves, so I've made it so it would be accessible via object destructuring, that way we can export both POST and the queue instance in one go, and alias the queue instance with a meaningful name.

Queue Usage:

  export const { POST, queue: sampleQueue } = Queue(
   "/api/queues/sample",
   (payload) => {
       ...logic goes here
  });
 
 await sampleQueue.enqueue({ jobData });

CronJob Usage:

  export const { POST } = CronJob(
   "/api/queues/sample",
   "0 0 * * 1"
   (payload) => {
       ...logic goes here
  });

I've added some docs changes as well to explain the usage of the new queue api.

The object destructuring is the best way I could think of to keep the named export function POST and still have a meaningful name for the queue instance, if you can think of a better implementation for this please let me know!

Changelog:

code

• added new next13.ts file to support nextjs 13 app directory natively.

docs

• added to proper documentation for all of the Nextjs changes.
• added new "Development" category which explains how to run the Quirrel instance in a docker compose, or as a standalone instance.
• added a new and improved "Deployment" category with several guides on how to deploy quirrel (docker, railway, fly and vercel).
• removed the old "Deploy" page.

BEGIN_COMMIT_OVERRIDE
feat: added nextjs 13 app router native support & docs improvements
END_COMMIT_OVERRIDE

[netlify]

✅ Deploy Preview for quirrel-docs canceled.

Name	Link
🔨 Latest commit	f46f66e
🔍 Latest deploy log	https://app.netlify.com/sites/quirrel-docs/deploys/6491c0282aad4300086b488c

[netlify]

👷 Deploy request for quirrel-development-ui pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	f46f66e

[Skn0tt]

Hi @KevinEdry, this is an amazing PR! Thank you so much - I love how you improved the docs. It's quite big, so reviewing will take a couple iterations, but we'll get there.

[coveralls]

coverage: 82.464%. remained the same when pulling e2f0146 on KevinEdry:main into 9344abf on quirrel-dev:main.

[Skn0tt]

I hope it's okay that i'm committing onto your branch! I figured that's the fastest way to make progress. I'll comment about the changes i'm making and the rationale behind it, feel free to leave comments about anything.

In 5b430d7, i've reworked the quirrel/next13 implementation to be based on the others we have in that directory. I've also changed the user-facing signature to be in-line with how quirre/sveltekit works: https://docs.quirrel.dev/api/sveltekit This means that devs won't destructure the return value of Queue, but instead they'll export it twice.
I've also renamed the file to quirrel/next-app, since next13 will probably grow out-of-date pretty soon :D

[Skn0tt]

I've reverted the changes to the CronJob API docs. I don't think we need to differentiate between Next.js App Router / Pages Router on that page - it's not framework-specific, and Next.js isn't the only framework that's supported by Quirrel.

[KevinEdry]

It is totally fine for you to commit on my branch, I didn't notice you had a similar implementation in quirre/sveltekit, I would probably would go with that.
For the CronJob, I agree that this isn't framework specific, but I do think the docs should also reflect the implementation for every framework, such as a tab selector for each framework and it's implementation. (I might do that later).

[KevinEdry]

We should add here a <Payload> generic and pass it to the handler or the Queue.

export function CronJob<Payload>(
  route: string,
  schedule: string,
  handler: QuirrelJobHandler<Payload>,
  options?: QuirrelOptions<Payload>
) {
  return Queue(route, handler, options);
}

[Skn0tt]

CronJobs don't receive any kind of payload, so there's no need for this.

[KevinEdry]

I use a cronjob with a payload, the cron is starting the job, the job is making an api request, and if the response contains a cursor, it invokes the same job with the cursor:

export const { POST, queue: companiesQueue } = CronJob<Payload>(
  "/api/queue/companies",
  "0 0 * * 1",
  async (payload?: Payload) => {
    try {
      const fetchUrl =
        payload?.cursor != null
          ? payload.cursor
          : "https://api.random-example.com/something";

      const res = await fetchApi<Ticker>(fetchUrl);
      const { results, next_url } = tickersSchema.parse(res);

      if (next_url != null) {
        companiesQueue.enqueue({ cursor: next_url });
      }

      return;
    } catch (error) {
      console.log({ error });
      throw error;
    }
  }
);

[Skn0tt]

Interesting! I'd have never imagined anyone to use a CronJob like this 😁 I think if we documented this, it'd be very non-obvious how it works in most cases. So i'd prefer to not document it. I'm sure you'll find a workaround for your specific case :D

[Skn0tt]

in 1d51c94, i've removed the docker-compose development docs. Quirrel has a local dev mode, and that should be used locally. I think that docker-compose is way too complex for most usecases of this, so I don't want to highlight it in the docs. Appreciate the document, though!

[KevinEdry]

@Skn0tt I wonder if we also need to change the cron-detector since we are no longer importing from quirrel/next.

[Skn0tt]

but I do think the docs should also reflect the implementation for every framework

I want to keep the documentation small and concise, and i'm unsure if another documentation for CronJob for every single framework adds much value.

[Skn0tt]

I wonder if we also need to change the cron-detector

I don't think so, the cron-detector isn't hard-coded on framework names, but matches on quirrel/*:

quirrel/src/cli/cron-detector.ts

Line 20 in 305e424

const quirrelImport = /["']quirrel\/(.*)["']/.exec(file);

[Skn0tt]

This is now in a state where i'm happy with it. @KevinEdry could you give it another read and let me know if there's anything you think needs changing?

[KevinEdry]

@Skn0tt LGTM, the only thing I would change is to add the Payload to the CronJob, but it is your call, I will manage either way in my project and my specific use-case.
I hope these changes will help people use this lib more, I found it really useful for my purposes.