Skip to content

workers.mdx

Latest commit

 

History

History
541 lines (418 loc) · 31 KB

workers.mdx

File metadata and controls

541 lines (418 loc) · 31 KB
Raw
pcx_content_type reference
title Workers
description Wrangler commands for creating, developing, deploying, and managing Workers.
sidebar
order
1
products
workers

import { TabItem, Tabs, Render, Type, MetaInfo, WranglerCommand, WranglerNamespace, PackageManagers, DashButton, } from "~/components";

Wrangler commands for creating, developing, deploying, and managing Workers.

init

Create a new project via the create-cloudflare-cli (C3) tool. A variety of web frameworks are available to choose from as well as templates. Dependencies are installed by default, with the option to deploy your project immediately.

wrangler init [<NAME>] [OPTIONS]
  • NAME
    • The name of the Workers project. This is both the directory name and name property in the generated Wrangler configuration.
  • --yes
    • Answer yes to any prompts for new projects.
  • --from-dash
    • Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name. wrangler init --from-dash <WORKER_NAME>.
    • The --from-dash command will not automatically sync changes made to the dashboard after the command is used. Therefore, it is recommended that you continue using the CLI.

dev

Start a local server for developing your Worker.

wrangler dev [<SCRIPT>] [OPTIONS]

:::note

None of the options for this command are required. Many of these options can be set in your Wrangler file. Refer to the Wrangler configuration documentation for more information.

:::

  • SCRIPT
    • The path to an entry point for your Worker. Only required if your Wrangler configuration file does not include a main key (for example, main = "index.js").
  • --name
    • Name of the Worker.
  • --config, -c
    • Path(s) to Wrangler configuration file. If not provided, Wrangler will use the nearest config file based on your current working directory.
    • You can provide multiple configuration files to run multiple Workers in one dev session like this: wrangler dev -c ./wrangler.toml -c ../other-worker/wrangler.toml. The first config will be treated as the primary Worker, which will be exposed over HTTP. The remaining config files will only be accessible via a service binding from the primary Worker.
  • --no-bundle
    • Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to Bundling for more information.
  • --env
    • Perform on a specific environment.
  • --compatibility-date
    • A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.
  • --compatibility-flags, --compatibility-flag
    • Flags to use for compatibility checks.
  • --latest
    • Use the latest version of the Workers runtime.
  • --ip
    • IP address to listen on, defaults to localhost.
  • --port
    • Port to listen on.
  • --inspector-port
    • Port for devtools to connect to.
  • --routes, --route
    • Routes to upload.
    • For example: --route example.com/*.
  • --host
    • Host to forward requests to, defaults to the zone of project.
  • --local-protocol
    • Protocol to listen to requests on.
  • --https-key-path
    • Path to a custom certificate key.
  • --https-cert-path
    • Path to a custom certificate.
  • --local-upstream
    • Host to act as origin in local mode, defaults to dev.host or route.
  • --assets
    • Folder of static assets to be served. Replaces Workers Sites. Visit assets for more information.
  • --site
    • Folder of static assets for Workers Sites. :::caution Workers Sites is deprecated. Please use Workers Assets or Pages. :::
  • --site-include
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.
  • --site-exclude
    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.
  • --upstream-protocol
    • Protocol to forward requests to host on.
  • --var
    • Array of key:value pairs to inject as variables into your code. The value will always be passed as a string to your Worker.
    • For example, --var "git_hash:'$(git rev-parse HEAD)'" "test:123" makes the git_hash and test variables available in your Worker's env.
    • This flag is an alternative to defining vars in your Wrangler configuration file. If defined in both places, this flag's values will be used.
  • --define
    • Array of key:value pairs to replace global identifiers in your code.
    • For example, --define "GIT_HASH:'$(git rev-parse HEAD)'" will replace all uses of GIT_HASH with the actual value at build time.
    • This flag is an alternative to defining define in your Wrangler configuration file. If defined in both places, this flag's values will be used.
  • --tsconfig
    • Path to a custom tsconfig.json file.
  • --minify
    • Minify the Worker.
  • --persist-to
    • Specify directory to use for local persistence.
  • --remote
    • Develop against remote resources and data stored on Cloudflare's network.
  • --tunnel
  • --tunnel-name
    • Use an existing named Cloudflare Tunnel. Combine with --tunnel to open it automatically at startup.
  • --test-scheduled
    • Exposes a /__scheduled fetch route which will trigger a scheduled event (Cron Trigger) for testing during development. To simulate different cron patterns, a cron query parameter can be passed in: /__scheduled?cron=*+*+*+*+* or /cdn-cgi/handler/scheduled?cron=*+*+*+*+*.
  • --log-level
    • Specify Wrangler's logging level.
  • --show-interactive-dev-session
    • Show the interactive dev session.
  • --alias Array<string>
  • --types
    • Generate types from your Worker configuration.
  • --local
    • Run in local mode. In this mode:
      • the Worker code is running locally on your machine
      • all remote bindings are disabled, which behaves exactly as if they were configured with remote: false.

wrangler dev is a way to locally test your Worker while developing. With wrangler dev running, send HTTP requests to localhost:8787 and your Worker should execute as expected. You will also see console.log messages and exceptions appearing in your terminal.

:::note wrangler dev runs the local workerd runtime with TZ=UTC to match the production Cloudflare runtime. Date and Intl APIs inside your Worker observe UTC during local development, regardless of your machine's timezone. :::

deploy

Deploy your Worker to Cloudflare.

When you run wrangler deploy in a project directory without a Wrangler configuration file, Wrangler will automatically detect your framework and configure your project for Cloudflare Workers. This command will prompt you to confirm the detected settings before applying changes. Confirm that you would like to proceed, and your project will be configured and deployed.

To configure your project without deploying, use wrangler setup instead.

wrangler deploy [<PATH>] [OPTIONS]

:::note

None of the options for this command are required. Also, many can be set in your Wrangler file. Refer to the Wrangler configuration documentation for more information.

:::

  • PATH

    • A path specific what needs to be deployed, this can either be:

      • The path to an entry point for your Worker.

      • Or the path to an assets directory for the deployment of a static site.

        • Visit assets for more information.
        • This overrides the eventual assets configuration in your Wrangler configuration file.
        • This is equivalent to the --assets option listed below.
        • Note: this option currently only works only in interactive mode (so not in CI systems).

  • --name

    • Name of the Worker.

  • --no-bundle

    • Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to Bundling for more information.

  • --env

    • Perform on a specific environment.

  • --outdir

    • Path to directory where Wrangler will write the bundled Worker files.

  • --compatibility-date

    • A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.

  • --compatibility-flags, --compatibility-flag

    • Flags to use for compatibility checks.

  • --latest

    • Use the latest version of the Workers runtime.

  • --assets

    • Folder of static assets to be served. Replaces Workers Sites. Visit assets for more information.

  • --site

    • Folder of static assets for Workers Sites. :::caution Workers Sites is deprecated. Please use Workers Assets or Pages. :::

  • --site-include

    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.

  • --site-exclude

    • Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.

  • --var

    • Array of key:value pairs to inject as variables into your code. The value will always be passed as a string to your Worker.
    • For example, --var git_hash:$(git rev-parse HEAD) test:123 makes the git_hash and test variables available in your Worker's env.
    • This flag is an alternative to defining vars in your Wrangler configuration file. If defined in both places, this flag's values will be used.

  • --define

    • Array of key:value pairs to replace global identifiers in your code.
    • For example, --define GIT_HASH:$(git rev-parse HEAD) will replace all uses of GIT_HASH with the actual value at build time.
    • This flag is an alternative to defining define in your Wrangler configuration file. If defined in both places, this flag's values will be used.

  • --triggers, --schedule, --schedules

  • --routes, --route string[] optional

    • Routes where this Worker will be deployed.
    • For example: --route example.com/*.

  • --domain

    • Custom domains where this Worker will be deployed.
    • For example: --domain example.com.

  • --tsconfig

    • Path to a custom tsconfig.json file.

  • --minify

    • Minify the bundled Worker before deploying.

  • --dry-run

    • Compile a project without actually deploying to live servers. Combined with --outdir, this is also useful for testing the output of npx wrangler deploy. It also gives developers a chance to upload our generated sourcemap to a service like Sentry, so that errors from the Worker can be mapped against source code, but before the service goes live.

  • --keep-vars

    • It is recommended best practice to treat your Wrangler developer environment as a source of truth for your Worker configuration, and avoid making changes via the Cloudflare dashboard.
    • If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behaviour set keep-vars to true.
    • Secrets are never deleted by a deployment whether this flag is true or false.

  • --secrets-file

  • --dispatch-namespace

  • --metafile

    • Specify a file to write the build metadata from esbuild to. If flag is used without a path string, this defaults to bundle-meta.json inside the directory specified by --outdir. This can be useful for understanding the bundle size.

  • --containers-rollout

    • Specify the rollout strategy for Containers associated with the Worker. If set to immediate, 100% of container instances will be updated in one rollout step, overriding any configuration in rollout_step_percentage. Note that rollout_active_grace_period, if configured, still applies.
    • Defaults to gradual, where the default rollout is 10% then 100% of instances.

  • --strict

    • Turns on strict mode for the deployment command, meaning that the command will be more defensive and prevent deployments which could introduce potential issues. In particular, this mode prevents deployments if the deployment would potentially override remote settings in non-interactive environments.

  • --tag

    • A tag for this Worker version. Matches the behavior of wrangler versions upload --tag.

  • --message

    • A descriptive message for this Worker version and deployment. Matches the behavior of wrangler versions upload --message. The message is also applied to the deployment.

  • --yes

    • Skip confirmation prompts and run automatic project configuration non-interactively using detected settings. Only applicable when no Wrangler configuration file exists in your project.

delete

Delete your Worker and all associated Cloudflare developer platform resources.

wrangler delete [<SCRIPT>] [OPTIONS]
  • SCRIPT
    • The path to an entry point for your Worker. Only required if your Wrangler configuration file does not include a main key (for example, main = "index.js").
  • --name
    • Name of the Worker.
  • --env
    • Perform on a specific environment.
  • --dry-run
    • Do not actually delete the Worker. This is useful for testing the output of wrangler delete.

This command configures your project for Cloudflare Workers without deploying. It performs the same automatic project configuration as wrangler deploy, but does not deploy. This is useful when you want to review the generated configuration before deploying.

secret

Manage the secret variables for a Worker.

This action creates a new version of the Worker and deploys it immediately. To only create a new version of the Worker, use the wrangler versions secret commands.

When running this command, you will be prompted to input the secret's value:

npx wrangler secret put FOO
? Enter a secret value: > ***
🌀 Creating the secret for script worker-app
✨ Success! Uploaded secret FOO

The put command can also receive piped input. For example:

echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY

The following is an example of listing the secrets for the current Worker.

npx wrangler secret list
[
  {
    "name": "FOO",
    "type": "secret_text"
  }
]

The following is an example of uploading secrets from a JSON file redirected to stdin. When complete, the output summary will show the number of secrets uploaded and the number of secrets that failed to upload.

{
	"secret-name-1": "secret-value-1",
	"secret-name-2": "secret-value-2"
}
npx wrangler secret bulk < secrets.json
🌀 Creating the secrets for the Worker "script-name"
✨ Successfully created secret for key: secret-name-1
...
🚨 Error uploading secret for key: secret-name-1
✨ Successfully created secret for key: secret-name-2

Finished processing secrets JSON file:
✨ 1 secrets successfully uploaded
🚨 1 secrets failed to upload

After starting wrangler tail, you will receive a live feed of console and exception logs for each request your Worker receives.

If your Worker has a high volume of traffic, the tail might enter sampling mode. This will cause some of your messages to be dropped and a warning to appear in your tail logs. To prevent messages from being dropped, add the options listed above to filter the volume of tail messages.

:::note

It may take up to 1 minute (60 seconds) for a tail to exit sampling mode after adding an option to filter tail messages. :::

If sampling persists after using options to filter messages, consider using instant logs.

versions

:::note The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the --x-versions flag. :::

:::note

The non-interactive version of this prompt is: wrangler versions deploy version-id-1@percentage-1% version-id-2@percentage-2 -y

For example: wrangler versions deploy 095f00a7-23a7-43b7-a227-e4c97cab5f22@10% 1a88955c-2fbd-4a72-9d9b-3ba1e59842f2@90% -y

:::

triggers

:::note The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the --x-versions flag. :::

deployments

Deployments track the version(s) of your Worker that are actively serving traffic.

:::note The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the --x-versions flag. :::

rollback

:::caution A rollback will immediately create a new deployment with the specified version of your Worker and become the active deployment across all your deployed routes and domains. This change will not affect work in your local development environment. :::

wrangler rollback [<VERSION_ID>] [OPTIONS]
  • VERSION_ID
    • The ID of the version you wish to roll back to. If not supplied, the rollback command defaults to the version uploaded before the latest version.
  • --name
  • --message
    • Add message for rollback. Accepts empty string. When specified, interactive prompts for rollback confirmation and message are skipped.

types

Generate types based on your Worker configuration, including Env types based on your bindings, module rules, and runtime types based on thecompatibility_date and compatibility_flags in your config file.

wrangler types [<PATH>] [OPTIONS]

:::note

:::

Multi-environment support

By default, wrangler types generates types for bindings from all environments defined in your configuration file. This ensures your generated Env type includes all bindings that might be used across different deployment environments (such as staging and production), preventing TypeScript errors when accessing environment-specific bindings.

For example, if you have a KV namespace binding only in production and an R2 bucket binding only in staging, both will be included in the generated types as optional properties.

To generate types for only a specific environment, use the --env flag.

Options

  • PATH
    • The path to where types for your Worker will be written.
    • The path must have a d.ts extension.
  • --env
    • Generate types for bindings in a specific environment only, rather than aggregating bindings from all environments.
  • --env-interface
    • The name of the interface to generate for the environment object.
    • Not valid if the Worker uses the Service Worker syntax.
  • --include-runtime
    • Whether to generate runtime types based on thecompatibility_date and compatibility_flags in your config file.
  • --include-env
    • Whether to generate Env types based on your Worker bindings.
  • --strict-vars
    • Control the types that Wrangler generates for vars bindings.
    • If true, (the default) Wrangler generates literal and union types for bindings (e.g. myVar: 'my dev variable' | 'my prod variable').
    • If false, Wrangler generates generic types (e.g. myVar: string). This is useful when variables change frequently, especially when working across multiple environments.
  • --check
    • Check if the generated types at the specified path are up-to-date without regenerating them.
    • Exits with code 0 if types are up-to-date, or code 1 if types are out-of-date.
    • Useful for CI/CD pipelines and pre-commit hooks to ensure types have been regenerated after configuration changes.
  • --config, -c
    • Path(s) to Wrangler configuration file. If the Worker you are generating types for has service bindings or bindings to Durable Objects, you can also provide the paths to those configuration files so that the generated Env type will include RPC types. For example, given a Worker with a service binding, wrangler types -c wrangler.toml -c ../bound-worker/wrangler.toml will generate an Env type like this:
    interface Env {
	SERVICE_BINDING: Service<import("../bound-worker/src/index").Entrypoint>;
}

check

startup

Generate a CPU profile of your Worker's startup phase.

After you run wrangler check startup, you can import the profile into Chrome DevTools or open it directly in VSCode to view a flamegraph of your Worker's startup phase. Additionally, when a Worker deployment fails with a startup time error Wrangler will automatically generate a CPU profile for easy investigation.

:::note

This command measures performance of your Worker locally, on your own machine — which has a different CPU than when your Worker runs on Cloudflare. This means results can vary widely.

You should use the CPU profile that wrangler check startup generates in order to understand where time is spent at startup, but you should not expect the overall startup time in the profile to match exactly what your Worker's startup time will be when deploying to Cloudflare.

:::

wrangler check startup
  • --args
    • To customise the way wrangler check startup builds your Worker for analysis, provide the exact arguments you use when deploying your Worker with wrangler deploy, or your Pages project with wrangler pages functions build. For instance, if you deploy your Worker with wrangler deploy --no-bundle, you should use wrangler check startup --args="--no-bundle" to profile the startup phase.
  • --worker
    • If you don't use Wrangler to deploy your Worker, you can use this argument to provide a Worker bundle to analyse. This should be a file path to a serialized multipart upload, with the exact same format as the API expects.
  • --pages
    • If you don't use a Wrangler config file with your Pages project (i.e. a Wrangler config file containing pages_build_output_dir), use this flag to force wrangler check startup to treat your project as a Pages project.