Skip to content

docs.md

Latest commit

 

History

History
287 lines (192 loc) · 9.7 KB

docs.md

File metadata and controls

287 lines (192 loc) · 9.7 KB
Raw

Developer guide for setting up, configuring, developing, and deploying the project:

Complete developer guide for contributing to this project or creating your own version to run on Cloudflare Workers using Wrangler.

Note: this project does not include a package.json, and it does not require any npm dependencies.

🚀 Getting started with GitHub Codespaces:

The project provides a pre-configured Dev Container environment for GitHub Codespaces, making it quick and easy to start coding.

Using Codespaces is the recommended way to work on the project because it automatically sets up the required elements and provides a ready-to-code environment.

1. Configure the required secrets:

Before you start a new Codespaces environment and begin coding in it, you need to register the required secrets in the repository's GitHub Codespaces Secrets.

See the environment variables section for the required configuration and the GitHub Codespaces secrets documentation for more details.

2. Open the repository in GitHub Codespaces:

Open the repository on GitHub and create a new Codespace from the Code → Codespaces menu.

GitHub will automatically detect the project's .devcontainer.json configuration and build the development environment.

3. Automatic environment setup:

The .devcontainer.json file defines the complete development environment:

  • Ubuntu-based development container

  • Node.js 24

  • Cloudflare Wrangler

  • Required environment variables

  • Generated TypeScript definitions for Cloudflare Worker bindings

The setup is executed automatically when the Codespace is created via postCreateCommand. The Codespace is created with environment variables that are automatically read from the Codespaces environment and written to .dev.vars by the dev container setup, Wrangler is installed, and types are initialized.

Wrangler is intentionally installed globally inside the Codespace to keep the repository free of Node.js project dependencies.

Note: .dev.vars is a local development file and must never be committed to the repository. It's already been added to the .gitignore.

4. Authenticate with Cloudflare:

Once the Codespace has finished initializing, authenticate Wrangler with your Cloudflare account:

wrangler login

⚙️ Configuration setup:

Review the wrangler.jsonc file, which contains the complete project configuration:

{
	"name": "project-name",
	"main": "main.ts",
	"compatibility_date": "2026-03-08",
	"preview_urls": false,
	"observability": {
		"enabled": true,
		"head_sampling_rate": 1,
		"logs": {
			"invocation_logs": false
		},
		"traces": {
			"enabled": false
		}
	}
}

Core configuration fields:

name

Defines the Worker project name. This determines your public URL (e.g., https://project-name.your-subdomain.workers.dev).

main

Specifies the entry point of your Worker script. This file exports your main fetch handler.

compatibility_date

Locks your Worker to a specific Cloudflare Workers runtime version. Ensures compatibility even as Cloudflare updates the platform.

preview_urls

Enables or disables preview URLs for testing.

  • true = Enables preview URLs
  • false = Disables preview URLs

For more details: https://developers.cloudflare.com/workers/configuration/previews/

Observability configuration:

observability.enabled

When true, enables automatic metrics and logs collection. Allows performance and error monitoring in the Cloudflare dashboard.

observability.head_sampling_rate

Defines the percentage of requests sampled for tracing (0 to 1):

  • 1 = 100% sampling (useful for debugging)
  • 0.1 = 10% sampling (better for production)

observability.logs.invocation_logs

Controls automatic invocation log collection:

  • true = Logs request metadata, headers, and execution details
  • false = Disables automatic logs, keeping only custom console.log entries

Disabling invocation logs is recommended for GDPR compliance to prevent storage of sensitive request data.

observability.traces.enabled

Controls distributed tracing:

  • true = Enables tracing spans and trace IDs
  • false = Disables tracing entirely

Leave disabled if not using OpenTelemetry or a tracing system.

Environment variables:

The Worker uses environment variables for local development and Cloudflare secrets for production.

Variable in this project:

Variable Description
HASH_KEY Cryptographic key for hashing user IP addresses

Local development:

Create/configure the following value as GitHub Codespaces secrets. When the Codespace is created, .devcontainer.json automatically writes it to .dev.vars:

HASH_KEY="THE_KEY_USED_TO_HASH_IPS"

Production:

For the deployed Worker, configure the same value as Cloudflare Workers secrets:

wrangler secret put HASH_KEY

For more details: https://developers.cloudflare.com/workers/configuration/secrets/

Software configuration: config.ts

export const config: StaticConfig = {

	RATE_LIMIT_INTERVAL_S: 1, // Min: 1
	
	MAX_RANDOM_METEORITES: 1000, // Min: 100
	
	MAX_RETURNED_SEARCH_RESULTS: 500, // Min: 100
	
	MIN_RADIUS: 1, // Min: 1
	
	MAX_RADIUS: 2500, // Min: 1000
	
	DEFAULT_RANDOM_NUMBER_OF_METEORITES: 100 // Min: 100

};

Configuration parameters:

Parameter Description Constraints
RATE_LIMIT_INTERVAL_S Rate limit interval in seconds Minimum: 1s
MAX_RANDOM_METEORITES Maximum meteorites returned by /random Minimum: 100
MAX_RETURNED_SEARCH_RESULTS Maximum meteorites returned by /search Minimum: 100
MIN_RADIUS Minimum allowed search radius (km) Minimum: 1km
MAX_RADIUS Maximum allowed search radius (km) Minimum: 1000km
DEFAULT_RANDOM_NUMBER_OF_METEORITES Default count for /random if not specified Minimum: 100

Important: MAX_RANDOM_METEORITES must always be greater than DEFAULT_RANDOM_NUMBER_OF_METEORITES. If this condition is not met, the configuration will produce errors.

🖧 Development server:

Once your Codespace is ready and your Cloudflare account is authenticated, you're ready to start coding, but some explanation of TypeScript types and the running process will be provided in this section.

1. TypeScript types:

The Dev Container automatically runs wrangler types when the Codespace is created, generating the Worker bindings in worker-configuration.d.ts (there are no bindings in this project at the moment).

If you change your Wrangler configuration or bindings, regenerate the definitions manually with:

wrangler types

Ensure wrangler.jsonc is properly configured before regenerating the types.

This generates TypeScript type definitions, which are already included in tsconfig.json:

{
    "compilerOptions": {
        "noEmit": true,
        "allowImportingTsExtensions": true,
        "target": "ES2020",
        "lib": [
            "ES2020",
            "DOM"
        ],
        "module": "ESNext",
        "moduleResolution": "Bundler",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "types": [
            "./worker-configuration.d.ts"
        ],
        "resolveJsonModule": true
    },
    "include": [
        "utilities",
        "worker-configuration.d.ts",
        "main.ts",
        "config.ts",
        "types"
    ],
    "exclude": [
        "node_modules",
        "dist"
    ]
}

TypeScript configuration explanation:

Setting Purpose
noEmit: true Prevents TypeScript from emitting JS locally; Wrangler handles bundling
allowImportingTsExtensions: true Allows direct .ts file imports for relative paths
target: "ES2020" Uses modern JavaScript syntax supported by Workers runtime
lib: ["ES2020", "DOM"] Includes modern JS features and Web APIs (fetch, Request, Response)
module: "ESNext" Uses ES Modules standard for Workers
moduleResolution: "Bundler" Configures module resolution for bundler-based ESM environments
strict: true Enables all strict type checking for safer code
esModuleInterop: true Facilitates CommonJS interoperability
skipLibCheck: true Skips type checking for .d.ts files to speed up compilation
forceConsistentCasingInFileNames: true Prevents file casing errors across operating systems
types: ["./worker-configuration.d.ts"] Includes Wrangler binding type definitions
resolveJsonModule: true Allows importing JSON files as modules
include Source files and types to type check
exclude Build artifacts and dependencies to ignore

2. Run and deploy:

Start local development:

wrangler dev

Deploy to Cloudflare Workers:

Make sure your Cloudflare Workers secrets have been configured before deploying. See environment variables.

wrangler deploy

If the Worker is configured with a workers.dev deployment, Wrangler will display the deployed URL.

📌 Support:

For issues or questions, open an issue on GitHub.