To deploy the application to Cloudflare, you need to do the following:
- Opt-in to the Edge runtime
- Using the Cloudflare Mailer
- Switching CMS
- Setting Node.js Compatibility Flags
- Environment variables
- Workarounds
NB: deploying to Cloudflare requires a subscription to the Cloudflare Workers paid service due to the size limitations of the free tier. It starts at $5.
0. Limitations
Before you continue, please evaluate the limitations of the Edge runtime. The Edge runtime does not support all Node.js features, so you may need to adjust your application accordingly.
Cloudflare is cheaper and faster than many other providers, but running your application on Cloudflare Pages means not having access to the vast Node.js ecosystem.
Makerkit uses Cloudflare as a baseline, so you can deploy it to Cloudflare Pages without any issues. However, you will need to keep in mind the limitations of the Workers/Edge runtime when adding new features.
One more thing to consider is that the Edge runtime does run close to your users, but may run far from your database. Consider read replicas or other strategies to reduce latency in all situations.
If your mind is set on using Cloudflare, please follow the instructions below.
1. Opting into the Edge runtime
To opt-in to the Edge runtime, you need to do the following: open the root layout file of your app apps/web/app/layout.tsx
and export the const runtime as edge
:
export const runtime = 'edge';
This will enable the Edge runtime for your application.
2. Using the Cloudflare Mailer or Resend Mailer
Since the default library nodemailer
relies on Node.js, we cannot use it in the Edge runtime. Instead, we will Resend Mailer.
Set up SPF and DKIM records in your DNS settings.
Please follow the Vercel Email documentation to set up the SPF and DKIM records.
Alternatively, you can use the Resend Mailer. Set the MAILER_PROVIDER
environment variable to resend
in the apps/web/.env
file:
MAILER_PROVIDER=resend
And provide the Resend API key:
RESEND_API_KEY=your-api-key
Alternatively, implement your own mailer using the abstract class we provide in the packages/mailers
package.
3. Switching CMS
By default, Makerkit uses Keystatic as a CMS. Keystatic's local mode (which relies on the file system) is not supported in the Edge runtime. Therefore, you will need to switch to another CMS or use Keystatic's Github mode - which uses Github as data provider.
At this time, the other CMS supported is WordPress. Set CMS_CLIENT
to wordpress
in the apps/web/.env
file:
CMS_CLIENT=wordpress
Alternatively, use the Keystatic remote mode through Github.
Please check the CMS documentation for more information.
4. Select "apps/web" as path to build
When prompted to select the path to build, select apps/web
as the path to build - since our Next.js app is located in the apps/web
directory.
If you have multiple apps, you can select the app you want to deploy.
5. Setting Node.js Compatibility Flags
Cloudflare requires you to set the Node.js compatibility flags. Please follow the instructions on the Cloudflare documentation.
Please don't miss this step, as it's crucial for the application to work in the Edge runtime.
6. Environment variables
When adding environment variables, make sure to add all of them from the Cloudflare dashboard instead of the .env
file. I cannot understand why, but the Workers did not pick up the environment variables from the .env
file. So please do make sure to add all the environment variables from the Cloudflare dashboard.
7. Workarounds
An issue with Cloudflare causes makes it impossible to deploy to Cloudflare Pages without two workarounds:
- Monkey-patching the
fetch
function for Keystatic
Monkey-patching the fetch
function
The below is needed if you use Keystatic in Github mode. If you use Wordpress or another CMS, you can skip this step.
Create a new file named mock-workerd-fetch.ts
in the packages/cms/keystatic/src
directory and add the following code:
function mockWorkerdFetch() {
const originalFetch = globalThis.fetch;
globalThis.fetch = async function (...args) {
try {
return await originalFetch.apply(this, args);
} catch (e) {
if (!args[1] || typeof args[1] !== 'object') throw e;
const unimplementedCacheError =
e &&
typeof e === 'object' &&
'message' in e &&
e.message ===
"The 'cache' field on 'RequestInitializerDict' is not implemented.";
if (!unimplementedCacheError) throw e;
const newOpts = { ...args[1] };
delete newOpts.cache;
return originalFetch.apply(this, [args[0], newOpts]);
}
};
}
mockWorkerdFetch();
Open the file packages/cms/keystatic/src/create-reader.ts
and add the following line at the top of the file:
import './mock-workerd-fetch';