Custom routing on a per-collection basis

[GeorgeyB]

What's the Payload convention for introducing custom routes on a per-collection basis? Currently I'm importing custom routers into server.ts, but it could get messy.

I think it would be neat to have a way of providing custom routes to our collection configurations that'd be matched before the payload routes in src\collections\init.ts. As an example:

const Products: CollectionConfig = {
    slug: 'products',
    admin: {
        useAsTitle: 'name'
    },
    preRoute: (router) => {
        router.post('/sync/:id', (req, res) => {
            /** POST: /products/sync/12345 hits this route */
            /** Matched before payload routes */
        });
    }
}

Any thoughts on this?

Apologies if there's already a neater way to do this that I've missed. 🙂

[jmikrut]

This is great!

And it would be pretty easy to accomplish I think. We have our hands full with other features, but if anyone wants to tackle this in the interim, we would be happy to collaborate!

[DanRibbens]

I would like to see the preRoute function on the collection config moved to an array. This helps plugins to be able to work without collisions.

Another question is how do we get the most out of the pattern you've identified? Aside from extending the router there are other use-cases for a function call when initializing collections and this could all be lumped together by supplying more arguments than just the router.

Example uses would be:

• modify the collection schema
• change passport strategies
• do something with the collection config after it has been sanitized

I'd like to explore this direction in collections\init.ts

if (collection.onInit) {
  collection.onInit.forEach((hook) => hook({ collection, router, schema, versionSchema }));
}

and then calling the same thing outside of the collection.local condition that doesn't include the router.

This way we're future proofed too as we can add other things to the arguments later with fewer breaking changes.

[GeorgeyB]

Great idea 👍

Though if you're heading in that direction, I'd suggest a collection.beforeInit (e.g. to add priority routes) and collection.afterInit (e.g. to manipulate the passport strategy) in which case, maybe it'd make more sense to throw these into the existing hooks config.

[DanRibbens]

You don't think it would be confusing to have hooks that run only at startup and not each time the api is called?

I'm second guessing how can we make this most useful but also easy to understand.

Simple and just do extension of routes or paint with a wider brush? Would love to hear what some others think!

[JarrodMFlesch]

@DanRibbens my gut feeling is that preRoute is too specific, and as you explained it could instead be handled within an init function. I think the config structure and naming scheme is just something that needs to be ironed out. My vote is to broaden the approach and allow for the user to do many things before/after init.

I am not saying that it should necessarily be patched into hooks, as that might be confusing as you described, but maybe these would fall underneath another (new) property on the config.

[GeorgeyB]

@DanRibbens, @JarrodMFlesch,

Sounds good. What's the verdict?

A config option like so?

init: {
    before: [ ({ router }) => { /** things and stuffs.. */ } ],
    after: [ ({ router }) => { /** things and stuffs.. */ } ]
}

Or something even more future-proof?

lifecycle: {
    beforeInit: [ ({ router }) => { /** things and stuffs.. */ } ],
    afterInit: [ ({ router }) => { /** things and stuffs.. */ } ]
}

I'd be happy to implement and update the PR.

[jmikrut]

@DanRibbens and I were just talking about this idea and we have come up with a direction that we think is appropriate.

const ExampleCollection = {
  // Collection config here
  endpoints: [
    {
      route: '/say-hello/:name/',
      method: 'get',
      handlers: [
        (req, res) => {
          return res.json({ message: `hello ${req.params.name}` });
        },
      ],
    },
  ],
}

Here is our thinking:

• We've scrapped the notion of "init" because we want to make sure that Payload's config properties each have a declarative purpose, rather than leaving everything open-ended. If things were so open ended, you'd need to learn how Payload works internally in order to write plugins / etc. for Payload. This is the grave mistake that other CMS make and we're going to try and avoid it. Instead, by using a property called endpoints, we can declaratively define endpoints. That's it.
• We may move to supporting a serverless infrastructure in the future, and we want to make sure that we don't bind ourselves directly to Express for this reason. We will always support Express, but if we use a convention of defining route, method, and handlers, we'll be safer in the long run if we want to mount each of these as serverless functions down the line.
• The notion of "pre" / "post" isn't relevant here, because each of these endpoints will be encapsulated entirely to themselves. They just simply need to be mounted.

Other notes:

• We need to add this functionality to the /demo folder and build tests around it.
• We should validate that there are no route / method collisions with other endpoints that may be injected by plugins and similar. If there are collisions, we should throw an error on config validation.
• This should all apply in the same way to Globals.
• We need to update docs in connection with this change.

What do we all think? @JarrodMFlesch @DanRibbens @GeorgeyB

[JarrodMFlesch]

I really like this approach. I had a similar feeling about the init functions, and needing to learn the Payload way which is obviously not what we are going for.

I am on board with the above 👍

[GeorgeyB]

I'm also a big fan of this approach 🙂

[DanRibbens]

I've changed handers, to just handler. It can still take an array since express knows what to do.
I also changed route to path to be more semantic.

We ended up scrapping the extra endpoint validation because it was unnecessary due to how express can handle multiple matching routes. By removing this it is possible to add middleware before built-in payload endpoints are called which could be a great feature for adding extra logic to hooks or something.

Thanks for your help on the PR and patience getting it merged!