TickPick Cloudflare Workers Monorepo

Introduction

Welcome to the TickPick Cloudflare Workers monorepo. This repository manages the development, deployment, and maintenance of multiple Cloudflare Workers for TickPick. These Workers act as edge servers, routing incoming requests to appropriate service handlers or proxying them to origin APIs when necessary. Deployment is facilitated using Wrangler, enabling configuration for various environments and zones managed by Cloudflare.

Table of Contents

• Project Structure
• Getting Started
  • Prerequisites
  • Cloning the Repository
  • Installing Dependencies
• Development Workflow
  • Local Development
    • Using .dev.vars for Local Variables
    • Running the Development Server
  • Environment Bindings and TypeScript Definitions
    • Generating worker-configuration.d.ts
    • Updating Bindings
  • Viewing Production Logs
  • Deployment
• Additional Information
  • Wrangler Environments
  • Environment Variable Management
  • Using Yarn
• Contributing
• Support

Project Structure

Directory Organization

• src/workers/: Contains subdirectories for each Cloudflare Worker. Examples include:

  • src/workers/datafeeds
  • src/workers/events

• Each Worker directory includes:

  • index.ts: The main entry point for the Worker.
  • wrangler.toml: Configuration file defining how the Worker is deployed across different environments.
  • .dev.vars (optional): Defines local environment variables for development.

• src/: Contains shared code such as constants, helper methods, interfaces, and modules used across multiple Workers.

Getting Started

Prerequisites

• Yarn Package Manager: Ensure you have Yarn installed. The project uses Yarn for dependency management to maintain consistency across development environments.

• Wrangler CLI: Install Wrangler globally to manage and deploy Cloudflare Workers.

  yarn global add wrangler
  

  Alternatively, if you prefer NPM:

  npm install -g wrangler
  

Note: It's crucial to use Yarn for managing dependencies. Avoid using NPM within this project to prevent conflicts between yarn.lock and package-lock.json, which can cause issues in Azure DevOps build pipelines.

Cloning the Repository

Clone the repository to your local machine:

git clone [repository-url]
cd [repository-directory]

Installing Dependencies

Install the project dependencies using Yarn:

yarn install

Development Workflow

Local Development

Using .dev.vars for Local Variables

When running wrangler dev --remote, you may need to define local environment variables that differ from production settings. To do this, create a .dev.vars file in the root directory of the specific Worker you're working on (e.g., src/workers/datafeeds/.dev.vars).

Example .dev.vars file:

API_BASEURL=http://localhost:5000/api
DATAFEEDS_ACCESSTOKEN=your-local-access-token

This file allows you to override environment variables during local development without affecting the production configuration.

Important: Do not commit .dev.vars files to version control, as they may contain sensitive information.

Running the Development Server

To start a local development server for a specific Worker:

1. Navigate to the Worker's directory:

   cd src/workers/datafeeds
   

2. Run the development server:

   wrangler dev --remote
   

3. When prompted, select TickPick LLC as the account.

This command starts a development server at https://localhost:8787/, using the configuration variables specified in the .dev.vars file.

Environment Bindings and TypeScript Definitions

Generating worker-configuration.d.ts

When you define environment variables and bindings in wrangler.toml, you can generate corresponding TypeScript definitions using Wrangler. This ensures that TypeScript recognizes the bindings and provides type checking and autocomplete features.

To generate or update the worker-configuration.d.ts file:

wrangler types

This command creates a worker-configuration.d.ts file in the Worker's directory, containing the type definitions for the environment variables and bindings.

Updating Bindings

Whenever you change the environment bindings in a Worker's wrangler.toml file (e.g., adding a new variable or KV namespace), you must regenerate the TypeScript definitions:

1. Modify wrangler.toml with the new bindings.

2. Run:

   wrangler types
   

3. Ensure that worker-configuration.d.ts is updated accordingly.

Note: Keeping worker-configuration.d.ts up-to-date is essential to prevent type mismatches and to improve the developer experience by providing accurate type information.

Viewing Production Logs

To view live logs from a deployed Worker:

wrangler tail [worker-name]

Select the TickPick LLC account when prompted. This will stream logs in real-time, allowing you to monitor the Worker's behavior in the production environment.

Deployment

Using Azure DevOps CI/CD Pipelines

Deployment to Cloudflare's edge network is managed via Azure DevOps CI/CD pipelines. This ensures consistent deployments and proper handling of environment variables and secrets across different environments (development, staging, production).

Important: Do not deploy Workers directly using wrangler publish. Manual deployments can override environment variables and disrupt the configuration. Always use the established CI/CD pipelines for deploying changes.

Additional Information

Wrangler Environments

Wrangler supports multiple environments, allowing you to define different configurations for development, staging, and production. Environments are specified in the wrangler.toml file using [env.name] sections.

Example wrangler.toml:

name = "my-worker"
type = "webpack"
account_id = "your-account-id"

[vars]
API_BASEURL = "#{ORIGIN}#"

[env.production]
vars = { API_BASEURL = "https://api.tickpick.com/1.0/" }

[env.development]
vars = { API_BASEURL = "http://localhost:5000/api" }

In this example, #{ORIGIN}# is a placeholder that gets replaced with the appropriate value during the deployment process via the CI/CD pipelines.

For more information on Wrangler environments, refer to the Cloudflare Workers Environments Documentation.

Environment Variable Management

In production pipelines, generic variable placeholders in wrangler.toml (e.g., #{ORIGIN}#) are replaced with site-specific variables during deployment. This allows the same codebase to be used across different environments and domains, such as:

• api.tickpick.com/1.0/ for TickPick
• api.simpleseats.com/1.0/ for SimpleSeats

This approach ensures consistency and reduces the need for environment-specific code changes.

Using Yarn

Consistently using Yarn for dependency management is crucial for maintaining the integrity of the build process. Yarn's lock file (yarn.lock) ensures that all developers and build agents use the same package versions.

Avoid using NPM within this project to prevent conflicts and potential issues in Azure DevOps pipelines.