Host mailing preview on Next.js API route

[umar-ahmed]

I see that Mailing.run is already built on top of Next.js. I was wondering if there is any interest in allowing projects to integrate the preview server in an existing Next.js project using API routes?

Example:

// /pages/api/mailing/[...nextmailing].js
import NextMailing from 'mailing-next'

export default NextMailing({
  emailsDir: 'emails',
  preview: process.env.NODE_ENV === 'development'
})

The benefit of directly integrating is mostly for DX:

• Only need to spin up one server in local dev, ie. next dev
• Similar to the way NextAuth integrates
• Can share the same deployment, build tools, etc.

The main disadvantage I can see is that if Mailing.run decides to switch away for Next.js or not tie itself to any one framework, it might be harder to implement future features.

Let me know what you guys think!

[psugihara]

Hey @umar-ahmed I definitely like this idea as it might make it easier for some people to deploy. However, it seems kind of hard to implement. For example, I was not able to figure out a nice way to read the filesystem from a next API route so the next app actually runs embedded in a vanilla node server when you're in development mode and that process packages up the emails directory to pass it to the next app in .mailing.

[umar-ahmed]

Ok I think I've found a decent compromise that removes the need to hard-code any paths. Basically, instead of using require.context() inside of the library code itself, we provide the user with a factory function that takes the require.context() has an argument:

// emails/server.js
import { createNextMailing } from "next-mailing/server";

export const { handler, getServerSideProps } = createNextMailing(
  require.context(".", false, /\.[jt]sx$/)
);

and an equivalent for the page:

// emails/client.js
import { buildNextMailingPage } from "next-mailing/client";

export const NextMailingPage = buildNextMailingPage();

These two files will need to be added to the boilerplate emails folder so that the user doesn't need to manually create them. Then the user can just add the pages to the correct routes:

// pages/api/mailing/[[...nextmailing]].js
import { handler } from "emails/server";

export default handler;

// pages/mailing/[[...nextmailing]].js
import { NextMailingPage } from "emails/client";
import { getServerSideProps } from "emails/server";

export default NextMailingPage;

export { getServerSideProps };

The client and server have to be separated like this so that Next.js correctly separates the dependencies (there are some calls to node:fs in mailing-core).

[psugihara]

love that solution for the emailsDir

Just looked at the code. Very clean, very promising!

I can explore how we might fold some of this into packages/cli and get rid of the custom node server more tomorrow. My first thought is that we could add the rest of the preview server features/ui to this then use it in the .mailing next app. We might want to do it in its own package (e.g. packages/next-mailing) so that we can configure the build separately from the CLI. Then when you're installing in a next app, we'd try to install in your app directly rather than generating the .mailing app.

[umar-ahmed]

Sounds good to me!

You probably have a better idea than I do of how exactly we'd go about integrating this into the main repo, but what you've described makes sense to me.

It's kind of like progressive enhancement; if the CLI detects that your project is Next.js project, it can integrate directly. And if not (say you're using Remix or something else), it'll just do what it currently does and create a separate folder. In that way, it's very similar to what Storybook has been doing with their CLI where it detects your framework and installs the appropriate packages and configs.

I'll leave https://github.com/umar-ahmed/mailing-test as is for your reference.

Also, if you start up a PR or want any help, feel free to ping me on GitHub or Discord. I'm happy to help 😄

[psugihara]

sounds good, appreciate this work so much 🙌. I'll definitely loop you for help as I try to integrate.

[psugihara]

Hey @umar-ahmed, I wanted to follow up here. I did some investigation and this seems doable but kind of hard to integrate (mostly a lot of routes to migrate). After reviewing priorities, unfortunately I don't think I'll have time in the near future.

If you wanted to take this work on yourself, I'd of course be happy to support. Otherwise we really appreciate the work and added a ticket with tasks for when someone does have time to pick it up here #402. Feel free to dm or email me if you want to chat more.