Cloudflare Pages: Do Static and Function Routes Test Separately?

Updated 5 November 2026 · Standard formula, shown below

Yes, Cloudflare Pages tests static routes and Functions separately. Static assets are served directly from the edge network, while Functions run on Cloudflare Workers; each has its own build, deployment, and testing pipeline. This separation affects how you preview, debug, and deploy your site.

Background: How Cloudflare Pages Works

Cloudflare Pages is a platform for hosting static sites and serverless functions. It integrates with Git providers (GitHub and GitLab) to automatically build and deploy your project. The static part consists of HTML, CSS, JavaScript, images, and other files that are served as-is. The Functions part is a set of JavaScript or TypeScript files that run on Cloudflare Workers, allowing dynamic behavior like form handling, authentication, or API proxying.

When you push changes to your repository, Cloudflare Pages builds the static assets and bundles the Functions separately. The build output is then deployed to Cloudflare’s global edge network. Because the two parts are fundamentally different, they are tested and served independently.

How Static Routes Are Tested

Static routes are tested by verifying that the correct files are served for each URL. In a typical Pages project, the file structure determines the routes. For example:

/about.html serves the file about.html.
/about serves about.html if clean URLs are enabled.
/blog/post-1 serves the file at blog/post-1.html or blog/post-1/index.html.

You can test static routes locally by running the build command and serving the output directory with any static file server. Cloudflare also provides a local development tool, wrangler pages dev, which serves both static assets and Functions together. However, if you only want to test the static portion, you can use a simple HTTP server like python -m http.server or npx serve.

How Functions Are Tested

Functions are tested by invoking them with mock requests and checking the responses. Each function is a file in the /functions directory (or the directory specified in your build config). The file name determines the route. For example:

/functions/api/hello.js handles requests to /api/hello.
/functions/form.js handles requests to /form.

To test functions locally, you use wrangler pages dev which starts a local server that emulates the Workers runtime. You can send HTTP requests to the local server and inspect the responses. This is the standard way to test functions because they rely on the Workers runtime, which is not available in a plain static file server.

Common Misconception: Build and Test Are Not the Same

A frequent misunderstanding is that if the static site builds successfully, the Functions are also fine. That is not true. Static build tools (like Vite, Webpack, or Next.js) only process frontend assets. Functions are compiled separately by Cloudflare’s build system. A syntax error in a function will not fail the static build; it will only appear when the function is invoked. Therefore, you must test both parts independently.

How to Choose the Right Testing Approach

For a project with both static and dynamic parts, you should test them separately to isolate issues. Here is a practical workflow:

Build the static site with your usual build command (e.g., npm run build).
Serve the dist folder locally and check that all pages and assets load correctly.
Run wrangler pages dev to start the full local environment.
Send requests to your function routes (e.g., curl http://localhost:8788/api/hello) and verify the responses.
Test edge cases like missing parameters, invalid JSON, and CORS headers.

If you are using a framework like Next.js or SvelteKit, the static and dynamic parts are often intertwined. In that case, you should rely on the framework’s own development server, which handles both. But for plain static sites with a few Functions, the separate approach is simpler and more reliable.

Common Problems and How to Avoid Them

One common issue is path mismatches. A static route might be /about while a function is at /about as well. Cloudflare Pages gives priority to static assets over Functions. If a static file exists at a given path, it will be served instead of the function. This is a frequent source of confusion. To avoid it, use distinct paths for functions, such as /api/ prefix.

Another issue is environment variables. Static builds can use environment variables at build time, but Functions can also access them at runtime. If you test locally, make sure you have the correct .dev.vars file for Functions. If you forget, the function may fail with an undefined variable.

Finally, be aware of CORS. When testing Functions from a browser, you may need to set appropriate CORS headers. This is not an issue when testing with curl, but it will appear in real browser usage.

Costs and Performance Considerations

There is no extra cost for testing separately; it is just a workflow choice. In production, static assets are served from Cloudflare’s CDN, which is very fast. Functions run on Workers, which also have low latency, but they incur compute time. Cloudflare’s free tier includes a generous amount of Workers requests, but heavy usage may require a paid plan. Since static and Functions are billed separately, you can optimize costs by keeping static content on CDN and only using Functions when necessary.

Alternatives to Cloudflare Pages

If you need a platform that tests static and dynamic routes together, you might consider other JAMstack hosts like Netlify or Vercel. They also separate static and serverless functions, but their local development tools may differ. For example, Netlify uses Netlify Functions and has a similar local dev server. Vercel uses Vercel Functions and has its own CLI. The core concept is the same: static and dynamic are separate, but the testing tools vary.

Frequently Asked Questions

Can I test static and Functions at the same time?

Yes, you can use wrangler pages dev which serves both static assets and Functions together. This is the closest to production behavior. However, if you want to isolate a problem, you can test them separately.

Does Cloudflare Pages run unit tests for Functions?

No, Cloudflare Pages does not run your unit tests automatically. You need to configure your own CI/CD pipeline to run tests before deploying. Cloudflare only builds and deploys your code.

Why is my static route not working but my function is?

This usually happens when a static file and a function have the same path. Static assets take precedence. Check your file structure and rename one of them.

How do I debug a Function locally?

Use wrangler pages dev and add console.log statements in your function code. The logs will appear in the terminal where you run the dev server. You can also use the Workers playground in the Cloudflare dashboard for quick testing.

Can I use a different directory for Functions?

Yes, you can specify a custom functions directory in your wrangler.toml or in the Pages project settings. The default is /functions.

Do Functions count against my static site’s bandwidth?

No, Functions requests are billed separately from static asset bandwidth. Static assets are served from the CDN, while Functions run on Workers and are metered by request count and compute time.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.