This guide outlines the direct, programmatic workflow for deploying a static website or single-page application (SPA) to Cloudflare Pages.
By utilizing the Cloudflare Wrangler CLI, you bypass the need to manually configure projects inside the Cloudflare dashboard UI. The entire lifecycle—from initialization to deployment—is managed entirely from your terminal or CI/CD pipeline.
When deploying static assets via the CLI, you do not need to create a project or worker-page in the Cloudflare dashboard beforehand. 1. Local Initialization: The create-cloudflare tool handles scaffolding and links your local directory structure.
2. Direct Edge Publishing: Running wrangler pages deploy automatically registers the project under your Cloudflare account (if it doesn't already exist), uploads your static build assets, provisions an edge routing layer, and outputs a live deployment URL instantly.
If you haven't already scaffolded your project, use the official Cloudflare initializer. This will guide you through setting up a framework or a standard static upload directory:
npm create cloudflare@latest -- --type=static
During this process, you will be prompted to authenticate with your Cloudflare account via your browser.
Ensure your project is compiled and all static files (HTML, CSS, JS, images) are located in a single distribution directory (e.g., dist, build, or public).
If you are deploying a raw static page, your directory structure might look like this:
my-static-site/
├── index.html
├── styles.css
└── assets/
To deploy your static assets directly to Cloudflare's global edge network, run the following command from your project root:
npx wrangler pages deploy <directory-name>
If your static assets are in the root directory or a folder named public:
npx wrangler pages deploy public --project-name=my-awesome-static-page
- By default, Wrangler deploys to a preview environment and generates a unique hash URL.
- To deploy directly to production (updating your main project URL), explicitly pass the production branch flag:
npx wrangler pages deploy public --branch=main
| Command | Purpose |
|---|---|
npm create cloudflare@latest |
Initializes a new Cloudflare-compatible project repository. |
npx wrangler login |
Manually re-authenticates or switches Cloudflare accounts in the CLI. |
npx wrangler pages deploy <dir> |
Deploys specified directory to a preview URL. |
npx wrangler pages deploy <dir> --branch=main |
Deploys specified directory directly to the production environment. |
- No UI Overhead: Skip the Cloudflare dashboard setup completely.
- Instant Propagation: Files are distributed to Cloudflare's global edge nodes within seconds of terminal completion.
- Immutable Previews: Every non-production deploy provides a unique, permanent preview URL to inspect changes safely. """