Production only NPM Builds for Cloudflare Pages

Why Optimize Your Cloudflare Pages Build Process

When deploying websites to Cloudflare Pages, you don’t need development dependencies like testing frameworks and linting tools in your production build. This guide shows you how to configure Cloudflare Pages to install only necessary production dependencies, resulting in faster builds and cleaner deployments.

Understanding The Two Types of NPM Dependencies

Production Dependencies: What Your Live Site Needs

Packages required for your application to run in production

• Listed under dependencies in package.json
• Examples: React, Vue, Express

Development Dependencies: Tools for Developers Only

Packages only needed during development such as testing frameworks, linting tools, and type definitions

• Listed under devDependencies in package.json
• Examples: Jest, ESLint, TypeScript, Playwright

By default, Cloudflare Pages installs all dependencies during the build process. We can optimize this by installing only production dependencies.

Step-by-Step Configuration Guide

1. Organize Your Package.json Dependencies

First, ensure your package.json has dependencies properly categorized:

1
"dependencies": {
2
  "astro": "^3.0.0",
3
  "react": "^18.0.0"
4
},
5
"devDependencies": {
6
  "jest": "^29.0.0",
7
  "eslint": "^8.0.0"
8
}

2. Create a Production-Optimized Build Script

Add a dedicated production build script to your package.json:

1
{
2
  "scripts": {
3
    "build:production": "npm clean-install --omit=dev && astro build",
4
    "build:development": "astro build"
5
  }
6
}

The clean-install --omit=dev flag ensures only production dependencies are installed.

3. Configure Cloudflare Pages Build Settings

1. Add an environment variable:

   • Name: SKIP_DEPENDENCY_INSTALL
   • Value: 1

2. Set the build command:

   • Command: npm run build:production

This configuration tells Cloudflare to:

• Skip the default dependency installation
• Use your custom build command that only installs production dependencies

If done correctly you will see the following in the build logs:

1
SKIP_DEPENDENCY_INSTALL is present in environment. Skipping automatic dependency installation.
2
Executing user command: npm run build:production

How to Test Your Optimized Build Configuration

Test the build locally to ensure it works as expected and all required dependencies are in the “dependencies” section of your package.json. If the build succeeds locally, it should work on Cloudflare Pages as well.

1. Remove the node_modules directory
2. Run npm run build:production
3. Verify that your application builds successfully
4. Check that development tools are not installed

Troubleshooting Common Build Optimization Issues

1. Missing Dependencies: Check if any production dependencies were incorrectly listed under devDependencies
2. Build Script Errors: Ensure your build script includes all necessary steps in the correct order
3. Environment Variables: Verify that any required environment variables are properly set in your Cloudflare Pages project settings

Best Practices for NPM Build Optimization

• Regularly audit your dependencies to ensure proper categorization

• Keep your package.json organized and up-to-date

• Document any special build requirements in your project’s README

• Test production builds locally before deploying

By following these steps, you’ll have a more efficient build process that only includes the packages necessary for your production environment.