Server Configuration (wrangler.toml)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/server/wrangler.raw.toml
• packages/server/vite.config.ts
• packages/server/src/constants/binding.ts
• packages/server/src/api/pages.ts
• packages/server/package.json

The wrangler.toml file is the primary configuration manifest for the web-archive server, which runs as a Cloudflare Worker. This file dictates how the Worker is built, deployed, and how it interacts with other Cloudflare services. It defines essential metadata, compatibility settings, and, most importantly, the bindings that connect the application code to infrastructure resources like the D1 database, R2 storage buckets, and Workers AI.

The project uses a template-based approach for this configuration. A source file, wrangler.raw.toml, serves as a template. During the build process, this file is copied and renamed to wrangler.toml within the distribution directory. This allows for a clean separation between source configuration and the final build artifact used by Cloudflare's wrangler CLI.

Sources: packages/server/wrangler.raw.toml, packages/server/vite.config.ts:25-29

Configuration Build Process

The final wrangler.toml file is not checked into source control directly. Instead, it is generated from packages/server/wrangler.raw.toml during the Vite build process. The vite-plugin-static-copy plugin is configured to handle this transformation.

This diagram illustrates the flow from the raw template to the final configuration file used for deployment.

The vite.config.ts file contains the specific instruction for this operation.

// packages/server/vite.config.ts:24-30
      viteStaticCopy({
        targets: [
          {
            src: ['./wrangler.raw.toml'],
            dest: '../',
            rename: 'wrangler.toml',
          },

This process is triggered by running the build script defined in packages/server/package.json.

Sources: packages/server/vite.config.ts:15-37, packages/server/package.json:6

Core Configuration

The wrangler.raw.toml file specifies the fundamental properties of the Cloudflare Worker.

Parameter	Value	Description
name	web-archive-service	The name of the worker service in the Cloudflare dashboard.
main	src/server.js	The entry point file for the worker, located inside the dist/service directory after the build.
compatibility_date	2024-05-18	Ensures the worker runs with a specific version of the Cloudflare Workers runtime API for stable behavior.
pages_build_output_dir	../../dist/web	Specifies the directory containing the static assets for the web client, which are served by Cloudflare Pages.

Sources: packages/server/wrangler.raw.toml:1-5

Service Bindings

Bindings are the mechanism by which the Worker code gains access to Cloudflare resources. They are defined in wrangler.toml and exposed as environment variables within the Hono application context (c.env).

The following diagram shows how the bindings defined in wrangler.toml connect the Hono server application to various Cloudflare services.

D1 Database (d1_databases)

The application binds to a D1 database for storing metadata about archived pages, folders, and tags.

• Binding Name: DB
• Configuration:

  # packages/server/wrangler.raw.toml:8-11
  [[d1_databases]]
  binding = "DB"
  database_name = "web-archive-db"
  database_id = "59359d56-5232-4428-85a2-09c3401b97a6"
  

• TypeScript Definition: The binding is typed for use in the application.

  // packages/server/src/constants/binding.ts:2
  export type HonoType = {
    Bindings: {
      DB: D1Database
      // ... other bindings
    }
    // ...
  }
  

• Usage Example: The DB binding is used throughout the API to perform database operations.

  // packages/server/src/api/pages.ts:101-106
  const insertId = await insertPage(c.env.DB, {
    title,
    pageDesc,
    pageUrl,
    contentUrl,
    folderId,
    screenshotId,
    isShowcased,
  })
  

Sources: packages/server/wrangler.raw.toml:8-11, packages/server/src/constants/binding.ts:2-13, packages/server/src/api/pages.ts:101

R2 Storage (r2_buckets)

An R2 bucket is used to store the actual HTML content and screenshots of the archived pages.

• Binding Name: BUCKET
• Configuration:

  # packages/server/wrangler.raw.toml:13-15
  [[r2_buckets]]
  binding = "BUCKET"
  bucket_name = "web-archive-bucket"
  

• TypeScript Definition:

  // packages/server/src/constants/binding.ts:6
  export type HonoType = {
    Bindings: {
      // ...
      BUCKET: R2Bucket
      // ...
    }
    // ...
  }
  

• Usage Example: The BUCKET binding is used to save and retrieve files.

  // packages/server/src/api/pages.ts:94-97
  const [contentUrl, screenshotId] = await Promise.all([
    saveFileToBucket(c.env.BUCKET, pageFile),
    saveFileToBucket(c.env.BUCKET, screenshot),
  ])
  

Sources: packages/server/wrangler.raw.toml:13-15, packages/server/src/constants/binding.ts:2-13, packages/server/src/api/pages.ts:95-96

Workers AI (ai)

The project leverages Workers AI, likely for features like automatic tagging.

• Binding Name: AI
• Configuration:

  # packages/server/wrangler.raw.toml:17-18
  [ai]
  binding = "AI"
  

• TypeScript Definition:

  // packages/server/src/constants/binding.ts:7
  export type HonoType = {
    Bindings: {
      // ...
      AI: Ai
    }
    // ...
  }
  

Sources: packages/server/wrangler.raw.toml:17-18, packages/server/src/constants/binding.ts:2-13

Variables and Secrets (vars)

Secrets and environment variables are managed through the vars block. This is used for storing the authentication key.

• Variable Name: AUTH_KEY_SECRET
• Configuration:

  # packages/server/wrangler.raw.toml:20-22
  [vars]
  # This value will be replaced by the secret in the cloudflare dashboard
  AUTH_KEY_SECRET = "a-random-string"
  

  For local development, a .dev.vars file is used, but in production, this value is intended to be replaced by a secret configured in the Cloudflare dashboard.
• TypeScript Definition:

  // packages/server/src/constants/binding.ts:8
  export type HonoType = {
    Bindings: {
      // ...
      AUTH_KEY_SECRET: string
    }
    // ...
  }
  

Sources: packages/server/wrangler.raw.toml:20-22, packages/server/src/constants/binding.ts:2-13

Summary

The wrangler.toml configuration is the cornerstone of the web-archive server's architecture. It acts as the declarative link between the Hono application code and the Cloudflare services it depends on. The build process, which generates wrangler.toml from a template, ensures a consistent and manageable configuration for both local development and production deployments. Understanding this file and its bindings is crucial for comprehending how the server functions and interacts with its cloud environment.