Worker-setup NPM

Worker Setup

David

Interactive setup and deployment of pre-made Cloudflare Workers

demo

👋 Introduction

While wrangler generate is meant to generate a completely new worker from an existing template, worker-setup is meant to setup a pre-made Worker like cf-worker-redirect.

The basic wrangler configuration, required KV Namespaces, secrets and environment variables are stored in the workerConfig.toml file. When a user wants to setup your Worker, they can simply run worker-setup deploy and they will be guided through the process of logging in to their account, setting up and deploying the Worker. Required KV Namespaces are automatically created and the user is asked to input all required secrets and environment variables.

⭐ Features

Generates ready-to-use wrangler.toml file filled with user specific values like Account/Zone/KV Namespace ID
Installs and configures Wrangler (Including authenticating with Cloudflare)
Automatically creates required KV Namespaces
Prompts the user for required Secrets and Environment Variables (and uploads them)
Lets the user choose between deploying to workers.dev or a custom Zone
Can dynamically fill wrangler.toml with user specific values using environment variables (useful for CI)

🚀 Get started

Install worker-setup via npm:

npm install worker-setup

See below on how to configure worker-setup for your own Worker.

📚 Usage

Run worker-setup help to see all available commands and options.

Here's an overview of the available commands:

Deploy

worker-setup deploy

Will start the interactive deployment process. You will be asked to login with Cloudflare if not already logged in. Required KV Namespaces are automatically created and you are asked to input all required secrets and environment variables. The final wrangler.toml will be generated from the template.

Generate

worker-setup generate

Will use a local workerConfig.toml and environment variables/.env file to generate a wrangler.toml (useful for CI purposes).

Login

worker-setup login

Will authenticate Wrangler with Cloudflare, either via the browser or by specifying an API token.

Migrate

worker-setup migrate

Will migrate your old wrangler.toml to a new workerConfig.toml by removing all personal fields, like account/zone id as well as the ids for kv_namespaces and values for environment variables and adding wrangler.toml to your .gitignore file. All other options will be transfered to the new config.

🛠️ Setup

worker-setup uses a workerConfig.toml file which replaces your normal wrangler.toml. It supports everything you normally put into your wrangler.toml file as well as more (see below).

If you have an existing wrangler.toml, run the following to generate a new workerConfig.toml from your config:

worker-setup migrate

If not, create a new workerConfig.toml file and fill it with your normal Wrangler configuration options manually.

If your Worker uses Workers KV or requires secrets/environment variables add the binding/keys as well.

When you run worker-setup deploy, worker-setup will use the workerConfig.toml file to know what your Worker needs and asks the user to input the required values, as well as create the required KV Namespaces. Once everything is done, it will output a normal wrangler.toml file and deploy the worker with wrangler.

⚙️ Configuration

The workerConfig.toml file supports the following configuration options:

Key	Description	Required
`name`	The default name of your Worker (can be changed by the user during setup)	Yes
`type`	Specifies how `wrangler build` will build your project.	Yes
`webpack_config`	This is the path to a custom webpack configuration file for your worker.	No
`site`	Determines the local folder to upload and serve from a Worker	No
`usage_model`	Specifies the Usage Model for your Worker.	No
`triggers`	Configures cron triggers for executing a Worker on a schedule	No
`dev`	Arguments for `wrangler dev`, configure local server	No
`build`	Allows configuring a custom build step to be run by wrangler when building your worker.	No

See wrangler's docs for more info on each option.

As well as these additional options:

Key	Description	Required	Example
`kv_namespaces`	Specify the required KV namespace bindings (will be created during setup)	No	`[ "EXAMPLE_KV" ]`
`secrets`	Specify the required secrets (user will be asked to input during setup)	No	`[ "EXAMPLE_SECRET" ]`
`variables`	Specify the required plain-text variables (user will be asked to input during setup)	No	`[ "EXAMPLE_VARIABLE" ]`
`recommended_route`	A recommended route to be used with the Worker (will be shown to user)	No	`"*example.com/test"`
`instructions`	Specify additional instructions to be printed after deploying the worker	No	`Learn how to use the Worker at example.com`

📖 Examples

Here are a few examples to help you get started!

📝 Intructions for your README

Here are example intructions you can use in the README for your Worker:

If you want to deploy this Worker yourself, clone this repo and cd into it:

git clone https://github.com/betahuhn/cf-worker-redirect && cd cf-worker-redirect

Next start the interactive deployment process:

worker-setup deploy

You will be asked to login to Cloudflare if not already authenticated. The programm will guide you through the process of setting up and deploying the Worker under your own Cloudflare Account.

💻 Development

run yarn lint or npm run lint to run eslint.
run npm link to setup the program for development.
run yarn build or npm run build to produce a compiled version in the dist folder.