Cloudflare Setup

Deploy your tag bundles to Cloudflare's global edge network for sub-millisecond latency and infinite scalability.

Architecture

YourTM uses Cloudflare R2 (object storage) for maximum performance and cost efficiency:

The Edge-Native Advantage

YourTM is the first tag manager built from the ground up to leverage the Cloudflare Edge. By using R2 Object Storage and the global CDN, we've eliminated the performance "tax" associated with traditional tag managers.

Key Benefits

• Global Distribution - Your tags are cached in 300+ edge locations, physically closer to your users.
• Zero-Latency Logic - Zone detection happens at the edge, so the browser only ever sees the code it needs.
• Infinite Scalability - Built on the same infrastructure that powers 20% of the internet.
• Free Tier Friendly - R2's generous free tier (10M reads/mo) means most production sites run for free.

Requirements

To deploy to Cloudflare, you'll need:

Cloudflare Pricing

With R2 architecture, YourTM is extremely cost-effective:

R2 Storage (Static Bundles)

Workers (API Only - Optional)

Step 1: Create a Cloudflare Account

If you don't have a Cloudflare account:

Step 2: Create an API Token

YourTM needs an API token to deploy Workers and manage KV storage.

https://dash.cloudflare.com/profile/api-tokens

Step 3: Run Deploy Init

The ytm deploy init command sets up everything automatically:

ytm deploy init

The interactive wizard will prompt you:

🚀 YourTM Cloudflare Setup
──────────────────────────────

  Container ID   YTM-MYSITE
  Container Name My Website Tags

? Cloudflare Account ID: a1b2c3d4e5f6g7h8i9j0
? Cloudflare API Token: ****************************

✔ API token validated

? Which environment(s) to set up?
  ❯ Production only
    Staging only
    Both (staging + production)

? Storage mode for tag bundles:
  ❯ R2 Bucket (Recommended) - Fast CDN delivery, no Worker invocations
    KV Namespace (Legacy)   - Worker serves all requests

✔ Created R2 bucket "ytm-mysite"
✔ Public access enabled: https://pub-a1b2c3d4.r2.dev/ytm-mysite

? Deploy API worker for telemetry and preview mode? (optional) No

✔ Updated yourtm.config.ts

🎉 Cloudflare setup complete!

Created resources:
  R2 Bucket: ytm-mysite
    Public URL: https://pub-a1b2c3d4.r2.dev/ytm-mysite

Add this to your site:
  <script src="https://pub-a1b2c3d4.r2.dev/ytm-mysite/latest/core.js" async></script>

Architecture:
  • Static bundles served from R2 CDN (fast, low cost)
  • No Worker invocations for bundle requests

Next steps:
  1. Run 'ytm build' to compile your tags
  2. Run 'ytm deploy' to publish to Cloudflare

Command Options

CI/CD Setup

For automated deployments, use environment variables or flags:

ytm deploy init \
  --account-id $CLOUDFLARE_ACCOUNT_ID \
  --api-token $CLOUDFLARE_API_TOKEN \
  --env production \
  --yes

Configuration File

After running deploy init, your config is updated:

import { defineConfig } from '@yourtm/core'

export default defineConfig({
  container: {
    id: 'YTM-MYSITE',
    name: 'My Website Tags',
  },

  // Cloudflare configuration (added by deploy init)
  cloudflare: {
    accountId: 'a1b2c3d4e5f6g7h8i9j0',
    // R2 bucket for static bundles (recommended)
    r2BucketName: 'ytm-mysite',
    r2PublicUrl: 'https://pub-a1b2c3d4.r2.dev/ytm-mysite',
    // Optional: Custom domain
    // r2PublicUrl: 'https://cdn.mysite.com',
    // Optional: Worker for API (telemetry, preview)
    // workerUrl: 'https://ytm-api.workers.dev',
  },
})

Legacy KV Configuration

If using legacy KV mode (--legacy-kv):

  cloudflare: {
    accountId: 'a1b2c3d4e5f6g7h8i9j0',
    workerName: 'yourtm-cdn',
    kvNamespaceId: 'kv-namespace-id-production',
  },

Credentials Storage

YourTM looks for credentials in this order:

1. Environment Variables (recommended for CI/CD)

   export CLOUDFLARE_API_TOKEN="your-token"
   export CLOUDFLARE_ACCOUNT_ID="your-account-id"

2. Credentials File (for local development)
   ~/.yourtm/credentials.json

   {
     "cloudflare": {
       "apiToken": "your-token",
       "accountId": "your-account-id"
     }
   }

3. Config File (not recommended for tokens)

   cloudflare: {
     accountId: 'your-account-id',
     // Don't put apiToken in config - use env vars
   }

Multiple Environments

YourTM supports staging and production environments with separate storage:

# Set up both environments
ytm deploy init --env both

# Deploy to staging first
ytm deploy -e staging

# Then promote to production
ytm deploy -e production

Each environment has its own:

• KV namespace (isolated storage)
• Version history
• Rollback capability

Deploying

After initial setup, deploy with:

# Build and deploy to staging
ytm build && ytm deploy -e staging

# Deploy to production
ytm deploy -e production

# Deploy with a message
ytm deploy -e production -m "Added TikTok pixel"

Deploy output:

Deploying to production...
──────────────────────────────

  Container     YTM-MYSITE
  Environment   production
  Version       v1.2.3

Uploading bundles:
  ✔ core.js                 2.06 KB
  ✔ zone-global.js          1.92 KB
  ✔ zone-checkout.js          635 B
  ✔ zone-product.js           229 B

✔ Deploy successful!

  CDN URL: https://yourtm-cdn.your.workers.dev/c/YTM-MYSITE/core.js
  Version: v1.2.3
  Time:    1.2s

Rollback

If something goes wrong, rollback instantly:

# Quick rollback to previous version
ytm rollback quick -e production

# Rollback to specific version
ytm rollback v1.2.2 -e production

# View version history
ytm deploy versions -e production

Custom Domain

By default, your bundles are served from:

https://yourtm-cdn.YOUR_SUBDOMAIN.workers.dev/c/CONTAINER_ID/core.js

To use a custom domain like cdn.yourdomain.com:

<script src="https://cdn.yourdomain.com/latest/core.js"></script>

Troubleshooting

Authentication Errors

Error: Authentication failed (10000)

Solution: Check that your API token has the correct permissions and hasn't expired.

KV Namespace Not Found

Error: KV namespace not found

Solution: Run ytm deploy init again or check that the namespace ID in config is correct.

Worker Deploy Failed

Error: Worker upload failed

Solutions:

• Check your Workers quota (free tier: 100,000 requests/day)
• Ensure "Workers Scripts: Edit" permission is set
• Try deploying with --skip-worker and deploy worker manually

Slow Response Times

If bundle loading is slow:

• Check bundle sizes with ytm build
• Ensure caching headers are working (check response headers)
• Verify you're loading from the edge (check CF-Ray header)

Getting Help

If you're still having issues:

• Open a GitHub issue
• Include output of ytm status and ytm deploy versions