|
| 1 | +--- |
| 2 | +updated: 2025-05-16 |
| 3 | +difficulty: Beginner |
| 4 | +pcx_content_type: tutorial |
| 5 | +title: Migrate from Netlify to Workers |
| 6 | +--- |
| 7 | + |
| 8 | +import { WranglerConfig } from "~/components"; |
| 9 | + |
| 10 | +In this tutorial, you will learn how to migrate your Netlify application to Cloudflare Workers. |
| 11 | + |
| 12 | +You should already have an existing project deployed on Netlify that you would like to host on Cloudflare Workers. Netlify specific features are not supported by Cloudflare Workers. Review the [Workers compatibility matrix](/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix) for more information on what is supported. |
| 13 | + |
| 14 | +## Frameworks |
| 15 | + |
| 16 | +Some frameworks like Next.js, Astro with on demand rendering, and others have specific guides for migrating to Cloudflare Workers. Refer to our [framework guides](/workers/frameworks/) for more information. If your framework has a **Deploy an existing project on Workers** guide, follow that guide for specific instructions. Otherwise, continue with the steps below. |
| 17 | + |
| 18 | +## Find your build command and build directory |
| 19 | + |
| 20 | +To move your application to Cloudflare Workers, you will need to know your build command and build directory. Cloudflare Workers will use this information to build and deploy your application. We will cover how to find these values in the Netlify Dashboard below. |
| 21 | + |
| 22 | +In your Netlify Dashboard, find the project you want to migrate to Workers. Go to the **Project configuration** menu for your specific project, then go into the **Build & deploy** menu item. You will find a **Build settings** card that includes the **Build command** and **Publish directory** fields. Save these for deploying to Cloudflare Workers. In the below image, the **Build Command** is `npm run build`, and the **Output Directory** is `.next`. |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +## Create a wrangler file |
| 27 | + |
| 28 | +In the root of your project, create a `wrangler.jsonc` or `wrangler.toml` file (`wrangler.jsonc` is recommended). What goes in the file depends on what type of application you are deploying: an application powered by [Static Site Generation (SSG)](/workers/static-assets/routing/static-site-generation/), or a [Single Page Application (SPA)](/workers/static-assets/routing/single-page-application/). |
| 29 | + |
| 30 | +For each case, be sure to update the `<your-project-name>` value with the name of your project and `<your-build-directory>` value with the build directory from Netlify. |
| 31 | + |
| 32 | +For a **static site**, you will need to add the following to your wrangler file. |
| 33 | + |
| 34 | +<WranglerConfig> |
| 35 | + |
| 36 | +```jsonc |
| 37 | +{ |
| 38 | + "name": "<your-project-name>", |
| 39 | + "compatibility_date": "$today", |
| 40 | + "assets": { |
| 41 | + "directory": "<your-build-directory>", |
| 42 | + } |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +</WranglerConfig> |
| 47 | + |
| 48 | +For a **Single Page Application**, you will need to add the following to your Wrangler configuration file, which includes the `not_found_handling` field. |
| 49 | + |
| 50 | +<WranglerConfig> |
| 51 | + |
| 52 | +```jsonc |
| 53 | +{ |
| 54 | + "name": "<your-project-name>", |
| 55 | + "compatibility_date": "2025-04-23", |
| 56 | + "assets": { |
| 57 | + "directory": "<your-build-directory>", |
| 58 | + "not_found_handling": "single-page-application" |
| 59 | + } |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +</WranglerConfig> |
| 64 | + |
| 65 | +Some frameworks provide specific guides for migrating to Cloudflare Workers. Please refer to our [framework guides](/workers/frameworks/) for more information. If your framework includes a “Deploy an existing project on Workers” guide, follow it for detailed instructions. |
| 66 | + |
| 67 | +## Create a new Workers project |
| 68 | + |
| 69 | +Your application has the proper configuration to be built and deployed to Cloudflare Workers. |
| 70 | + |
| 71 | +The [Connect a new Worker](/workers/ci-cd/builds/#connect-a-new-worker) guide will instruct you how to connect your GitHub project to Cloudflare Workers. In the configuration step, ensure your build command is the same as the command you found on Netlify. Also, the deploy command should be the default `npx wrangler deploy`. |
| 72 | + |
| 73 | +## Add a custom domain |
| 74 | + |
| 75 | +Workers Custom Domains only supports domains that are configured as zones on your account. A zone refers to a domain (such as example.com) that Cloudflare manages for you, including its DNS and traffic. |
| 76 | + |
| 77 | +Follow these instructions for [adding a custom domain to your Workers project](/workers/configuration/routing/custom-domains/#add-a-custom-domain). You will also find additional information on creating a zone for your domain. |
| 78 | + |
| 79 | +## Delete your Netlify app |
| 80 | + |
| 81 | +Once your custom domain is set up and sending requests to Cloudflare Workers, you can safely delete your Netlify application. |
| 82 | + |
| 83 | +## Troubleshooting |
| 84 | + |
| 85 | +For additional migration instructions, review the [Cloudflare Pages to Workers migration guide](/workers/static-assets/migration-guides/migrate-from-pages/). While not Netlify specific, it does cover some additional steps that may be helpful. |
0 commit comments