DEV Community: Dale Nguyen

How I Almost Got Pwned - A Tale of Supply Chain Attacks and GitHub Actions Gone Wrong

Dale Nguyen — Fri, 12 Sep 2025 02:35:15 +0000

Or: "That time someone tried to turn my innocent Node.js repo into a credential-harvesting machine"

So there I was, minding my own business with my trusty old Node.js REST API project, when I noticed something weird in the package-lock.json file from one of a PR from a random contributor - and another contributor actually approved the PR right after that. What started as a routine dependency check turned into a rabbit hole that led me straight into the middle of a supply chain attack campaign that was actively targeting developers like us.

Buckle up, because this is a story about how modern software development can go sideways fast, and why that "helpful" pull request might not be so helpful after all.

What Even Is a Supply Chain Attack?

It’s when hackers sneak bad stuff (malware, credential stealers, you name it) into your dependencies, build scripts, or CI/CD pipelines—any link where code, secrets, and environments touch. Think: “If I can poison upstream, why bother attacking thousands of repos individually?” Welcome to modern risk!

It's insidious because these are the tools we trust implicitly. When lodash releases an update, we don't usually audit every line of code, right? We just npm update and move on with our lives.

The Smoking Gun: The Lockfile Had Been Tampered With

It all started when I was reviewing the package-lock.json from the pull request. I noticed something that made my developer spidey-senses tingle - together with the recent NPM hack news on Sep 2025:

// BEFORE (Normal, secure)
"@types/body-parser": {
  "version": "1.17.0",
  "requires": {
    "@types/connect": "3.4.32",
    "@types/node": "10.12.18"
  }
}

// AFTER (Sus as hell)
"@types/body-parser": {
  "version": "1.17.0",
  "dependencies": {
    "@types/connect": "*",
    "@types/node": "*"
  }
}

Those little asterisks? Those are wildcards that basically tell npm "give me whatever version you feel like." It's like ordering food and telling the waiter "surprise me" – except the surprise might be malware.

This change completely bypasses version pinning, which is one of our main defenses against supply chain attacks. With wildcards, if any of those packages gets compromised later, you'll automatically pull the malicious version on your next install.

Enter the "Helpful" Contributor

Then I found the smoking gun: a pull request from September 5, 2025, submitted by a user called harshitcodez19. The PR looked innocent enough – just adding some CI/CD with GitHub Actions. How thoughtful!

name: Build on PR
# Heello this is a ymk file made up for cICD
on:
  push:
    branches:
      - main # ← Wait, my repo uses 'master'
  pull_request:
    branches:
      - main # ← This is wrong too...

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm install # ← Should be 'npm ci' for security

      - name: Run Build
        run: npm run build

At first glance, this looks like a newbie trying to be helpful. The typos in the comment ("Heello", "ymk", "cICD") make it seem like someone who's just learning. The branch configuration is wrong, so it wouldn't even run.

But here's the thing – this is exactly how the GhostAction campaign operates.

The GhostAction Campaign: When GitHub Actions Turn Evil

The timing of this PR wasn't coincidental. September 5, 2025 was when security researchers first detected the GhostAction campaign – a sophisticated supply chain attack targeting GitHub repositories.

Here's how GhostAction works:

Reconnaissance: Attackers identify repositories with outdated dependencies
Social Engineering: Submit "helpful" PRs adding CI/CD workflows
Intentional Sabotage: Include obvious mistakes to avoid immediate execution
Patience: Wait for maintainers to "fix" the obvious issues
Exploitation: When the workflow runs, it harvests secrets and credentials

The genius is in the plausible deniability. The PR looks like a well-meaning but inexperienced contributor. The "mistakes" make it seem harmless. But once those workflows run with the right permissions, game over.

The Attack Vector Breakdown

Let's dissect what would have happened if I'd merged this PR:

# The branch misconfiguration prevents immediate execution
on:
  push:
    branches:
      - main # My repo uses 'master', so this won't trigger

This gives the attacker time. If I had "fixed" the obvious branch issue and merged it, the workflow would then:

- name: Install Dependencies
  run: npm install # Pulls wildcarded dependencies

With those wildcards in my lockfile, npm install would fetch the latest versions of @types/node and @types/connect. If those packages had been compromised (which is exactly what the broader npm hack was doing), my CI environment would install malware with full access to:

GitHub secrets
AWS credentials
Database connection strings
API keys
Deploy tokens

Basically, everything you need to completely own my infrastructure.

The Broader Context: The Great NPM Hack of 2025

This attack was part of a much larger campaign according to OX Security's research.

The attackers were:

Compromising legitimate package maintainer accounts
Injecting malicious code into trusted packages
Specifically targeting CI/CD environments
Using GitHub Actions to exfiltrate credentials

My old lockfile, with packages from 2018-2019, was the perfect target. Outdated dependencies are like old locks – they work until someone with the right tools shows up.

Red Flags I Should Have Caught Earlier

Looking back, there were several warning signs:

1. The Contributor Profile

harshitcodez19 had minimal contribution history
Random username pattern typical of throwaway accounts
No established relationship with my project

2. The "Mistakes" Were Too Convenient

Wrong branch names that prevent immediate execution
Typos that create plausible deniability
Using npm install instead of the more secure npm ci

3. The Timing

Submitted on September 5, 2025 (exact GhostAction detection date)
My lockfile wildcards appeared around the same timeframe
Coincided with broader npm supply chain compromises

What Could Have Gone Wrong

If this attack had succeeded, here's what the attacker could have done:

# In my compromised CI environment:
echo $AWS_SECRET_ACCESS_KEY  # Exfiltrate cloud credentials
echo $DATABASE_URL          # Steal database access
echo $DEPLOY_TOKEN          # Compromise deployment pipeline

# Then pivot to:
# - Deploy backdoors to production
# - Access customer data
# - Crypto mining on my infrastructure
# - Lateral movement to other systems

The blast radius from a successful CI compromise is enormous because CI environments typically have elevated permissions to deploy, test, and integrate with other services.

Best Practices: How to Not Get Pwned

Here's what I learned and what you should do to protect yourself:

1. Lockfile Hygiene

# Always use npm ci in production/CI
npm ci  # Uses exact lockfile versions

# Never use npm install in CI
npm install  # Can update versions unexpectedly

// Keep your lockfile pinned
"dependencies": {
  "@types/node": "10.12.18",  // ✅ Exact version
  "@types/connect": "*"       // ❌ Wildcard = danger
}

2. CI/CD Security

# Secure GitHub Actions workflow
name: Secure Build
on:
  pull_request:
    branches: [master] # Correct branch names

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # Latest version

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm' # Cache for performance

      # Use npm ci for reproducible builds
      - name: Install dependencies
        run: npm ci

      # Audit before building
      - name: Security audit
        run: npm audit --audit-level=critical

      - name: Build
        run: npm run build

3. Dependency Management

# Regular maintenance
npm outdated        # Check for updates
npm audit          # Security vulnerabilities
npm audit fix      # Auto-fix where possible

# Keep dependencies current
npm update         # Update within semver ranges

4. PR Review Guidelines

When reviewing PRs that touch CI/CD or dependencies:

Who is the contributor? Do they have a history with your project?
Why are they making this change? Unsolicited CI/CD PRs are suspicious
What permissions would this grant? Review secrets and environment access
Are there obvious "mistakes"? Sometimes bugs are features for attackers

5. Repository Protection

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    schedule:
      interval: 'weekly'
    reviewers:
      - 'your-username'

Enable branch protection rules:

Require PR reviews for CI/CD changes
Require status checks to pass
Restrict who can modify workflows

The Human Element

The scariest part of supply chain attacks isn't the technical sophistication – it's how they exploit our human nature. We want to be helpful to contributors. We want to trust the tools we use daily. We want to merge that PR that "fixes" an obvious mistake.

But in the age of automated attacks and compromised packages, a little paranoia goes a long way. That friendly contributor might be a bot. That helpful PR might be reconnaissance. That simple typo fix might be setting up a backdoor.

Lessons Learned

Trust but verify: Even helpful PRs need scrutiny
Keep dependencies updated: Old packages are attractive targets
Use lockfiles properly: Pin versions and use npm ci
Secure your CI/CD: It's the crown jewel attackers want
Stay informed: Follow security researchers and vulnerability databases

The Silver Lining

While getting targeted by a supply chain attack was unsettling, it was also educational. It reminded me that security isn't just about writing secure code – it's about securing the entire development pipeline.

The npm ecosystem is incredibly powerful, but that power comes with responsibility. Every npm install is a vote of trust in hundreds of package maintainers. Every GitHub Action workflow is a potential attack vector.

But don't let this scare you away from open source. The community is what makes JavaScript development amazing. Just be smart about it. Audit your dependencies. Review your workflows. Trust but verify.

And maybe, just maybe, be a little suspicious when harshitcodez19 offers to help with your CI/CD pipeline.

Stay safe out there, fellow developers. The supply chain attackers are getting creative, but so are we.

References

Mastering Email Rate Limits — A Deep Dive into Resend API and Cloud Run Debugging

Dale Nguyen — Sun, 07 Sep 2025 14:11:09 +0000

How we solved persistent rate limiting issues and implemented robust batch email functionality for our AI-powered learning platform

The Challenge: When Emails Start Failing

Picture this: You've built a beautiful lesson scheduling system that sends personalized daily lessons to your users. Everything works perfectly in development, but in production, you start seeing mysterious email failures:

This was exactly the situation we faced with DailyMastery, our AI-powered learning platform. Despite having a solid architecture built with Nx monorepo, Fastify microservices, and deployed on Google Cloud Run, our email delivery system was hitting Resend's rate limits consistently.

Understanding the Problem

The Initial Architecture

Our system had a straightforward approach:

Lesson scheduler triggered by Cloud Scheduler (3x daily)
Individual API calls to Resend for each lesson email
No rate limiting protection
Basic error handling

// The problematic approach
for (const lesson of lessons) {
  const emailResult = await this.emailService.sendEmail({
    to: user.email,
    subject: lesson.title,
    html: lessonContent,
  })
  // Rate limits hit here when processing multiple users rapidly
}

The Root Cause

Resend enforces a 2 requests per second rate limit across all endpoints. When our scheduler processed multiple users with multiple lessons each, we quickly exceeded this limit, causing cascading failures.

The Investigation: Debugging Cloud Run Like a Pro

Step 1: Enhanced Logging Strategy

The first step was implementing comprehensive logging to understand exactly what was happening:

async sendEmail(options: EmailOptions): Promise<{ success: boolean; error?: string; messageId?: string }> {
  try {
    console.log('Attempting to send email via Resend:', {
      to: options.to,
      subject: options.subject,
      htmlLength: options.html?.length || 0
    });

    const result = await this.resend.emails.send(emailData);
    console.log('Resend API response:', result);

    // Critical: Check if Resend returned an error (they don't throw exceptions!)
    if (result.error) {
      console.error('Resend API returned error:', result.error);
      return {
        success: false,
        error: result.error.message || JSON.stringify(result.error),
      };
    }

    return {
      success: true,
      messageId: result.data?.id
    };
  } catch (error) {
    console.error('Failed to send email via Resend:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    };
  }
}

Step 2: Cloud Run Log Analysis Techniques

You can view logs in the Google Cloud console, but if you like the terminal approach, then here are the essential Cloud Run debugging commands we used:

# Real-time log monitoring during issues
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --limit=50 --format="value(timestamp,textPayload)" | head -20

# Filter for specific errors
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --limit=100 | grep -E "(rate_limit|429|Failed)"

# Check logs from specific time range
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler AND timestamp>=\"2025-09-03T16:00:00Z\"" \
  --limit=50

The Solution: Multi-Layer Rate Limiting Strategy

Layer 1: Proper Error Detection

The first critical insight: Resend doesn't throw exceptions for rate limits. They return error objects:

// Before: Missing rate limit detection
const result = await this.resend.emails.send(emailData)
return { success: true, messageId: result.data?.id } // Wrong!

// After: Comprehensive error checking
const result = await this.resend.emails.send(emailData)

if (result.error) {
  console.error('Resend API returned error:', result.error)
  return {
    success: false,
    error: result.error.message || JSON.stringify(result.error),
  }
}

if (!result.data) {
  return {
    success: false,
    error: 'No data returned from Resend API',
  }
}

return {
  success: true,
  messageId: result.data.id,
}

Layer 2: Intelligent Batch Email Implementation with Auto-Chunking

Resend offers a batch API that can send up to 100 emails in a single request. Here's our implementation with smart fallback and automatic chunking for larger batches:

async sendBatchLessonEmails(
  emails: BatchEmailOptions[]
): Promise<{ success: boolean; error?: string; messageIds?: string[]; sentCount?: number; failedCount?: number }> {
  try {
    if (emails.length === 0) {
      return { success: true, messageIds: [], sentCount: 0, failedCount: 0 };
    }

    console.log(`Sending batch of ${emails.length} lesson emails`);

    // Automatic chunking: Split into batches of 100 (Resend limit)
    const batchSize = 100;
    const batches: BatchEmailOptions[][] = [];
    for (let i = 0; i < emails.length; i += batchSize) {
      batches.push(emails.slice(i, i + batchSize));
    }

    let totalSent = 0;
    let totalFailed = 0;
    const allMessageIds: string[] = [];
    const errors: string[] = [];

    // Process each chunk sequentially with rate limiting
    for (let i = 0; i < batches.length; i++) {
      const batch = batches[i];
      console.log(`Sending batch ${i + 1}/${batches.length} with ${batch.length} emails`);

      const result = await this.emailService.sendBatchEmails(batch);

      if (result.success) {
        totalSent += batch.length;
        if (result.messageIds) {
          allMessageIds.push(...result.messageIds);
        }
        console.log(`✅ Batch ${i + 1} sent successfully (${batch.length} emails)`);
      } else {
        totalFailed += batch.length;
        errors.push(`Batch ${i + 1} failed: ${result.error || 'Unknown error'}`);
        console.error(`❌ Batch ${i + 1} failed: ${result.error}`);
      }

      // Add delay between batches to avoid rate limiting
      if (i < batches.length - 1) {
        console.log('⏳ Waiting 1 second between batches to avoid rate limiting...');
        await new Promise(resolve => setTimeout(resolve, 1000));
      }
    }

    const overallSuccess = totalFailed === 0;

    return {
      success: overallSuccess,
      messageIds: allMessageIds,
      sentCount: totalSent,
      failedCount: totalFailed,
      error: errors.length > 0 ? errors.join('; ') : undefined,
    };
  } catch (error) {
    console.error('Error sending batch lesson emails:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
      sentCount: 0,
      failedCount: emails.length,
    };
  }
}

Layer 3: Architectural Refactoring

We completely restructured our email sending flow:

// Old approach: Send emails immediately during processing
for (const user of users) {
  for (const lesson of lessons) {
    await sendEmail(user, lesson) // Rate limit hit here
  }
}

// New approach: Prepare first, then batch send
const allPreparedEmails: PreparedEmail[] = []

// Phase 1: Prepare all emails
for (const user of users) {
  for (const lesson of lessons) {
    const preparedEmail = await this.prepareLessonEmail(user, lesson)
    if (preparedEmail) {
      allPreparedEmails.push({ email: preparedEmail, user, lesson })
    }
  }
}

// Phase 2: Batch send with intelligent chunking and accurate tracking
if (allPreparedEmails.length > 0) {
  console.log(`🚀 Sending ${allPreparedEmails.length} emails in optimized batches`)

  const emailsToSend = allPreparedEmails.map((pe) => pe.email)

  // The EmailCoordinator handles chunking internally for 100+ email limits
  const batchResult = await this.emailCoordinator.sendBatchLessonEmails(emailsToSend)

  if (batchResult.success) {
    // Only mark lessons as sent based on actual successful send count
    const successfulEmails = allPreparedEmails.slice(0, batchResult.sentCount)
    await this.markLessonsAsSent(successfulEmails)
  }
}

Layer 4: Smart Retry Logic

For critical emails like admin reports, we implemented retry logic:

async sendSummaryReport(result: SchedulerResult): Promise<void> {
  // Add delay to avoid rate limiting after lesson emails
  console.log('⏳ Waiting 3 seconds to avoid rate limiting...');
  await new Promise(resolve => setTimeout(resolve, 3000));

  const emailResult = await this.emailService.sendEmail({
    to: this.reportingEmail,
    subject: `📊 Lesson Scheduler Report - ${result.timeSlot}`,
    html: htmlContent,
  });

  if (!emailResult.success) {
    // Retry logic for rate limits
    if (emailResult.error?.includes('rate_limit_exceeded') ||
        emailResult.error?.includes('Too many requests')) {
      console.log('⏳ Rate limited - waiting 10 seconds and retrying...');
      await new Promise(resolve => setTimeout(resolve, 10000));

      const retryResult = await this.emailService.sendEmail({
        to: this.reportingEmail,
        subject: `📊 Lesson Scheduler Report - ${result.timeSlot} (Retry)`,
        html: htmlContent,
      });

      if (retryResult.success) {
        console.log('✅ Summary report sent successfully on retry');
      }
    }
  }
}

Key Debugging Techniques for Cloud Run

1. Structured Logging

Use consistent emoji prefixes and structured data:

// Good logging practices
console.log('🚀 BATCH EMAIL MODE: Sending emails', { count: emails.length })
console.log('✅ Email sent successfully', { messageId, recipient })
console.log('❌ Email failed', { error: error.message, recipient })
console.log('⏳ Rate limiting delay', { delayMs: 600 })

2. Revision Tracking

Always verify your code is actually deployed:

# Check current revision
gcloud run services describe lesson-scheduler \
  --region=us-central1 \
  --format="value(status.latestReadyRevisionName)"

# List recent revisions with images
gcloud run revisions list --service=lesson-scheduler \
  --format="table(metadata.name,status.conditions[0].status,spec.containers[0].image)"

3. Real-time Monitoring

Set up log streaming during debugging:

# Stream logs in real-time
gcloud beta logging tail "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler"

# Filter for errors only
gcloud beta logging tail "resource.type=cloud_run_revision AND resource.labels.service_name=lesson-scheduler" \
  --filter="severity>=ERROR"

Results and Performance Impact

Before Optimization

❌ Cascading failures due to rate limits
❌ Poor user experience with missed lessons
❌ Manual intervention required daily

After Optimization

✅ 0% email failure rate
✅ Automatic handling of up to 100 emails per batch
✅ Zero manual intervention required

Performance Metrics

Final Test Results:
- totalUsers: 1
- emailsSent: 3
- emailsFailed: 0
- errorCount: 0
- processingTime: 7.048s
- batchEmailsUsed: true

Best Practices Learned

1. Email Service Design Patterns

interface EmailService {
  // Always return structured results
  sendEmail(options: EmailOptions): Promise<{
    success: boolean
    error?: string
    messageId?: string
  }>

  // Batch operations with fallback
  sendBatchEmails(emails: BatchEmailOptions[]): Promise<{
    success: boolean
    error?: string
    messageIds?: string[]
    sentCount?: number
    failedCount?: number
  }>
}

2. Rate Limiting Strategies

Batch First: Use batch APIs when available
Automatic Chunking: Split large batches into 100-email chunks automatically
Intelligent Delays: 600ms between individual requests (< 2 req/sec) and 1s between batch chunks
Accurate Tracking: Only mark operations as successful based on actual send counts
Exponential Backoff: Longer delays for retries
Circuit Breaker: Fail fast on repeated rate limits

Conclusion

Building a robust email delivery system requires understanding both your email provider's limitations and your cloud platform's deployment mechanics. Our journey from 30% failure rates to 0% taught us that:

Rate limiting is real - Plan for it from day one
Batch APIs are game-changers - Use them when available
Docker caching can bite you - Structure your builds carefully
Comprehensive logging saves time - Invest in good observability
Fallback strategies are essential - Always have a Plan B

The combination of Resend's batch API, intelligent fallback logic, proper rate limiting, and robust Cloud Run debugging techniques transformed our email delivery from a daily headache into a reliable, scalable system.

Remember: In production systems, it's not just about making it work—it's about making it work reliably, even when things go wrong.

This blog post is based on our real-world experience building DailyMastery, an AI-powered learning platform. The techniques described here are battle-tested in production and have been processing thousands of lesson emails daily without issues.

SupaWP Storage Filter Hooks - Seamless Supabase Storage Integration for WordPress

Dale Nguyen — Sat, 06 Sep 2025 04:05:16 +0000

Building modern WordPress applications often requires robust file storage solutions that scale beyond traditional media library limitations. Today, we're excited to introduce SupaWP Storage Filter Hooks – a powerful new feature that brings seamless Supabase Storage integration directly to your WordPress plugins and themes.

What Are SupaWP Storage Filter Hooks?

SupaWP Storage Filter Hooks are a set of WordPress filter hooks that provide a standardized, developer-friendly way to integrate Supabase Storage into any WordPress application. Instead of writing custom storage code for each project, you can now leverage these hooks to upload, delete, and manage files in Supabase Storage with just a few lines of code.

Prerequisites

Before diving into the implementation, ensure you have:

WordPress site with SupaWP plugin v1.3.4 or higher installed and configured
Supabase project with Storage enabled
Basic knowledge of WordPress filters and PHP
Supabase Storage bucket configured

The Three Essential Hooks

1. `supawp_upload_image_to_supabase`

Upload images directly to Supabase Storage with automatic validation and security:

// Upload a user profile image
$image_url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-images');

if (!empty($image_url)) {
    // Success! Save the URL to your database
    update_user_meta($user_id, 'profile_image_url', $image_url);
    return array('success' => true, 'url' => $image_url);
}

2. `supawp_delete_image_from_supabase`

Remove files from Supabase Storage with proper cleanup:

// Delete a user's profile image
$success = apply_filters('supawp_delete_image_from_supabase', $image_url, 'user-images');

if ($success) {
    // File deleted successfully
    delete_user_meta($user_id, 'profile_image_url');
}

3. `supawp_get_storage_config`

Access Supabase Storage configuration and verify setup:

// Check if storage is properly configured
$config = apply_filters('supawp_get_storage_config');

if (!empty($config)) {
    echo "Storage URL: " . $config['url'];
    echo "Authentication: Configured ✓";
}

Simple File Upload Implementation

Here's a basic implementation using the SupaWP Storage Filter Hooks:

<?php
/**
 * Simple File Upload with SupaWP Storage
 */
class Simple_SupaWP_Upload {

    public static function init() {
        add_shortcode('simple_file_upload', array('Simple_SupaWP_Upload', 'upload_shortcode'));
        add_action('wp_ajax_upload_to_supabase', array('Simple_SupaWP_Upload', 'handle_upload'));
    }

    public static function upload_shortcode() {
        $current_user = wp_get_current_user();
        if (!$current_user->ID) {
            return '<p>Please log in to upload files.</p>';
        }

        ob_start();
        ?>
        <form id="upload-form" enctype="multipart/form-data">
            <input type="file" name="user_file" accept=".jpg,.jpeg,.png,.webp" required>
            <button type="submit">Upload File</button>
        </form>

        <div id="upload-result"></div>

        <script>
            document.getElementById('upload-form').addEventListener('submit', function(e) {
                e.preventDefault();

                const formData = new FormData(this);
                formData.append('action', 'upload_to_supabase');
                formData.append('nonce', '<?php echo wp_create_nonce('upload_nonce'); ?>');

                fetch('<?php echo admin_url('admin-ajax.php'); ?>', {
                    method: 'POST',
                    body: formData
                })
                .then(response => response.json())
                .then(data => {
                    document.getElementById('upload-result').innerHTML =
                        data.success ? 'Upload successful!' : 'Upload failed: ' + data.data;
                });
            });
        </script>
        <?php
        return ob_get_clean();
    }

    public static function handle_upload() {
        check_ajax_referer('upload_nonce', 'nonce');

        if (!isset($_FILES['user_file'])) {
            wp_send_json_error('No file provided');
        }

        $file = $_FILES['user_file'];
        $user_id = get_current_user_id();

        // Generate file path
        $extension = pathinfo($file['name'], PATHINFO_EXTENSION);
        $fileName = "users/{$user_id}/" . time() . ".{$extension}";

        // Upload using SupaWP hook
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-content');

        if ($url) {
            wp_send_json_success(array('url' => $url));
        } else {
            wp_send_json_error('Upload failed');
        }
    }
}

add_action('supawp_init', array('Simple_SupaWP_Upload', 'init'));

Advanced Implementation Examples

E-commerce Product Gallery

function upload_product_images($product_id, $files) {
    $uploaded_urls = array();

    foreach ($files as $file) {
        $fileName = "products/{$product_id}/" . time() . ".jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'products');

        if ($url) {
            $uploaded_urls[] = $url;
        }
    }

    update_post_meta($product_id, '_gallery_urls', $uploaded_urls);
    return $uploaded_urls;
}

User Document Management

function upload_user_document($user_id, $file) {
    if (!current_user_can('upload_files')) {
        return false;
    }

    $fileName = "documents/{$user_id}/" . time() . ".pdf";
    $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'documents');

    if ($url) {
        update_user_meta($user_id, 'document_url', $url);
        return $url;
    }

    return false;
}

Integration with Popular Plugins

Contact Form 7 Integration

function handle_contact_form_upload($contact_form) {
    $submission = WPCF7_Submission::get_instance();
    $files = $submission->uploaded_files();

    if (isset($files['resume'])) {
        $fileName = "resumes/" . time() . "_resume.pdf";
        $url = apply_filters('supawp_upload_image_to_supabase', $files['resume'], $fileName, 'resumes');

        if ($url) {
            update_option('latest_resume', $url);
        }
    }
}
add_action('wpcf7_mail_sent', 'handle_contact_form_upload');

WooCommerce Integration

function sync_product_to_supabase($product_id) {
    $product = wc_get_product($product_id);
    $image_id = $product->get_image_id();

    if ($image_id) {
        $image_path = get_attached_file($image_id);
        $file = array(
            'tmp_name' => $image_path,
            'name' => basename($image_path),
            'size' => filesize($image_path)
        );

        $fileName = "products/{$product_id}.jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'products');

        if ($url) {
            update_post_meta($product_id, '_supabase_image', $url);
        }
    }
}
add_action('woocommerce_process_product_meta', 'sync_product_to_supabase');

Security Best Practices

Row Level Security (RLS) Policies

Set up proper RLS policies in your Supabase dashboard:

-- Users can only upload to their own folders
CREATE POLICY "Users upload own files" ON storage.objects
FOR INSERT WITH CHECK (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

-- Users can only view their own files
CREATE POLICY "Users view own files" ON storage.objects
FOR SELECT USING (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

-- Users can only delete their own files
CREATE POLICY "Users delete own files" ON storage.objects
FOR DELETE USING (
    bucket_id = 'user-content' AND
    (storage.foldername(name))[1] = auth.uid()::text
);

Simple File Validation

function validate_file($file) {
    // Check file size (5MB limit)
    if ($file['size'] > 5242880) {
        return false;
    }

    // Check file type
    $allowed_types = array('jpg', 'png', 'pdf');
    $extension = pathinfo($file['name'], PATHINFO_EXTENSION);

    return in_array($extension, $allowed_types);
}

Performance Optimization

Batch Upload

function batch_upload($files, $user_id) {
    $results = array();

    foreach ($files as $file) {
        $fileName = "users/{$user_id}/" . time() . ".jpg";
        $url = apply_filters('supawp_upload_image_to_supabase', $file, $fileName, 'user-content');

        $results[] = array(
            'name' => $file['name'],
            'url' => $url,
            'success' => !empty($url)
        );
    }

    return $results;
}

Using Your File Upload System

Once your code is in place:

Add the shortcode to any page or post: [simple_file_upload]
Ensure users are logged in for security
Configure your Supabase Storage with appropriate buckets

Example usage:

[simple_file_upload]

Common Supabase Storage Query Filters

When working with uploaded files, you can query them using various filters:

// Get user's files from database
$user_files = apply_filters('supawp_get_data_from_supabase', 'files', array(
    'user_id' => 'eq.' . $user_id,
    'order' => 'created_at.desc'
));

// Filter by file size
$large_files = apply_filters('supawp_get_data_from_supabase', 'files', array(
    'file_size' => 'gt.1000000'
));

Troubleshooting Common Issues

Troubleshooting

// Check if storage is configured
$config = apply_filters('supawp_get_storage_config');
if (empty($config)) {
    echo "Storage not configured";
}

Common Issues

Storage not configured - Check SupaWP settings
Upload fails - Verify file size and type limits
Permission denied - Check Supabase RLS policies
Files not showing - Ensure bucket is public

Conclusion

SupaWP Storage Filter Hooks revolutionize file management in WordPress by providing seamless integration with Supabase's powerful storage infrastructure. With enterprise-grade security, global CDN distribution, and a developer-friendly API, you can build sophisticated file management systems with minimal code.

Key benefits of this integration:

Zero Configuration Complexity - SupaWP handles authentication and API communication
Enterprise Security - Automatic RLS integration and secure file handling
Global Performance - Leverage Supabase's worldwide CDN network
WordPress Native - Uses familiar WordPress filter patterns
Scalable Architecture - No server storage limitations

Whether you're building a simple profile system, complex document management, or e-commerce product galleries, SupaWP Storage Filter Hooks provide the foundation for modern, scalable WordPress applications.

Resources

Ready to transform your WordPress file management? Download SupaWP v1.3.4+ and start building with Supabase Storage today!

Learn with Daily Mastery - From AI Generation to Email Delivery

Dale Nguyen — Thu, 04 Sep 2025 04:00:42 +0000

One of the biggest challenges in online education isn't creating content—it's delivering the right content to the right person at the right time. When building DailyMastery, we needed to solve a complex scheduling problem: how do you deliver personalized, AI-generated lessons to users across different time zones, preferences, and learning schedules?

Our solution is a high-performance lesson scheduling system that processes thousands of users daily, generates personalized content on-the-fly, and delivers beautiful email lessons at precisely the right moment. Here's how we built it.

The Challenge: Personalization at Scale

Traditional learning platforms send the same content to everyone. But true personalization requires:

Individual content generation: Each lesson tailored to specific goals and progress
Time-based delivery: Respecting user preferences for morning, afternoon, or evening learning
Scalable processing: Handling growing user bases without performance degradation
Reliability: Ensuring lessons are delivered consistently, even when individual components fail

Architecture Overview: From User Preferences to Inbox

Our lesson scheduling system consists of several coordinated services:

1. User Selection Engine

The system starts by identifying which users should receive lessons for each time slot:

Selection Criteria:

Users must have preferences.studyTime matching the time slot ('morning', 'afternoon', 'evening')
Users must have preferences.notifications.dailyReminders enabled
Users must have active study plans with lessons scheduled for today

Time Slots:

06:00 UTC (Morning): Targets users who prefer early learning
12:00 UTC (Afternoon): Catches lunch-break learners
18:00 UTC (Evening): Reaches after-work studiers

2. AI Content Generation Pipeline

Once we identify users, each lesson goes through our AI enhancement process:

Process Flow:

Lesson Retrieval: Get scheduled lesson from database with original template content
AI Enhancement: Use Google Cloud Vertex AI with Gemini to expand and personalize the content
Quality Validation: Ensure AI-generated content meets quality standards
Fallback Strategy: Use original template if AI generation fails

Content Personalization:
The AI considers user context including:

Learning objectives and goals
Current progress and difficulty level
Preferred learning style and time commitment
Previous lesson feedback and engagement

3. Batch Processing for Scale

To handle thousands of users efficiently, we use sophisticated batch processing:

Concurrency Control:

const pLimit = (await import('p-limit')).default
const limit = pLimit(10) // Process up to 10 users concurrently

const promises = userGroups.map((userGroup) => limit(() => this.processUserGroup(userGroup)))

await Promise.allSettled(promises)

Error Resilience:
Individual user failures don't stop the entire batch. Each user's processing is isolated, logged, and reported separately.

The Lesson Processor: Heart of the System

Our LessonProcessorService handles the complex task of managing lesson content:

Active Plan Discovery

The system performs comprehensive scans to find all active study plans:

async getActivePlans(): Promise<UserPlanGroup[]> {
  // Scan all users with active plans
  // Find today's scheduled lessons
  // Group by user for efficient processing
}

AI Content Generation

Each lesson is enhanced with AI-generated content:

Quality Metrics:

Content length and depth analysis
Learning objective alignment
Engagement potential scoring
Readability assessment

Performance Tracking:

AI generation time per lesson
Success/failure rates
Content quality improvement over time
User engagement correlation

Database Integration

Seamless integration with Firestore for lesson management:

Atomic updates for lesson content
Timestamp tracking for delivery status
Progress tracking for user analytics
Batch operations for efficiency

Email Delivery: The Final Mile

Our EmailCoordinatorService handles the critical task of email delivery:

Personalized Templates

Each email is personalized based on:

Time-based greetings: 🌅 "Good morning" vs ☀️ "Good afternoon" vs 🌙 "Good evening"
Study plan context: Extracted plan names and goals
Progress indicators: Current lesson number and completion status
Engagement elements: Interactive exercises and progress tracking

Responsive Design

Our TemplateEngineService creates mobile-friendly emails with:

Maximum width of 600px for optimal display
Modern gradient designs and professional styling with CSS animations
Clear call-to-action buttons for lesson engagement
Progress visualization and success metrics
Time-based personalized greetings and content adaptation
Professional email templates with comprehensive fallback support

Delivery Reliability

Email delivery includes comprehensive error handling:

Detailed error logging for failed deliveries
Retry mechanisms for transient failures
Admin alerting for critical delivery issues
Success rate monitoring and reporting
Batch email API with intelligent fallback to individual sends
Rate limiting protection (2 requests per second compliance)

Real-Time Processing Flow

Here's what happens when our scheduler processes the morning time slot:

1. Trigger Processing (06:00 UTC)

POST /schedule/06:00

2. User Discovery

Query database for morning-preference users
Filter for active daily reminders
Identify today's scheduled lessons

3. Batch Processing

Group users for efficient processing
Apply concurrency limits (10 concurrent users)
Process each user's lessons independently

4. Content Generation

For each user:

Retrieve scheduled lessons from database
Generate AI-enhanced content
Update lesson records with new content
Mark lessons as processed

5. Email Delivery

Render personalized HTML templates
Send via Resend email service
Track delivery status and metrics
Update lesson records with sent timestamps

6. Reporting and Monitoring

Generate processing summary
Send admin reports via email
Log performance metrics
Alert on critical errors

Performance Metrics and Monitoring

Our system tracks comprehensive metrics:

Processing Performance

Total processing time per time slot
Average time per user
Concurrency efficiency metrics
Database operation latency

Content Quality

AI generation success rates (target: >95%)
Content length and complexity metrics
User engagement correlation with AI content
Fallback usage rates

Email Delivery

Email send success rates (target: >99%)
Template rendering performance
User engagement rates (opens, clicks, completions)
Bounce and complaint rates

Future Enhancements

We're continuously improving the scheduling system:

Advanced Personalization

Learning pattern analysis: Adapt timing based on user engagement patterns
Content difficulty adjustment: Dynamic complexity scaling based on progress
Multi-modal delivery: Support for SMS, push notifications, and in-app delivery

Performance Optimization

Predictive scaling: Auto-scaling based on user growth patterns
Content pre-generation: Cache frequently used AI-generated content
Global distribution: Multi-region deployment for reduced latency

Analytics and Insights

Learning effectiveness metrics: Correlation between delivery timing and retention
Content performance analysis: A/B testing for AI-generated vs template content
User journey optimization: Personalized scheduling based on individual success patterns

Lessons Learned

Building a personalized lesson scheduling system taught us:

Technical Insights

Batch processing with concurrency limits provides the best balance of speed and reliability
Comprehensive error handling at every level is essential for user trust
AI content generation requires robust fallback strategies for reliability
Email delivery is more complex than it appears - template rendering, personalization, and deliverability all matter

Product Insights

Time-based personalization significantly improves engagement compared to generic scheduling
AI-enhanced content shows measurably higher completion rates than template-based lessons
Processing transparency builds user confidence - users appreciate knowing when their lessons are being prepared
Reliable delivery is table stakes - users expect lessons to arrive consistently

Getting Started

If you're building your own personalized delivery system, consider:

Start with reliable basics: Get consistent delivery working before adding AI enhancement
Design for failure: Assume every external service will fail and plan accordingly
Monitor everything: Comprehensive logging and metrics are essential for debugging and optimization
Test with real load: Batch processing behaves differently at scale

Our lesson scheduling system demonstrates that personalized, AI-powered education delivery is not only possible but can be built reliably and efficiently with the right architecture and attention to detail.

Fixing Next.js Authentication Redirects - Preserving Deep Links After Login

Dale Nguyen — Fri, 29 Aug 2025 14:34:06 +0000

The Problem

In our learning platform DailyMastery, we send personalized lesson emails to users with direct links to specific lessons, like:

https://dailymastery.io/dashboard/lessons/sample-lesson-detail

However, we discovered a frustrating user experience issue: when users clicked these lesson links from their emails, they would be redirected to login (which is correct for unauthenticated users), but after successful authentication, instead of landing on the specific lesson page, they would end up on the generic dashboard.

This broke the seamless experience we wanted to provide - users had to manually navigate to find their intended lesson after logging in.

Understanding the Authentication Flow

Let's break down what was happening:

The Original (Broken) Flow:

User clicks lesson link: https://dailymastery.io/dashboard/lessons/sample-lesson-detail
Middleware intercepts: Detects no authentication token
Redirect to login: https://dailymastery.io/login (❌ Original URL lost!)
User authenticates: Successfully logs in with Google
Post-login redirect: Goes to default /dashboard (❌ Not the intended lesson)

The Root Cause

Our Next.js middleware was correctly protecting routes but wasn't preserving the original destination URL when redirecting unauthenticated users to the login page.

Here's the problematic middleware code:

// ❌ BEFORE: Lost the original URL
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    const token = request.cookies.get('firebase-token')?.value

    if (!token) {
      // This loses the original URL!
      return NextResponse.redirect(new URL('/login', request.url))
    }
  }

  return NextResponse.next()
}

The Solution: Preserving Deep Links

The fix required two components working together:

1. Enhanced Middleware (Capturing the Original URL)

We modified the middleware to capture the full original URL and pass it as a query parameter:

// ✅ AFTER: Preserves the original URL
export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/dashboard')) {
    const cookieToken = request.cookies.get('firebase-token')?.value
    const headerToken = request.headers.get('authorization')?.replace('Bearer ', '')
    const token = cookieToken || headerToken

    if (!token) {
      // 🎯 Key fix: Preserve original URL with query params
      const loginUrl = new URL('/login', request.url)
      loginUrl.searchParams.set('redirect', request.nextUrl.pathname + request.nextUrl.search)
      return NextResponse.redirect(loginUrl)
    }
  }

  return NextResponse.next()
}

Key improvements:

request.nextUrl.pathname captures the path (/dashboard/lessons/sample-lesson-detail)
request.nextUrl.search captures any query parameters
Combined as redirect parameter in the login URL

2. Smart Login Page (Reading and Using the Redirect)

Our login page was already set up to handle redirects, but let's look at the key parts:

// login/page.tsx
function LoginForm() {
  const router = useRouter()
  const searchParams = useSearchParams()

  useEffect(() => {
    if (!loading && user) {
      // 🎯 Check for redirect parameter first, fallback to dashboard
      const redirectUrl = searchParams.get('redirect')
      router.push(redirectUrl || '/dashboard')
    }
  }, [user, loading, router, searchParams])

  const signInWithGoogle = async () => {
    try {
      const result = await signInWithPopup(auth, provider)
      const idToken = await result.user.getIdToken()

      // Store auth token
      document.cookie = `firebase-token=${idToken}; path=/; max-age=86400; secure; samesite=strict`

      // 🎯 Redirect to original destination after login
      const redirectUrl = searchParams.get('redirect')
      router.push(redirectUrl || '/dashboard')
    } catch (error) {
      setError(error.message)
    }
  }
}

The Fixed Flow

Now the authentication flow works perfectly:

The New (Working) Flow:

User clicks lesson link: https://dailymastery.io/dashboard/lessons/sample-lesson-detail
Middleware intercepts: Detects no authentication token
Smart redirect: https://dailymastery.io/login?redirect=/dashboard/lessons/sample-lesson-detail (✅ URL preserved!)
User authenticates: Successfully logs in with Google
Post-login redirect: Goes to the original lesson URL (✅ Perfect user experience!)

Testing the Fix

To test this, you can:

Create a protected route: Any URL under /dashboard/*
Visit while logged out: The middleware will redirect you
Check the URL: Should be /login?redirect=/dashboard/your-original-path
Complete authentication: Should redirect back to your original destination

Key Takeaways

1. Middleware Should Preserve Context

When redirecting users for authentication, always preserve where they were trying to go:

// Bad: Loses context
return NextResponse.redirect(new URL('/login', request.url))

// Good: Preserves user intent
const loginUrl = new URL('/login', request.url)
loginUrl.searchParams.set('redirect', request.nextUrl.pathname + request.nextUrl.search)
return NextResponse.redirect(loginUrl)

2. Login Pages Should Check for Redirects

Your authentication success handler should always check for intended destinations:

// Bad: Always goes to same place
router.push('/dashboard')

// Good: Respects user's original intent
const redirectUrl = searchParams.get('redirect')
router.push(redirectUrl || '/dashboard')

3. Handle Edge Cases

Consider various scenarios:

Query parameters in original URLs
Relative vs absolute URLs
Security validation of redirect URLs (prevent open redirects)
Fallback behaviors when redirects fail

Security Considerations

When implementing redirect preservation, be mindful of open redirect vulnerabilities. In our case, we're safe because:

We only redirect within our own domain
The middleware controls what URLs get set as redirects
We validate that redirects start with /dashboard (our protected routes)

For additional security, you could add validation:

const validateRedirectUrl = (url: string): boolean => {
  // Only allow internal redirects to specific paths
  return url.startsWith('/dashboard') || url.startsWith('/profile')
}

// In login handler:
const redirectUrl = searchParams.get('redirect')
const safeRedirectUrl = redirectUrl && validateRedirectUrl(redirectUrl) ? redirectUrl : '/dashboard'
router.push(safeRedirectUrl)

Conclusion

This seemingly small fix dramatically improved our user experience. Users clicking lesson links in emails now seamlessly land on their intended lessons after authentication, rather than getting lost on a generic dashboard.

The solution demonstrates how proper state preservation in authentication flows is crucial for maintaining user intent and creating smooth, professional web applications.

Technologies used: Next.js 15, TypeScript, Firebase Auth, Next.js Middleware

Building a Next.js Landing Page with Google Sheets Integration and Google Cloud Run Deployment

Dale Nguyen — Wed, 20 Aug 2025 15:55:31 +0000

Building a modern landing page that captures potential user emails is essential for any startup or product launch. In this comprehensive guide, I'll walk you through creating a Next.js 15 landing page that collects emails in Google Sheets and deploys seamlessly to Google Cloud Run.

What We'll Build

By the end of this tutorial, you'll have:

A responsive Next.js 15 landing page with TypeScript
Email signup form with validation and loading states
Google Sheets integration to store collected emails
Dockerized application ready for production
Automated deployment to Google Cloud Run
Cost-effective, scalable infrastructure

Prerequisites

Node.js 20+ and pnpm installed
Google Cloud Platform account
Basic knowledge of React and TypeScript
Docker installed (for local testing)

Project Setup

1. Initialize the Next.js Project

# Create Next.js project with TypeScript
npx create-next-app@latest landing --typescript --tailwind --app

cd landing

2. Install Dependencies

# Install Google APIs client
pnpm add googleapis

# Install development dependencies
pnpm add -D @types/node

Building the Email Signup Component

1. Create the Email Signup Component

Create src/app/components/email-signup/email-signup.tsx:

'use client'

import { useState, useEffect } from 'react'

const EmailSignup = () => {
  const [email, setEmail] = useState('')
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
  const [message, setMessage] = useState('')

  const validateEmail = (email: string): boolean => {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    return emailRegex.test(email)
  }

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault()

    if (!validateEmail(email)) {
      setStatus('error')
      setMessage('Please enter a valid email address')
      return
    }

    setStatus('loading')
    setMessage('')

    try {
      const response = await fetch('/api/v1/email-signup', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ email }),
      })

      if (response.ok) {
        setStatus('success')
        setMessage('Thank you for subscribing!')
        setEmail('')
      } else {
        throw new Error('Subscription failed')
      }
    } catch (error) {
      setStatus('error')
      setMessage('Something went wrong. Please try again.')
    }
  }

  return (
    <section className="relative py-24 bg-gradient-to-br from-blue-600 via-purple-600 to-indigo-700">
      <div className="container relative z-10">
        <div className="text-center max-w-2xl mx-auto">
          <h2 className="mb-6 text-3xl md:text-4xl font-bold text-white">Stay updated with the latest</h2>
          <p className="mb-10 text-xl text-blue-100">Get the latest updates delivered to your inbox.</p>

          <form onSubmit={handleSubmit} className="flex flex-col sm:flex-row gap-4 max-w-md mx-auto mb-8">
            <input
              type="email"
              required
              className="flex-1 px-6 py-4 text-lg bg-white/10 backdrop-blur-sm border border-white/20 rounded-2xl text-white placeholder:text-blue-200 focus:outline-none focus:ring-2 focus:ring-white/50"
              placeholder="Enter your email"
              value={email}
              onChange={(e) => setEmail(e.target.value)}
              disabled={status === 'loading'}
            />
            <button
              type="submit"
              disabled={status === 'loading'}
              className="px-8 py-4 bg-white text-blue-600 rounded-2xl font-semibold hover:bg-blue-50 disabled:opacity-50 transition-all"
            >
              {status === 'loading' ? 'Subscribing...' : 'Subscribe'}
            </button>
          </form>

          {message && (
            <p className={`mb-6 text-lg font-medium ${status === 'success' ? 'text-green-400' : 'text-red-400'}`}>
              {message}
            </p>
          )}
        </div>
      </div>
    </section>
  )
}

export default EmailSignup

Google Sheets Integration

1. Create Google Sheets Service

Create src/lib/google-sheets.ts:

import { google } from 'googleapis'

export interface EmailSignupData {
  email: string
  timestamp: string
  source?: string
}

class GoogleSheetsService {
  private auth
  private sheets

  constructor() {
    // Use Application Default Credentials (Cloud Run provides this automatically)
    this.auth = new google.auth.GoogleAuth({
      scopes: ['https://www.googleapis.com/auth/spreadsheets'],
    })

    this.sheets = google.sheets({ version: 'v4', auth: this.auth })
  }

  async saveEmailSignup(data: EmailSignupData): Promise<void> {
    const spreadsheetId = process.env.GOOGLE_SHEETS_ID

    if (!spreadsheetId) {
      throw new Error('Google Sheets ID not configured')
    }

    const values = [[data.email, data.timestamp, data.source || 'landing-page']]

    try {
      await this.sheets.spreadsheets.values.append({
        spreadsheetId,
        range: 'Sheet1!A:C',
        valueInputOption: 'USER_ENTERED',
        requestBody: {
          values,
        },
      })
    } catch (error) {
      console.error('Error saving to Google Sheets:', error)
      throw error
    }
  }

  async setupSheet(): Promise<void> {
    const spreadsheetId = process.env.GOOGLE_SHEETS_ID

    if (!spreadsheetId) {
      throw new Error('Google Sheets ID not configured')
    }

    try {
      // Add headers if sheet is empty
      const response = await this.sheets.spreadsheets.values.get({
        spreadsheetId,
        range: 'Sheet1!A1:C1',
      })

      if (!response.data.values || response.data.values.length === 0) {
        await this.sheets.spreadsheets.values.update({
          spreadsheetId,
          range: 'Sheet1!A1:C1',
          valueInputOption: 'USER_ENTERED',
          requestBody: {
            values: [['Email', 'Timestamp', 'Source']],
          },
        })
      }
    } catch (error) {
      console.error('Error setting up Google Sheets:', error)
      throw error
    }
  }
}

export const googleSheetsService = new GoogleSheetsService()

2. Create API Route

Create src/app/api/v1/email-signup/route.ts:

import { NextRequest, NextResponse } from 'next/server'
import { googleSheetsService } from '../../../../lib/google-sheets'

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()
    const { email } = body

    // Validate email
    if (!email || typeof email !== 'string') {
      return NextResponse.json({ error: 'Email is required' }, { status: 400 })
    }

    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
    if (!emailRegex.test(email)) {
      return NextResponse.json({ error: 'Invalid email format' }, { status: 400 })
    }

    // Save to Google Sheets
    try {
      await googleSheetsService.saveEmailSignup({
        email,
        timestamp: new Date().toISOString(),
        source: 'landing-waitlist',
      })
      console.log('Email saved to Google Sheets:', email)
    } catch (sheetsError) {
      console.error('Failed to save to Google Sheets:', sheetsError)
      // Continue with success response even if sheets fails
    }

    return NextResponse.json({ message: 'Email subscribed successfully' }, { status: 200 })
  } catch (error) {
    console.error('Email signup error:', error)
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
  }
}

Dockerization for Production

1. Configure Next.js for Standalone Output

Update next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Enable standalone output for Docker
  output: 'standalone',

  // Enable compression in production
  compress: true,

  // Optimize for production
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },
}

module.exports = nextConfig

2. Create Dockerfile

Create Dockerfile:

# Minimal production image for built Next.js app
FROM node:20-alpine AS production

WORKDIR /app

# Copy the standalone build (includes dependencies, server, and app)
COPY .next/standalone/ ./

# Copy static files
COPY public ./public
COPY .next/static ./.next/static

# Set environment
ENV NODE_ENV=production
ENV PORT=3000

# Create a non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001

# Change ownership of the application files
RUN chown -R nextjs:nodejs /app

USER nextjs

# Expose port
EXPOSE 3000

# Start the standalone server
CMD ["node", "server.js"]

3. Build and Test Locally

# Build the Next.js application
npm run build

# Build Docker image
docker build -t landing-page .

# Test locally
docker run -p 3000:3000 -e GOOGLE_SHEETS_ID=your-sheet-id landing-page

Google Cloud Setup

1. Create Google Cloud Resources

# Login to Google Cloud
gcloud auth login

# Set your project
gcloud config set project YOUR-PROJECT-ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable sheets.googleapis.com

# Create a service account
gcloud iam service-accounts create workwrite-sheets \
    --display-name="WorkWrite Sheets Service Account"

# Grant Google Sheets access
gcloud projects add-iam-policy-binding YOUR-PROJECT-ID \
    --member="serviceAccount:workwrite-sheets@YOUR-PROJECT-ID.iam.gserviceaccount.com" \
    --role="roles/editor"

2. Create Google Sheet

Go to Google Sheets
Create a new spreadsheet
Copy the spreadsheet ID from the URL
Share the sheet with your service account email

3. Build and Push to Google Cloud Registry

# Configure Docker to use gcloud
gcloud auth configure-docker us-central1-docker.pkg.dev

# Create Artifact Registry repository
gcloud artifacts repositories create workwrite-repo \
    --repository-format=docker \
    --location=us-central1

# Build and tag image
docker build --platform linux/amd64 -t us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing .

# Push to registry
docker push us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing

Deployment to Google Cloud Run

1. Deploy with Cloud Run

gcloud run deploy workwrite-landing \
  --image us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing \
  --region us-central1 \
  --platform managed \
  --allow-unauthenticated \
  --service-account workwrite-sheets@YOUR-PROJECT-ID.iam.gserviceaccount.com \
  --set-env-vars GOOGLE_SHEETS_ID=YOUR-SHEET-ID \
  --port 3000 \
  --memory 1Gi \
  --cpu 1 \
  --max-instances 10 \
  --timeout 300

2. Automated Deployment with Scripts

Create deployment scripts in your package.json:

{
  "scripts": {
    "docker:build": "docker build --platform linux/amd64 -t us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing .",
    "docker:push": "docker push us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing",
    "deploy": "npm run build && npm run docker:build && npm run docker:push && gcloud run deploy workwrite-landing --image us-central1-docker.pkg.dev/YOUR-PROJECT-ID/workwrite-repo/workwrite-landing --region us-central1"
  }
}

Advanced Features

1. Environment Variables

Create .env.local for development:

GOOGLE_SHEETS_ID=your-development-sheet-id

2. Error Handling and Monitoring

Add comprehensive error handling in your API routes:

export async function POST(request: NextRequest) {
  try {
    // ... your existing code
  } catch (error) {
    // Log error for monitoring
    console.error('Email signup error:', {
      error: error.message,
      timestamp: new Date().toISOString(),
      userAgent: request.headers.get('user-agent'),
    })

    return NextResponse.json({ error: 'Internal server error' }, { status: 500 })
  }
}

3. Rate Limiting

Implement rate limiting to prevent abuse:

import { NextRequest, NextResponse } from 'next/server'

const rateLimitMap = new Map()

export async function POST(request: NextRequest) {
  const ip = request.ip || 'unknown'
  const limit = 5 // 5 requests per minute
  const windowMs = 60 * 1000 // 1 minute

  if (!rateLimitMap.has(ip)) {
    rateLimitMap.set(ip, {
      count: 0,
      lastReset: Date.now(),
    })
  }

  const user = rateLimitMap.get(ip)

  if (Date.now() - user.lastReset > windowMs) {
    user.count = 0
    user.lastReset = Date.now()
  }

  if (user.count >= limit) {
    return NextResponse.json({ error: 'Too many requests' }, { status: 429 })
  }

  user.count += 1

  // ... rest of your code
}

Performance Optimizations

1. Image Optimization

Add optimized images with Next.js Image component:

import Image from 'next/image'

const Hero = () => (
  <section className="hero">
    <Image src="/hero-image.jpg" alt="Hero" width={800} height={600} priority className="rounded-lg" />
  </section>
)

2. SEO Optimization

Update src/app/layout.tsx with comprehensive metadata:

import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'WorkWrite - AI-Powered Writing Platform',
  description: 'Transform your writing workflow with AI.',
  keywords: ['writing', 'AI', 'productivity'],
  openGraph: {
    type: 'website',
    locale: 'en_US',
    url: 'https://workwrite.com',
    title: 'WorkWrite - AI-Powered Writing Platform',
    description: 'Transform your writing workflow with AI.',
    images: [
      {
        url: '/og-image.jpg',
        width: 1200,
        height: 630,
        alt: 'WorkWrite',
      },
    ],
  },
}

Cost Optimization

1. Cloud Run Pricing

Google Cloud Run pricing is based on:

CPU and Memory: Pay per 100ms of usage
Requests: $0.40 per million requests
Networking: Egress charges apply

For a typical landing page:

Low traffic (1K visitors/month): ~$1-2/month
Medium traffic (10K visitors/month): ~$5-10/month
High traffic (100K visitors/month): ~$20-40/month

2. Optimization Tips

// next.config.js
const nextConfig = {
  // Compress responses
  compress: true,

  // Optimize bundle
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },

  // Cache static assets
  headers: async () => [
    {
      source: '/(.*)\\.(js|css|png|jpg|jpeg|gif|ico|svg)',
      headers: [
        {
          key: 'Cache-Control',
          value: 'public, max-age=31536000, immutable',
        },
      ],
    },
  ],
}

Monitoring and Analytics

1. Google Analytics

Add Google Analytics to track conversions:

// src/app/layout.tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID" strategy="afterInteractive" />
        <Script id="google-analytics" strategy="afterInteractive">
          {`
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());
            gtag('config', 'GA_MEASUREMENT_ID');
          `}
        </Script>
      </head>
      <body>{children}</body>
    </html>
  )
}

2. Conversion Tracking

Track email signups:

// Declare gtag as a global function for TypeScript
declare global {
  interface Window {
    gtag: (
      command: 'config' | 'event' | 'js',
      targetId: string | Date,
      config?: {
        event_category?: string
        event_label?: string
        value?: number
        [key: string]: any
      },
    ) => void
  }
}

// In your email signup component
const trackConversion = () => {
  if (typeof gtag !== 'undefined') {
    gtag('event', 'sign_up', {
      event_category: 'engagement',
      event_label: 'email_signup',
    })
  }
}

const handleSubmit = async (e) => {
  // ... existing code

  if (response.ok) {
    trackConversion()
    // ... rest of success handling
  }
}

Security Best Practices

1. Environment Variables

Never commit sensitive data:

# .env.local (never commit)
GOOGLE_SHEETS_ID=your-actual-sheet-id

# For production, set in Cloud Run
gcloud run services update workwrite-landing \
  --set-env-vars GOOGLE_SHEETS_ID=your-production-sheet-id

2. Input Validation

Always validate user inputs:

import { z } from 'zod'

const emailSchema = z.object({
  email: z.string().email('Invalid email format'),
})

export async function POST(request: NextRequest) {
  try {
    const body = await request.json()
    const { email } = emailSchema.parse(body)

    // ... rest of your code
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors[0].message }, { status: 400 })
    }
    // ... handle other errors
  }
}

Testing

1. Component Testing

// __tests__/email-signup.test.tsx
import { render, screen, fireEvent, waitFor } from '@testing-library/react'
import EmailSignup from '../src/app/components/email-signup/email-signup'

describe('EmailSignup', () => {
  test('submits email successfully', async () => {
    global.fetch = jest.fn(() =>
      Promise.resolve({
        ok: true,
        json: () => Promise.resolve({ message: 'Success' }),
      }),
    )

    render(<EmailSignup />)

    const input = screen.getByPlaceholderText('Enter your email')
    const button = screen.getByRole('button', { name: /subscribe/i })

    fireEvent.change(input, { target: { value: 'test@example.com' } })
    fireEvent.click(button)

    await waitFor(() => {
      expect(screen.getByText('Thank you for subscribing!')).toBeInTheDocument()
    })
  })
})

2. API Testing

// __tests__/api/email-signup.test.ts
import { POST } from '../../src/app/api/v1/email-signup/route'

describe('/api/v1/email-signup', () => {
  test('validates email format', async () => {
    const request = new Request('http://localhost', {
      method: 'POST',
      body: JSON.stringify({ email: 'invalid-email' }),
    })

    const response = await POST(request)
    const data = await response.json()

    expect(response.status).toBe(400)
    expect(data.error).toBe('Invalid email format')
  })
})

Conclusion

You now have a complete, production-ready Next.js landing page that:

Collects emails efficiently with a beautiful UI
Stores data in Google Sheets automatically
Scales automatically with Google Cloud Run
Costs minimal for low to medium traffic
Performs excellently with optimized builds
Monitors effectively with built-in analytics

This setup provides a solid foundation for any product launch or marketing campaign. The combination of Next.js 15, Google Sheets, and Cloud Run offers excellent developer experience with enterprise-grade scalability and reliability.

Next Steps

Add A/B testing for different signup copy
Implement email automation with services like SendGrid
Add more landing page sections (testimonials, features, pricing)
Set up CI/CD with GitHub Actions
Add real-time analytics dashboard

The architecture we've built is flexible and can grow with your product needs while maintaining excellent performance and cost efficiency.

Supabase WordPress Integration - Sync WordPress Posts and Pages to Supabase

Dale Nguyen — Wed, 20 Aug 2025 03:56:00 +0000

Are you looking to create a modern, scalable architecture for your WordPress site? Syncing your WordPress content to Supabase opens up powerful possibilities for headless websites, mobile apps, and real-time applications. In this comprehensive guide, we'll walk you through setting up automatic post and page synchronization from WordPress to Supabase using the SupaWP plugin.

Why Sync WordPress to Supabase?

Before diving into the setup, let's understand the benefits:

🚀 Performance: Lightning-fast content delivery through Supabase's edge network
📱 Multi-platform: Build mobile apps, SPAs, and JAMstack sites using the same content
🔄 Real-time: Instant content updates across all your applications
🔒 Security: Robust Row Level Security (RLS) policies protect your data
💰 Cost-effective: Pay only for what you use with Supabase's pricing model

Prerequisites

Before getting started, make sure you have:

WordPress site with admin access
Supabase account and project
SupaWP plugin installed (v1.3.2 or later)
Basic understanding of SQL for table setup

Step 1: Install and Configure SupaWP

Install the Plugin

Download the SupaWP plugin
Upload to your WordPress site via Plugins → Add New → Upload
Activate the plugin

Configure Basic Settings

Navigate to WordPress Admin → SupaWP and configure:

General Settings:

Supabase URL: Your project URL (e.g., https://your-project.supabase.co)
Supabase Anon Key: Your public API key

Security Settings (Critical):

Supabase Service Role Key: Your service role key for server-side operations
This key bypasses Row Level Security and should never be exposed to the frontend

⚠️ Security Note: Always configure the Service Role Key for production use. This ensures secure write operations from WordPress while maintaining public read access.

Step 2: Set Up Supabase Tables

Create the Posts Table

In your Supabase SQL editor, run this command to create the posts table:

CREATE TABLE public.wp_posts (
  id integer PRIMARY KEY,
  post_title text,
  post_content text,
  post_excerpt text,
  post_status text,
  post_type text,
  post_date timestamptz,
  post_modified timestamptz,
  permalink text,
  post_thumbnail text,
  author jsonb,
  taxonomies jsonb,
  custom_fields jsonb,
  synced_at timestamptz DEFAULT now()
);

Create the Pages Table

CREATE TABLE public.wp_pages (
  id integer PRIMARY KEY,
  post_title text,
  post_content text,
  post_excerpt text,
  post_status text,
  post_type text,
  post_date timestamptz,
  post_modified timestamptz,
  permalink text,
  post_thumbnail text,
  author jsonb,
  taxonomies jsonb,
  custom_fields jsonb,
  synced_at timestamptz DEFAULT now()
);

Step 3: Implement Row Level Security

Security is paramount when exposing your content through an API. Let's set up RLS policies that allow public read access while restricting write operations to WordPress only.

Enable RLS on Posts Table

-- Enable Row Level Security
ALTER TABLE public.wp_posts ENABLE ROW LEVEL SECURITY;

-- Allow public read access (anonymous users can read published posts)
CREATE POLICY "Allow public read access"
ON public.wp_posts FOR SELECT
TO anon
USING (post_status = 'publish');

-- Allow authenticated users to read all posts
CREATE POLICY "Allow authenticated read access"
ON public.wp_posts FOR SELECT
TO authenticated
USING (true);

-- Only service role can insert/update/delete (WordPress backend only)
CREATE POLICY "Service role can manage posts"
ON public.wp_posts FOR ALL
TO service_role
USING (true) WITH CHECK (true);

-- Deny all write operations for anonymous and authenticated users
CREATE POLICY "Deny public writes"
ON public.wp_posts FOR INSERT
TO anon, authenticated
WITH CHECK (false);

CREATE POLICY "Deny public updates"
ON public.wp_posts FOR UPDATE
TO anon, authenticated
USING (false);

CREATE POLICY "Deny public deletes"
ON public.wp_posts FOR DELETE
TO anon, authenticated
USING (false);

Apply the Same Security to Pages

Repeat the same RLS setup for the wp_pages table, replacing table references accordingly.

Step 4: Configure WordPress Sync Settings

Now let's configure which content types to sync:

Go to WordPress Admin → SupaWP → Sync Data tab
Select Post Types: Check "Posts" and "Pages"
Custom Post Types: Add any custom post types (comma-separated, e.g., product, event)
Click Save Settings

Step 5: Understanding the Sync Process

Once configured, SupaWP automatically handles synchronization:

What Gets Synced

The plugin captures comprehensive post data:

Basic Info: Title, content, excerpt, status, type
Metadata: Publish date, modified date, permalink
Media: Featured image URL (with retry mechanism for processing delays)
Author Data: Author information as JSON
Taxonomies: Categories, tags, and custom taxonomies
Custom Fields: All non-private custom fields

When Sync Happens

Automatic synchronization triggers on:

Creating a new post → Immediately synced to Supabase
Updating existing content → Updates the Supabase record
Moving to trash → Removes from Supabase
Permanent deletion → Removes from Supabase

Step 6: Using Your Synced Data

Frontend API Access

With your content synced, you can now access it from any frontend application:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient('https://your-project.supabase.co', 'your-anon-key')

// Get all published posts
const { data: posts } = await supabase
  .from('wp_posts')
  .select('*')
  .eq('post_status', 'publish')
  .order('post_date', { ascending: false })

// Get a specific post by ID
const { data: post } = await supabase.from('wp_posts').select('*').eq('id', 123).single()

// Search posts by title
const { data: searchResults } = await supabase
  .from('wp_posts')
  .select('*')
  .textSearch('post_title', 'search term')
  .eq('post_status', 'publish')

Real-time Subscriptions

Take advantage of Supabase's real-time capabilities:

// Subscribe to new posts
const subscription = supabase
  .channel('wp_posts')
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'wp_posts' }, (payload) => {
    console.log('New post published:', payload.new)
    // Update your UI in real-time
  })
  .subscribe()

Step 7: Advanced Customization

Custom Data Modification

You can modify data before it's saved to Supabase:

// In your theme's functions.php
add_filter('supawp_before_saving_to_supabase', function($data) {
  // Add site information
  $data['site_url'] = get_site_url();

  // Add custom SEO data
  $data['seo_title'] = get_post_meta($data['id'], '_yoast_wpseo_title', true);

  // Sanitize content for API consumption
  if (isset($data['post_content'])) {
    $data['post_content'] = wp_strip_all_tags($data['post_content']);
  }

  return $data;
});

Sync Event Hooks

Monitor sync operations:

// Log successful syncs
add_action('supawp_after_saving_to_supabase', function($response_data, $original_data) {
  error_log('Post synced: ' . $original_data['post_title']);
}, 10, 2);

// Handle sync failures
add_action('supawp_sync_error', function($error, $post_data) {
  // Send notification to admin
  wp_mail(get_option('admin_email'), 'Sync Error', $error);
}, 10, 2);

Manual Sync Operations

Use SupaWP's filter system for custom operations:

// Manually sync specific post
$post_data = array(
  'id' => 123,
  'post_title' => 'Custom Post',
  'custom_field' => 'Additional data'
);
apply_filters('supawp_save_data_to_supabase', $post_data);

// Get data from Supabase
$posts = apply_filters('supawp_get_data_from_supabase', 'wp_posts', array(
  'post_status' => 'eq.publish',
  'limit' => '10'
));

Troubleshooting Common Issues

Posts Not Syncing

Check post type selection in SupaWP settings
Verify Service Role Key is configured (not just anon key)
Ensure tables exist in Supabase with correct naming convention

Permission Errors

Verify RLS policies allow service_role to write
Check service role key is correct and has proper permissions
Test connection from WordPress admin

Image Sync Issues

Enable WordPress debugging to see detailed error logs
Check featured image processing - some themes delay image processing
Verify image URLs are publicly accessible

Debug Logging

Enable WordPress debug logging:

// In wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Check /wp-content/debug.log for SupaWP error messages.

Best Practices for Production

Performance Optimization

Index your tables for common query patterns:

   CREATE INDEX idx_wp_posts_status_date
   ON wp_posts(post_status, post_date DESC);

Use selective querying - only fetch fields you need
Implement caching in your frontend application

Security Considerations

Never expose service role key to frontend
Regularly rotate API keys
Monitor database access through Supabase dashboard
Use RLS policies to restrict data access appropriately

Monitoring and Maintenance

Set up monitoring for sync operations
Regular backups of Supabase data
Monitor API usage and costs
Keep SupaWP updated for latest features and security fixes

Use Cases and Examples

JAMstack Blog

Create a lightning-fast blog using Supabase as your content API:

// Next.js example
export async function getStaticProps() {
  const { data: posts } = await supabase
    .from('wp_posts')
    .select('id, post_title, post_excerpt, post_date, permalink')
    .eq('post_status', 'publish')
    .order('post_date', { ascending: false })
    .limit(10)

  return {
    props: { posts },
    revalidate: 60, // Revalidate every minute
  }
}

Mobile App Integration

Use the same content in your React Native app:

const [posts, setPosts] = useState([])

useEffect(() => {
  const fetchPosts = async () => {
    const { data } = await supabase.from('wp_posts').select('*').eq('post_status', 'publish')
    setPosts(data)
  }

  fetchPosts()
}, [])

Multi-site Content Distribution

Sync content from one WordPress site to multiple frontend applications, each with different presentation layers but the same content source.

Conclusion

Syncing WordPress to Supabase with SupaWP opens up a world of possibilities for modern web development. You get the familiar WordPress editing experience combined with the power and flexibility of Supabase's modern database and real-time capabilities.

The automatic synchronization ensures your content is always up-to-date across all platforms, while the robust security model keeps your data safe. Whether you're building a headless website, mobile app, or multi-platform content distribution system, this setup provides a solid foundation for scalable, modern applications.

Start with the basic setup outlined in this guide, then gradually explore the advanced customization options as your needs grow. The combination of WordPress's content management capabilities and Supabase's modern infrastructure creates a powerful platform for any content-driven application.

Resources

This guide covers SupaWP v1.3.2 and later. Features and configuration may vary in different versions.

I Built a Leadership Simulator for Aspiring Tech Leads (And Why The Soft Skills Matter Most)

Dale Nguyen — Sat, 09 Aug 2025 15:01:20 +0000

Let's be honest - I'm good at code, but the thought of managing people terrifies me.

I've been a senior developer for a while now, and everyone keeps asking when I'm going to "take the next step" to Tech Lead or Staff Engineer. The problem? While I'm confident about system design and code reviews, I have no idea how to handle stakeholder politics or motivate struggling team members.

So instead of continuing to put off the inevitable, I built something to help me (and hopefully others) practice.

What is it?

TechLeadPilot is a leadership simulator that puts you in realistic Tech Lead scenarios before you actually have to face them. Think "choose your own adventure" but for workplace situations that'll actually happen to you.

You might face scenarios like:

🔥 Your PM wants to ship without proper testing to hit a deadline
🤝 Two senior engineers can't agree on system architecture
📊 You need to explain why refactoring is worth 2 sprints to your director
😤 A team member keeps missing deadlines but won't admit they're struggling

How it works

Pick a scenario from the library
Read the situation and make your choice or write your response
Get AI feedback on your leadership approach
Learn what you did well and where you can improve

Why I built this

The idea of going from "senior engineer who codes in peace" to "tech lead who spends most of their time in meetings" is honestly pretty scary.

I know I'll need to:

Navigate office politics (ugh)
Influence people who don't report to me
Communicate complex technical stuff to non-technical people
Actually motivate and mentor team members
Make decisions when I don't have all the information

These seem like learnable skills, but I'd rather practice them in a simulator than figure them out by potentially screwing up with real people.

The tech stack

Since this is dev.to:

Frontend: Angular with Analog.js for SSR
Backend: Node.js API routes
Database: Firestore for user data and simulation results
AI: Google Vertex AI for generating personalized feedback
Hosting: Firebase (because it just works)

What's next?

I'm working on:

More scenario types (performance reviews sound terrifying)
Roleplay mode where the AI plays different characters
Progress tracking so I can see if I'm actually getting better at this

Try it out: https://techleadpilot.com/simulations

Fellow aspiring Tech Leads - what scenarios scare you the most? Always looking for new ideas to add!

Building Production-Ready SSR Applications with Analog.js - Lessons from TechLeadPilot

Dale Nguyen — Mon, 28 Jul 2025 14:49:48 +0000

A comprehensive guide to server-side rendering with Angular's modern meta-framework, featuring real-world examples from a job board application

Introduction

Server-side rendering (SSR) has become essential for modern web applications, offering improved SEO, faster initial page loads, and better user experience. While Angular has supported SSR through Angular Universal for years, Analog.js emerges as a compelling alternative that brings the developer experience of modern meta-frameworks like Next.js to the Angular ecosystem.

In this article, I'll share the lessons learned from building TechLeadPilot.com, a job board platform for senior engineers and more, using Analog.js with GCP backend. We'll explore the challenges, solutions, and best practices discovered during the development of complex features like authentication, real-time data fetching, and a comprehensive favorites system.

What is Analog.js?

Analog.js is a meta-framework for Angular that provides:

File-based routing similar to Next.js
Server-side rendering out of the box
API routes with full-stack capabilities
Static site generation support
Vite-powered build system for fast development

Unlike traditional Angular applications, Analog.js eliminates much of the configuration complexity while maintaining the power and type safety that Angular developers love.

Project Architecture Overview

TechLeadPilot is built as an Nx monorepo with the following structure:

techleadpilot/
├── landing/                    # Analog.js application
│   ├── src/
│   │   ├── app/
│   │   │   ├── components/     # Reusable UI components
│   │   │   ├── pages/          # File-based routes
│   │   │   ├── services/       # Business logic services
│   │   │   ├── types/          # TypeScript interfaces
│   │   │   └── utils/          # Utility functions
│   │   └── server/             # Server-side API routes
│   ├── vite.config.ts          # Vite configuration
│   └── project.json            # Nx project configuration
├── firestore.rules             # Firebase security rules
└── nx.json                     # Nx workspace configuration

Key Technologies

Frontend: Analog.js (Angular 20)
Backend: Firebase Functions + Firestore
Authentication: Firebase Auth
Styling: Tailwind CSS
Build Tool: Vite
Monorepo: Nx

Setting Up Analog.js with Firebase

Initial Configuration

The journey begins with configuring Analog.js to work seamlessly with Firebase. Here's the essential setup:

// app.config.ts
import { ApplicationConfig } from '@angular/core'
import { provideRouter } from '@angular/router'
import { provideClientHydration } from '@angular/platform-browser'
import { provideFileRouter } from '@analogjs/router'
import { provideHttpClient } from '@angular/common/http'
import { provideFirebaseApp, initializeApp } from '@angular/fire/app'
import { provideAuth, getAuth } from '@angular/fire/auth'
import { provideFirestore, getFirestore } from '@angular/fire/firestore'
import { firebaseConfig } from './firebase-config'

export const appConfig: ApplicationConfig = {
  providers: [
    provideFileRouter(),
    provideClientHydration(),
    provideHttpClient(),
    provideFirebaseApp(() => initializeApp(firebaseConfig)),
    provideAuth(() => getAuth()),
    provideFirestore(() => getFirestore()),
  ],
}

Vite Configuration and SSR Troubleshooting

The most challenging aspect was configuring Vite to handle Firebase packages in SSR mode. Here are the critical configuration points:

// Key SSR configuration in vite.config.ts
ssr: {
  noExternal: [
    '@angular/fire/**',
    'firebase/**',
    'tslib',
    /^@firebase\//,
  ],
  external: ['rxjs']
}

Common SSR Errors We Encountered

1. tslib Destructuring Error

Error: Cannot destructure property '__extends' of 'import_tslib.default'
Solution: Add 'tslib' to noExternal array

2. RxJS "exports is not defined"

Error: ReferenceError: exports is not defined
Solution: Move RxJS to external array instead of noExternal

3. Firebase Module Resolution

Error: Module not found: firebase/auth
Solution: Use regex pattern /^@firebase\// to catch all Firebase submodules

Key Configuration Strategy

noExternal: Firebase packages that need Vite transformation
external: RxJS works better with Node.js native handling
Module resolution: Use proper ESM conditions for compatibility

Key Learning: Understanding which packages need SSR transformation vs. native Node.js handling is critical for Firebase integration.

File-Based Routing in Practice

Analog.js uses file-based routing similar to Next.js, which significantly simplifies route management:

pages/
├── (home).page.ts              # Route: /
├── jobs/
│   ├── (job-list).page.ts      # Route: /jobs
│   ├── [jobId].page.ts         # Route: /jobs/:jobId
│   └── [jobId].server.ts       # Server-side data loading
└── account/
    └── favorites.page.ts       # Route: /account/favorites

Server-Side Data Loading with Analog.js

Analog.js provides a powerful pattern for loading data on the server before rendering, similar to Next.js's getServerSideProps. This ensures data is available during SSR, improving SEO and initial page load performance.

The Server-Side Loader Pattern

The key is the .server.ts file that exports a load function:

// pages/jobs/[jobId].server.ts
import { PageServerLoad } from '@analogjs/router'
import { getJobById } from '../../../server/services/firestore-jobs.service'

export const load = async ({ params }: PageServerLoad) => {
  const jobId = params?.['jobId']

  // Fetch data server-side before rendering
  const job = jobId ? await getJobById(jobId) : null

  return { job }
}

Consuming Server Data in Components

The page component receives the server data through the load input:

// pages/jobs/[jobId].page.ts
export default class JobDetailPageComponent implements OnInit {
  @Input() set load(data: LoadResult<typeof load>) {
    this.data = data
  }

  data!: LoadResult<typeof load>

  ngOnInit(): void {
    // SSR-safe browser API usage
    if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
      window.scrollTo(0, 0)
    }
  }
}

Key Benefits

SEO-Friendly: Data is available during server rendering
Type-Safe: TypeScript infers the exact shape of loaded data
Performance: No client-side data fetching delays
Error Handling: Server-side errors can be handled gracefully

Error Handling in Server Loaders

export const load = async ({ params }: PageServerLoad) => {
  try {
    const jobId = params?.['jobId']
    const job = jobId ? await getJobById(jobId) : null

    return {
      job,
      error: null,
    }
  } catch (error) {
    console.error('Failed to load job:', error)
    return {
      job: null,
      error: 'Failed to load job details',
    }
  }
}

Key Learning: Server-side data loading provides better SEO and performance but requires careful error handling and SSR-safe component code.

Firebase Integration Patterns

Server-Side Firebase Admin

For server-side operations, we use Firebase Admin SDK:

// server/services/firebase-admin.ts
import { initializeApp, cert, getApps } from 'firebase-admin/app'
import { getFirestore } from 'firebase-admin/firestore'

let app: App
if (!getApps().length) {
  app = initializeApp({
    credential: applicationDefault(),
    projectId: process.env['GOOGLE_CLOUD_PROJECT'],
  })
} else {
  app = getApps()[0]
}

export const db = getFirestore(app)

Client-Side Firebase Services

For client-side operations, we create services that handle authentication and data operations:

// Key patterns in favorites.service.ts
@Injectable({ providedIn: 'root' })
export class FavoritesService {
  private user$ = user(this.auth)

  addToFavorites(job: Job): Observable<void> {
    return this.user$.pipe(
      switchMap((user) => {
        if (!user) throw new Error('Authentication required')

        const favoritesRef = collection(this.firestore, `users/${user.uid}/favorites`)
        const expireOn = new Date()
        expireOn.setMonth(expireOn.getMonth() + 3) // 3-month expiration

        return from(addDoc(favoritesRef, { ...job, expireOn }))
      }),
    )
  }
}

Key Learning: Use RxJS switchMap for complex async operations and always validate authentication before database operations.

Type Safety and Data Modeling

Handling Partial Types from Firestore

One significant challenge was dealing with TypeScript types when Firestore returns partial data:

// types/job.types.ts
export interface Job {
  id: string
  title: string
  company: string
  location: string
  description: string
  requirements: string[]
  benefits: string[]
  skills: string[]
  salary?: {
    min: number
    max: number
    currency: string
  }
  type: 'full-time' | 'part-time' | 'contract'
  experience: 'junior' | 'mid' | 'senior' | 'lead'
  isRemote: boolean
  isUrgent: boolean
  postedDate: string
  link: string
  logo?: string
}

export interface JobFilters {
  search: string
  location: string
  type: string
  experience: string
  isRemote: boolean
  salaryRange: {
    min: number
    max: number
  }
}

Type-Safe Component Input Handling

When building reusable components, we needed to handle both full and partial job objects:

// Safe handling of partial data in components
export class JobDetailComponent {
  @Input() job: Job | Partial<Job> | null = null

  get processedJob() {
    if (!this.job) return null

    return {
      ...this.job,
      requirements: Array.isArray(this.job.requirements) ? this.job.requirements : [],
      salary: this.job.salary ?? { min: 0, max: 0, currency: '' },
      company: this.job.company ?? '',
      // ... provide safe defaults for all fields
    }
  }
}

Key Learning: Create getter methods that safely handle partial data and provide sensible defaults to prevent runtime errors.

Advanced Component Patterns

Reusable Components with Context

When extracting the job detail functionality into a reusable component, we needed to handle different contexts (standalone page vs. modal):

// Reusable component that adapts to different contexts
@Component({
  selector: 'app-job-detail',
  template: `
    <div class="min-h-screen bg-gray-50 py-8">
      <div class="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8">
        <!-- Back Button (conditional) -->
        <button
          *ngIf="showBackButton"
          (click)="goBack()"
          class="flex items-center text-blue-600 hover:text-blue-800 mb-6"
        >
          <svg class="w-5 h-5 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
          </svg>
          {{ backButtonText }}
        </button>

        <!-- Favorite Button (conditional) -->
        <button
          *ngIf="showFavoriteButton && (user$ | async)"
          (click)="toggleFavorite()"
          [disabled]="favoriteLoading"
          [title]="isFavorited ? 'Remove from favorites' : 'Save to favorites (expires after 3 months)'"
          class="p-2 rounded-full hover:bg-gray-100 transition-colors"
          [class.text-red-500]="isFavorited"
          [class.text-gray-400]="!isFavorited"
        >
          <svg class="w-5 h-5" [class.fill-current]="isFavorited" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path
              stroke-linecap="round"
              stroke-linejoin="round"
              stroke-width="2"
              d="M4.318 6.318a4.5 4.5 0 000 6.364L12 20.364l7.682-7.682a4.5 4.5 0 00-6.364-6.364L12 7.636l-1.318-1.318a4.5 4.5 0 00-6.364 0z"
            />
          </svg>
        </button>

        <!-- Job content -->
        <div *ngIf="processedJob" class="bg-white rounded-lg shadow-sm border border-gray-200">
          <!-- Job details implementation -->
        </div>
      </div>
    </div>
  `,
})
export class JobDetailComponent implements OnInit {
  @Input() job: Job | Partial<Job> | null = null
  @Input() showBackButton: boolean = true
  @Input() backButtonText: string = 'Back to Jobs'
  @Input() showFavoriteButton: boolean = true

  private favoritesService = inject(FavoritesService)
  private auth = inject(Auth)

  user$ = user(this.auth)
  isFavorited = false
  favoriteLoading = false

  ngOnInit(): void {
    // SSR-safe initialization
    if (typeof window !== 'undefined' && typeof window.scrollTo === 'function') {
      window.scrollTo(0, 0)
    }

    // Check if job is favorited
    if (this.job?.id && this.showFavoriteButton) {
      this.favoritesService.isJobFavorited(this.job.id).subscribe({
        next: (isFavorited) => {
          this.isFavorited = isFavorited
        },
        error: (error) => {
          console.error('Error checking favorite status:', error)
        },
      })
    }
  }

  toggleFavorite(): void {
    if (!this.job || !this.job.id) return

    this.favoriteLoading = true

    if (this.isFavorited) {
      // Remove from favorites logic
      this.user$
        .pipe(
          switchMap((user) => {
            if (!user) throw new Error('User must be authenticated')
            return this.favoritesService.getFavoriteByJobId(this.job!.id!)
          }),
          switchMap((favorite) => {
            if (!favorite?.favoriteId) throw new Error('Favorite not found')
            return this.user$.pipe(
              switchMap((user) => {
                if (!user) throw new Error('User must be authenticated')
                return this.favoritesService.removeFromFavorites(user.uid, favorite.favoriteId!)
              }),
            )
          }),
        )
        .subscribe({
          next: () => {
            this.isFavorited = false
            this.favoriteLoading = false
          },
          error: (error) => {
            console.error('Error removing favorite:', error)
            this.favoriteLoading = false
          },
        })
    } else {
      // Add to favorites
      const jobForFavorite = this.job as Job
      this.favoritesService.addToFavorites(jobForFavorite).subscribe({
        next: () => {
          this.isFavorited = true
          this.favoriteLoading = false
        },
        error: (error) => {
          console.error('Error adding favorite:', error)
          this.favoriteLoading = false
        },
      })
    }
  }

  goBack(): void {
    if (typeof window !== 'undefined') {
      window.history.back()
    }
  }
}

UX and Accessibility Enhancements

Hover Effects and Interactions

Modern web applications require smooth, engaging interactions:

// Key accessibility patterns
export class FavoritesPageComponent {
  // Template with hover effects and accessibility
  template: `
    <div 
      (click)="viewJobDetails(favorite)"
      (keydown)="onCardKeydown($event, favorite)"
      tabindex="0"
      role="button"
      [attr.aria-label]="'View details for ' + favorite.title"
      class="hover:shadow-lg hover:border-blue-300 hover:-translate-y-1 
             focus:ring-2 focus:ring-blue-500 transition-all duration-300"
    >
      <!-- Prevent event bubbling on nested buttons -->
      <button (click)="$event.stopPropagation()">Apply Now</button>
    </div>
  `

  onCardKeydown(event: KeyboardEvent, favorite: FavoriteJob): void {
    if (event.key === 'Enter' || event.key === ' ') {
      event.preventDefault()
      this.viewJobDetails(favorite)
    }
  }
}

Key Learning: Always implement keyboard navigation and proper ARIA attributes for accessibility compliance.

State Management with Signals

Analog.js applications can leverage Angular's new Signals API for reactive state management:

// Using signals for reactive state management
@Component({
  template: `
    <div *ngIf="loading()" class="loading-spinner">Loading...</div>
    <div *ngIf="error()" class="error-message">{{ error() }}</div>
    <div *ngIf="!loading() && favorites().length === 0" class="empty-state">No favorites yet</div>
    <div *ngIf="favorites().length > 0" class="favorites-grid">
      <!-- Favorites content -->
    </div>
  `,
})
export class FavoritesPageComponent implements OnInit {
  private favoritesService = inject(FavoritesService)
  private auth = inject(Auth)

  // Reactive signals
  favorites = signal<FavoriteJob[]>([])
  loading = signal<boolean>(true)
  error = signal<string | null>(null)
  selectedJob = signal<FavoriteJob | null>(null)

  user$ = user(this.auth)

  ngOnInit(): void {
    this.user$.subscribe((user) => {
      if (user) {
        this.loadFavorites()
      } else {
        this.loading.set(false)
      }
    })
  }

  private loadFavorites(): void {
    this.loading.set(true)
    this.error.set(null)

    this.favoritesService.getUserFavorites().subscribe({
      next: (favorites) => {
        this.favorites.set(favorites)
        this.loading.set(false)
      },
      error: (error) => {
        console.error('Error loading favorites:', error)
        this.error.set('Failed to load favorites')
        this.loading.set(false)
      },
    })
  }

  // Type-safe conversion for component input
  get selectedJobForDisplay(): Job | null {
    const job = this.selectedJob()
    if (!job) return null

    // Convert FavoriteJob to Job by omitting the extra fields
    const { favoriteId, expireOn, addedOn, ...jobData } = job
    return jobData as Job
  }
}

Performance Optimization

Lazy Loading and Code Splitting

Analog.js automatically handles code splitting for routes, but we can optimize further:

// Lazy loading components
const JobCardComponent = lazy(() => import('../job-card/job-card.component'))
const JobFiltersComponent = lazy(() => import('../job-filters/job-filters.component'))

// Using dynamic imports for heavy features
async loadFavoritesFeature() {
  const { FavoritesService } = await import('../../services/favorites.service')
  return FavoritesService
}

Efficient Data Fetching

// server/services/firestore-jobs.service.ts
export async function getAllJobs({
  limit = 10,
  filters = {} as Partial<JobFilters>,
  sort = { field: 'postedDate', direction: 'desc' as 'asc' | 'desc' },
  cursor = undefined,
} = {}) {
  const baseCollection = db.collection('jobs')
  let filteredQuery = baseCollection as FirebaseFirestore.Query

  // Apply filters efficiently
  if (filters.type) {
    filteredQuery = filteredQuery.where('type', '==', filters.type)
  }
  if (filters.experience) {
    filteredQuery = filteredQuery.where('experience', '==', filters.experience)
  }
  if (filters.isRemote) {
    filteredQuery = filteredQuery.where('isRemote', '==', filters.isRemote)
  }

  // Pagination with cursors
  filteredQuery = filteredQuery.orderBy(sort.field, sort.direction)

  if (cursor) {
    const cursorDate = new Date(cursor)
    if (!isNaN(cursorDate.getTime())) {
      filteredQuery = filteredQuery.startAfter(cursorDate)
    }
  }

  const snapshot = await filteredQuery.limit(limit).get()
  let jobs = snapshot.docs.map((doc) => convertJobTimestamps({ id: doc.id, ...doc.data() }))

  // Client-side filtering for complex queries
  if (filters.search && typeof filters.search === 'string' && filters.search.trim() !== '') {
    const searchTerm = filters.search.trim().toLowerCase()
    jobs = jobs.filter((job) => {
      return (
        (job.title && job.title.toLowerCase().includes(searchTerm)) ||
        (job.company && job.company.toLowerCase().includes(searchTerm)) ||
        (job.description && job.description.toLowerCase().includes(searchTerm))
      )
    })
  }

  const newCursor = jobs.length > 0 ? jobs[jobs.length - 1].postedDate : null
  return { jobs, cursor: newCursor }
}

Security Best Practices

Firebase Security Rules

Implementing proper security is crucial for user data protection:

// firestore.rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // Helper functions
    function isAuthenticated() {
      return request.auth != null;
    }

    function isOwner(userId) {
      return request.auth != null && request.auth.uid == userId;
    }

    function isAdmin() {
      return request.auth != null &&
             resource.data.admins != null &&
             request.auth.uid in resource.data.admins;
    }

    // Jobs collection - public read, admin write
    match /jobs/{jobId} {
      allow read: if true;
      allow write: if isAdmin();
    }

    // User-specific favorites
    match /users/{userId} {
      allow read, write: if isOwner(userId);

      match /favorites/{favoriteId} {
        allow read, write: if isOwner(userId) || isAdmin();
      }
    }
  }
}

Input Validation and Sanitization

// services/favorites.service.ts
addToFavorites(job: Job): Observable<void> {
  return this.user$.pipe(
    switchMap((user) => {
      if (!user) {
        throw new Error('User must be authenticated to add favorites')
      }

      // Validate job data before saving
      if (!job.id || !job.title || !job.company) {
        throw new Error('Invalid job data')
      }

      // Sanitize and validate expiration date
      const expireOn = new Date()
      expireOn.setMonth(expireOn.getMonth() + 3)

      if (expireOn <= new Date()) {
        throw new Error('Invalid expiration date')
      }

      const favoritesRef = collection(this.firestore, `users/${user.uid}/favorites`)

      const favoriteJob: Omit<FavoriteJob, 'favoriteId'> = {
        ...job,
        expireOn: Timestamp.fromDate(expireOn),
        addedOn: Timestamp.fromDate(new Date())
      }

      return from(addDoc(favoritesRef, favoriteJob))
    }),
    map(() => void 0)
  )
}

Testing Strategies

Component Testing with SSR

Testing SSR components requires special consideration for browser APIs:

// job-detail.component.spec.ts
import { ComponentFixture, TestBed } from '@angular/core/testing'
import { JobDetailComponent } from './job-detail.component'
import { FavoritesService } from '../../services/favorites.service'
import { Auth } from '@angular/fire/auth'
import { of } from 'rxjs'

describe('JobDetailComponent', () => {
  let component: JobDetailComponent
  let fixture: ComponentFixture<JobDetailComponent>
  let mockFavoritesService: jasmine.SpyObj<FavoritesService>
  let mockAuth: jasmine.SpyObj<Auth>

  beforeEach(async () => {
    // Mock services
    const favoritesServiceSpy = jasmine.createSpyObj('FavoritesService', [
      'isJobFavorited',
      'addToFavorites',
      'removeFromFavorites',
    ])
    const authSpy = jasmine.createSpyObj('Auth', ['currentUser'])

    await TestBed.configureTestingModule({
      imports: [JobDetailComponent],
      providers: [
        { provide: FavoritesService, useValue: favoritesServiceSpy },
        { provide: Auth, useValue: authSpy },
      ],
    }).compileComponents()

    mockFavoritesService = TestBed.inject(FavoritesService) as jasmine.SpyObj<FavoritesService>
    mockAuth = TestBed.inject(Auth) as jasmine.SpyObj<Auth>
  })

  beforeEach(() => {
    fixture = TestBed.createComponent(JobDetailComponent)
    component = fixture.componentInstance

    // Mock window object for SSR testing
    Object.defineProperty(window, 'scrollTo', {
      value: jasmine.createSpy('scrollTo'),
      writable: true,
    })
  })

  it('should handle empty job gracefully', () => {
    component.job = null
    fixture.detectChanges()

    expect(component.processedJob).toBeNull()
  })

  it('should check if job is favorited on init', () => {
    const mockJob = {
      id: 'test-job-id',
      title: 'Test Job',
      company: 'Test Company',
      // ... other job properties
    }

    component.job = mockJob
    component.showFavoriteButton = true
    mockFavoritesService.isJobFavorited.and.returnValue(of(true))

    component.ngOnInit()

    expect(mockFavoritesService.isJobFavorited).toHaveBeenCalledWith('test-job-id')
    expect(component.isFavorited).toBe(true)
  })
})

Service Testing

// favorites.service.spec.ts
import { TestBed } from '@angular/core/testing'
import { FavoritesService } from './favorites.service'
import { Firestore } from '@angular/fire/firestore'
import { Auth } from '@angular/fire/auth'
import { of } from 'rxjs'

describe('FavoritesService', () => {
  let service: FavoritesService
  let mockFirestore: jasmine.SpyObj<Firestore>
  let mockAuth: jasmine.SpyObj<Auth>

  beforeEach(() => {
    const firestoreSpy = jasmine.createSpyObj('Firestore', ['collection', 'doc'])
    const authSpy = jasmine.createSpyObj('Auth', ['currentUser'])

    TestBed.configureTestingModule({
      providers: [
        { provide: Firestore, useValue: firestoreSpy },
        { provide: Auth, useValue: authSpy },
      ],
    })

    service = TestBed.inject(FavoritesService)
    mockFirestore = TestBed.inject(Firestore) as jasmine.SpyObj<Firestore>
    mockAuth = TestBed.inject(Auth) as jasmine.SpyObj<Auth>
  })

  it('should be created', () => {
    expect(service).toBeTruthy()
  })

  it('should throw error when user is not authenticated', (done) => {
    // Mock unauthenticated user
    spyOnProperty(service, 'user$', 'get').and.returnValue(of(null))

    const mockJob = {
      id: 'test-job',
      title: 'Test Job',
      // ... other properties
    }

    service.addToFavorites(mockJob as any).subscribe({
      error: (error) => {
        expect(error.message).toBe('User must be authenticated to add favorites')
        done()
      },
    })
  })
})

Deployment and Production Considerations

Build Optimization

// project.json
{
  "targets": {
    "build": {
      "executor": "@analogjs/platform:vite",
      "options": {
        "configFile": "landing/vite.config.ts",
        "main": "landing/src/main.ts",
        "outputPath": "dist/landing/client",
        "tsConfig": "landing/tsconfig.app.json"
      },
      "configurations": {
        "production": {
          "sourcemap": false,
          "mode": "production"
        }
      }
    }
  }
}

Environment Configuration

// Environment-specific configuration
export const environment = {
  production: process.env['NODE_ENV'] === 'production',
  firebase: {
    projectId: process.env['FIREBASE_PROJECT_ID'],
    appId: process.env['FIREBASE_APP_ID'],
    // ... other config
  },
  api: {
    baseUrl: process.env['API_BASE_URL'] || 'http://localhost:4200',
  },
}

Common Pitfalls and Solutions

1. Hydration Mismatch

Problem: Server-rendered content doesn't match client-side rendering.

Solution: Ensure consistent data and avoid browser-specific logic in templates.

// Use NgZone and afterNextRender for browser-specific code
import { afterNextRender } from '@angular/core'

@Component({...})
export class MyComponent {
  constructor() {
    afterNextRender(() => {
      // Browser-only code here
      this.initializeClientOnlyFeatures()
    })
  }
}

2. Firebase Auth State Persistence

Problem: Authentication state is lost on page refresh in SSR.

Solution: Handle authentication state properly with observables.

@Component({...})
export class AuthComponent implements OnInit {
  user$ = user(this.auth)
  isLoading = true

  ngOnInit() {
    this.user$.subscribe(user => {
      this.isLoading = false
      // Handle user state
    })
  }
}

3. Memory Leaks with Subscriptions

Problem: Observable subscriptions not cleaned up properly.

Solution: Use takeUntilDestroyed operator (Angular 16+).

import { takeUntilDestroyed } from '@angular/core/rxjs-interop'

@Component({...})
export class MyComponent {
  private destroyRef = inject(DestroyRef)

  ngOnInit() {
    this.dataService.getData()
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe(data => {
        // Handle data
      })
  }
}

Future Roadmap and Improvements

Based on our experience building TechLeadPilot, here are some areas for future enhancement:

1. Performance Optimizations

Implement service worker for offline functionality
Add image optimization and lazy loading
Implement progressive loading for large datasets

2. User Experience Enhancements

Add real-time notifications
Implement advanced search with filters
Create personalized job recommendations

3. Technical Improvements

Migrate to Angular's new control flow syntax
Implement comprehensive error boundaries
Add monitoring and analytics

Conclusion

Building a production-ready SSR application with Analog.js has been an enlightening experience. The framework successfully bridges the gap between Angular's robust architecture and the developer experience of modern meta-frameworks.

Key Takeaways:

SSR-First Approach: Always consider server-side rendering implications when writing components and services.
Type Safety: Leverage TypeScript's type system extensively, especially when dealing with partial data from APIs.
Firebase Integration: Requires careful configuration for SSR environments, but provides powerful real-time capabilities.
Performance Matters: Implement proper loading states, pagination, and caching strategies from the beginning.
Accessibility: Don't treat accessibility as an afterthought - implement it from the start.
Testing Strategy: SSR applications require special testing considerations, particularly around browser API usage.

Analog.js has proven to be a mature and capable framework for building complex, production-ready applications. While there are challenges specific to SSR and Firebase integration, the benefits of improved SEO, faster initial page loads, and better user experience make it a compelling choice for Angular developers.

The combination of Analog.js's developer experience with Angular's enterprise-grade features creates a powerful platform for building modern web applications. As the framework continues to evolve, we can expect even better integration with the Angular ecosystem and improved developer tooling.

Whether you're building a simple blog or a complex application like TechLeadPilot, Analog.js provides the foundation needed to create fast, scalable, and maintainable SSR applications with Angular.

This article is based on real-world experience building TechLeadPilot.com, a job board platform for senior engineers and more.

A Step-by-Step Guide to Deploying n8n on Oracle Cloud Free Tier

Dale Nguyen — Thu, 03 Jul 2025 04:08:41 +0000

For those who want to jump straight to the code, I've created a starter template repository on GitHub. It includes all the configurations and scripts mentioned in this guide.

n8n-self-hosted-cloudflare-starter on GitHub

In a previous article, we explored running n8n locally and exposing it to the internet using a Cloudflare Tunnel. This approach is great for quick setups, testing, or personal use, as it allows you to keep your workflows private and avoid complex network configurations. However, it comes with a major limitation: your server or laptop must remain powered on and connected to the internet at all times for your automations to work. This can be inconvenient, less reliable for production use, and may not be suitable for 24/7 automation needs.

Cloudflare Tunnel (Localhost) Approach:

Pros:
- Simple to set up
- No need to manage cloud infrastructure
- Good for development and testing
Cons:
- Requires your local machine to be always on
- Not ideal for production or critical workflows
- Limited scalability and reliability

In this guide, we take automation to the next level by installing and configuring n8n directly on Oracle Cloud's Always Free Tier. This approach provides a dedicated, always-on environment for your workflows, making it much more suitable for production or mission-critical automations.

Oracle Cloud Deployment:

Pros:
- Always-on, reliable hosting
- No need to keep your laptop/server running
- Scalable and more secure
- Free tier offers generous resources
Cons:
- Slightly more complex setup
- Requires managing cloud resources and security
- Data on the free tier may be wiped out at any time (not guaranteed for production use)

By the end of this article, you'll have a robust, cloud-hosted n8n instance that's accessible from anywhere, without the need to keep your personal device online.

Why Oracle Cloud (Free Tier +)?

Oracle Cloud Infrastructure (OCI) offers an incredibly generous "Always Free" tier, making it an attractive option for self-hosting applications like n8n. While other cloud providers often limit their free tiers to 12 months or offer minimal resources, OCI provides:

Perpetual Free Resources: Unlike many competitors, Oracle's "Always Free" tier resources do not expire after a trial period.
Generous Compute Resources: You can typically get a VM.Standard.A1.Flex (ARM-based) instance with up to 4 OCPUs and 24 GB of RAM, or 2 AMD-based VMs with 1 OCPU and 1 GB RAM each. These are ample resources for running n8n and its database.
Ample Storage: Up to 200 GB of Block Volume storage.
Free Networking: Includes a public IP address, and significant outbound data transfer.
Complete Control: You get full root access to your Linux VM, allowing for custom installations like Docker, Nginx, and databases, giving you maximum flexibility over your n8n environment.

This combination of free, powerful, and persistent resources makes OCI an ideal choice for running your n8n automation workflows without incurring monthly costs.

Step-by-Step Installation

This guide assumes you have an Oracle Cloud Free Tier account created, a domain name registered (e.g., n8n.yourdomain.com), and basic familiarity with the Linux command line. We'll use an Ubuntu instance and Docker Compose for a robust and easily manageable n8n setup.

1. Create Your Oracle Cloud Instance

Log in to your OCI Console.
Navigate to Compute > Instances.
Click "Create Instance".
Configuration:
- Name: Give your instance a descriptive name (e.g., n8n-instance).
- Availability Domain & Fault Domain: Choose a suitable AD and FD for your region (e.g., AD-1, FD-2 in ca-toronto-1).
- Image and Shape:
  - Image: Click "Change Image" and select Canonical Ubuntu (latest version, e.g., 22.04 LTS).
  - Shape: Click "Change Shape". Choose Ampere architecture, and select VM.Standard.A1.Flex. Allocate OCPUs and RAM within your Always Free limits (e.g., 2 OCPUs, 12 GB RAM for a good balance).
- Networking:
  - Virtual Cloud Network: Choose your existing VCN or create a new one.
  - Subnet: Choose an existing subnet or create a new one.
  - Public IP: Ensure "Assign a public IP address" is checked. Note down this IP (e.g., 40.233.98.119).
- SSH Keys: Paste your existing public SSH key or generate a new one. Download the corresponding private key (.key file) to your local machine and keep it secure (e.g., ~/.ssh/my_oracle_key.key).
- Boot Volume: The default 50GB is usually sufficient for n8n.
Click "Create". Wait for the instance to provision and become "Running".

Map Your Domain to Your Oracle Cloud Instance

Before you can access your n8n instance using a custom domain (like n8n.yourdomain.com), you need to point your domain to your Oracle Cloud instance's public IP address. This is done by creating an A record in your domain's DNS settings.

Steps:

Find your instance's public IP:

In the Oracle Cloud Console, go to your instance details and note the "Public IP Address" (e.g., 40.233.98.119).

Log in to your domain registrar or DNS provider:

This could be Namecheap, GoDaddy, Cloudflare, Google Domains, etc.

Add an A record:

Type: A
Name/Host: n8n (or the subdomain you want to use)
Value: Your Oracle Cloud instance's public IP (e.g., 40.233.98.119)
TTL: Default or 5-10 minutes

For example, to use n8n.yourdomain.com, set the Name/Host to n8n and the Value to your instance's public IP.

Wait for DNS propagation:
- Changes usually take a few minutes, but can take up to 24 hours. You can check if your domain points to the correct IP using tools like Dig from Google Toolbox.

Once this is set up, visiting http://n8n.yourdomain.com in your browser should reach your Oracle Cloud instance (after Nginx is configured in the next steps).

2. Configure OCI Network Security (Firewall Rules)

Even with iptables and UFW on the instance, OCI's network security groups (NSGs) or security lists act as a critical outer firewall.

Go to your OCI Console: Navigate to Networking > Virtual Cloud Networks.
Select your VCN that contains your instance.
Click on Security Lists (or Network Security Groups if you're using them).
Select the Security List/NSG associated with your instance's subnet/VNIC.
Add Ingress Rules:
- Click "Add Ingress Rules".
- Rule 1 (SSH):
  - Source Type: CIDR
  - Source CIDR: 0.0.0.0/0 (or your specific IP for more security)
  - IP Protocol: TCP
  - Destination Port Range: 22
- Rule 2 (HTTP):
  - Source Type: CIDR
  - Source CIDR: 0.0.0.0/0
  - IP Protocol: TCP
  - Destination Port Range: 80
- Rule 3 (HTTPS):
  - Source Type: CIDR
  - Source CIDR: 0.0.0.0/0
  - IP Protocol: TCP
  - Destination Port Range: 443

3. Initial Server Setup & SSH Access

SSH into your instance:
The default username for Ubuntu instances on OCI is ubuntu.

chmod 400 /path/to/your/my_oracle_key.key # Set correct permissions for private key
ssh -i /path/to/your/my_oracle_key.key ubuntu@<your_instance_public_ip>

(Replace with your actual private key path and public IP).

Update System Packages:
```
sudo apt update -y
sudo apt upgrade -y
```
Reset iptables Policies (Crucial for OCI Connectivity):
This step has resolved "No route to host" errors for many Oracle Cloud users, as it clears any hidden low-level firewall rules.
```
sudo iptables -P INPUT ACCEPT
sudo iptables -P OUTPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
sudo iptables -F
sudo apt install iptables-persistent -y
sudo netfilter-persistent save
```
During iptables-persistent installation, confirm saving IPv4 and IPv6 rules.

Configure Ubuntu Firewall (UFW):

sudo ufw allow 22/tcp # Allow SSH
sudo ufw allow 80/tcp # Allow HTTP
sudo ufw allow 443/tcp # Allow HTTPS
sudo ufw enable
sudo ufw status verbose # Verify rules are active

Reboot the Instance (Recommended):
To ensure all network changes are applied cleanly.
```
sudo reboot
```
Wait a few minutes, then SSH back in.

4. Install Docker and Docker Compose

Docker is the recommended way to run n8n in production.

Connect via SSH after reboot.

Install Docker & Docker Compose Plugin:

sudo apt install ca-certificates curl gnupg lsb-release -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update -y
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl start docker
sudo systemctl enable docker

Add your user (ubuntu) to the docker group:

sudo usermod -aG docker ubuntu
newgrp docker # Apply group changes immediately for current session

5. Install Nginx & Prepare for Certbot

Install Nginx:

sudo apt install nginx -y
sudo systemctl start nginx
sudo systemctl enable nginx

Create Nginx Web Root and Test Page:

sudo mkdir -p /var/www/html
echo "Hello from Nginx! Testing HTTP Connectivity." | sudo tee /var/www/html/index.html
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html

Configure Nginx for your Domain (HTTP only for now):
Create a new Nginx configuration file for your domain.

sudo nano /etc/nginx/conf.d/n8n.conf

Paste this content (replace n8n.yourdomain.com with your domain):

server {
    listen 80;
    listen [::]:80;
    server_name n8n.yourdomain.com; # Your exact domain

    location /.well-known/acme-challenge/ {
        root /var/www/html; # Used by Certbot for verification
        allow all;
    }

    location / {
        root /var/www/html; # Temporarily serve static HTML
        index index.html index.htm;
        try_files $uri $uri/ =404;
    }
}

Save and exit (Ctrl+X, Y, Enter).

Test Nginx Configuration and Reload:

sudo nginx -t
sudo systemctl reload nginx

Verify HTTP Access (from your local browser):
Visit http://n8n.yourdomain.com. You should now see "Hello from Nginx! Testing HTTP Connectivity." This confirms Nginx is properly serving.

6. Obtain SSL Certificate with Certbot (Let's Encrypt)

Install Certbot and Nginx Plugin:

sudo apt install certbot python3-certbot-nginx -y

Run Certbot:

sudo certbot --nginx -d n8n.yourdomain.com

- Follow the prompts: Enter email, agree to terms, choose to redirect HTTP to HTTPS (`2`).
- Certbot will automatically modify your Nginx config to include SSL and redirect HTTP traffic.

Test Nginx Configuration and Reload (again):

sudo nginx -t
sudo systemctl reload nginx

Test Automatic Renewal:
```
sudo certbot renew --dry-run
```
This should complete successfully.
Verify HTTPS in Browser:
Go to https://n8n.yourdomain.com. You should see a secure padlock.

7. Install n8n with Docker Compose & Database

Now, we'll set up n8n with a PostgreSQL database using Docker Compose.

Create a directory for n8n:
```
mkdir ~/n8n
cd ~/n8n
```
Create docker-compose.yml:
```
nano docker-compose.yml
```
Paste the following content. Remember to change placeholders:

- `your_strong_database_password`
- `n8n.yourdomain.com`
- `America/Toronto` (to your timezone)
- Generate a unique `N8N_ENCRYPTION_KEY` (run `head /dev/urandom | tr -dc A-Za-z0-9_ | head -c 32 ; echo ''` and paste the output).

<!-- end list -->

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:15
    restart: always
    environment:
      POSTGRES_DB: n8n
      POSTGRES_USER: n8nuser
      POSTGRES_PASSWORD: your_strong_database_password # CHANGE THIS!
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    networks:
      - n8n_backend
    healthcheck: # Ensures n8n waits for DB to be ready
      test: ['CMD-SHELL', 'pg_isready -U n8nuser -d n8n']
      interval: 5s
      timeout: 5s
      retries: 5

  n8n:
    image: n8nio/n8n
    restart: always
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_PORT: 5432
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8nuser
      DB_POSTGRESDB_PASSWORD: your_strong_database_password # MUST MATCH ABOVE!
      N8N_HOST: n8n.yourdomain.com # CHANGE THIS to your actual domain
      WEBHOOK_URL: https://n8n.yourdomain.com # CHANGE THIS to your actual domain
      N8N_PROTOCOL: https
      GENERIC_TIMEZONE: America/Toronto # Adjust to your timezone
      N8N_ENCRYPTION_KEY: your_generated_32_char_key # PASTE THE GENERATED KEY HERE
    ports:
      - '127.0.0.1:5678:5678' # Only expose to localhost for Nginx proxy
    volumes:
      - ./n8n_data:/home/node/.n8n
    networks:
      - n8n_backend
    depends_on:
      postgres:
        condition: service_healthy # Wait for DB to be healthy

networks:
  n8n_backend:
    driver: bridge
```

_Save and exit._

Set Permissions for n8n Data Volume:
This ensures the node user inside the container can write to the n8n_data volume.
```
sudo chown -R 1000:1000 n8n_data # 1000:1000 is often the UID/GID of 'node' user in n8n image
```
If n8n_data doesn't exist yet, Docker will create it with root permissions. You might need to run this command after the first docker compose up -d if it fails, or simply create the directory first: mkdir n8n_data && sudo chown -R 1000:1000 n8n_data.
Start n8n and the Database:
```
docker compose up -d
```
Verify Docker Containers:
```
docker ps
```
Both n8n and postgres (or mysql) containers should show Up status. If n8n is still Restarting, check docker logs n8n-n8n-1 for specific errors (e.g., database connection issues, incorrect N8N_ENCRYPTION_KEY).

8. Configure Nginx Reverse Proxy for n8n

Finally, tell Nginx to forward traffic from your domain to the running n8n container.

Edit your Nginx configuration file again:
```
sudo nano /etc/nginx/conf.d/n8n.conf
```
Locate the server block that has listen 443 ssl; and server_name n8n.yourdomain.com;.

Inside this block, replace or add the location / {} block to proxy to n8n:

# ... (other parts of the server block for listen 443 ssl) ...
    location / {
        proxy_pass http://localhost:5678; # n8n Docker container is accessible on localhost:5678
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_buffering off; # Important for long-running workflows
    }
# ... (rest of the server block for listen 443 ssl) ...

Make sure the location /.well-known/acme-challenge/ block is still present in your listen 80; server block (Certbot usually handles this correctly).
Save and exit.

Test Nginx Configuration and Reload:

sudo nginx -t
sudo systemctl reload nginx

Final Verification:
Open your web browser and navigate to https://n8n.yourdomain.com. You should now see the n8n setup screen. Create your first user account, and you're ready to start automating!

Troubleshooting Common Issues

ERR_CONNECTION_REFUSED / No route to host (solved in this guide!):
- Reason: Often a low-level firewall or routing issue on Oracle Cloud instances.
- Fix: The sudo iptables -P INPUT ACCEPT; sudo iptables -P OUTPUT ACCEPT; sudo iptables -P FORWARD ACCEPT; sudo iptables -F followed by iptables-persistent installation and a reboot usually resolves this. Also ensure OCI Security Lists/NSGs and UFW allow ports 80/443.
EACCES: permission denied, open '/home/node/.n8n/config' (n8n container restarting):
- Reason: The n8n container doesn't have write permissions to the mounted n8n_data volume.
- Fix: sudo chown -R 1000:1000 ~/n8n/n8n_data (adjust path if different).
Error getting validation data (Certbot failed):
- Reason: Nginx is not correctly serving the .well-known/acme-challenge/ path on port 80.
- Fix: Ensure Nginx is running, its port 80 block has server_name matching your domain, and the location /.well-known/acme-challenge/ { root /var/www/html; allow all; } block is correctly configured and pointing to a writable directory (/var/www/html should be owned by www-data). Ensure no listen 443 ssl; block is active before Certbot runs.
N8N Restarting (1) (not permissions/database):
- Reason: Check docker logs n8n-n8n-1. This could be database credential mismatch, database not fully initialized, or invalid N8N_ENCRYPTION_KEY.
- Fix: Double-check all environment variables in docker-compose.yml, especially database passwords and the 32-character encryption key. Add a healthcheck for the database service and depends_on: { postgres: { condition: service_healthy } } for n8n.

Backup and Restore Strategy

See also: Comprehensive backup & restore scripts and automation for n8n on Oracle Cloud (GitHub)

Regular backups are crucial for self-hosted n8n!

Stop n8n and database containers:
```
cd ~/n8n
docker compose stop
```
Create a timestamped archive of your data volumes:
```
tar -czvf n8n_backup_$(date +%Y%m%d%H%M%S).tar.gz n8n_data pg_data
```
(Replace pg_data with mysql_data if you used MySQL).

Securely transfer the backup:
Download this .tar.gz file to your local machine or upload it to object storage (e.g., OCI Object Storage, S3, Google Cloud Storage) for off-site redundancy.

# Example to download to your local machine from SSH
# From your LOCAL machine:
# scp -i /path/to/your/my_oracle_key.key ubuntu@<your_instance_public_ip>:~/n8n/n8n_backup_*.tar.gz .

Restart containers:
```
docker compose up -d
```

To Restore:

Stop containers: docker compose stop
Remove existing data (BE CAREFUL!): rm -rf n8n_data pg_data
Transfer your backup archive to ~/n8n/ on the server.
Extract the backup: tar -xzvf n8n_backup_YOUR_TIMESTAMP.tar.gz
Set correct permissions: sudo chown -R 1000:1000 n8n_data pg_data
Start containers: docker compose up -d

Further Enhancements & Considerations

Security: Always use strong, unique passwords for your database and any n8n basic auth. Keep your SSH private key secure.
Monitoring: Implement basic monitoring for your instance's CPU, RAM, and disk usage to ensure n8n runs smoothly.
Updates: Periodically update your n8n Docker image by running docker compose pull n8n followed by docker compose up -d (always backup first!).
Custom Domains: If you have multiple domains, you can configure Nginx to handle more, or use a wildcard certificate if you have one.
Node Versions: For specific n8n versions, use n8nio/n8n:1.X.X in your docker-compose.yml. :latest gets the newest.
Scalability: For very heavy workloads, consider a more powerful OCI instance, or exploring n8n's queue mode and separate workers.

By following this comprehensive guide, you've successfully deployed a powerful n8n automation server on Oracle Cloud's Free Tier, complete with domain mapping, SSL, and robust Docker management! Enjoy building your workflows.

How to Start Your Own MCP Server with n8n

Dale Nguyen — Mon, 30 Jun 2025 04:13:05 +0000

With recent versions of n8n, you can launch your own Model Context Protocol (MCP) server and client directly from the n8n interface—no extra installation, npm packages, or Docker images required. This built-in capability lets you expose n8n workflows as AI-usable tools and connect to other MCP servers, all within your workflow editor.

For those who want to jump straight to the code, I've created a starter template repository on GitHub. It includes all the configurations and scripts mentioned in this guide.

n8n-self-hosted-starter on GitHub

Below is a step-by-step guide to getting started.

What is MCP in n8n?

MCP (Model Context Protocol) is a standard that lets AI agents and other clients discover, call, and interact with tools—like n8n workflows—over a simple HTTP or SSE (Server-Sent Events) interface. In n8n, the MCP Server Trigger node exposes your workflows as MCP tools, while the MCP Client Tool node lets you call tools exposed by other MCP servers.

Prerequisites

n8n version 1.88.0 or higher (for built-in MCP nodes)
A running n8n instance (self-hosted or cloud)

Step 1: Add the MCP Server Trigger Node

Create a New Workflow in n8n.
Add the MCP Server Trigger Node:
- Search for "MCP Server Trigger" in the node panel and add it to your canvas.
- This node will expose a unique URL endpoint (e.g., /mcp/abc123) that MCP clients can call to access your workflow as a tool.
Configure the Node:
- MCP URL Path: Use the default or customize it.
- Authentication: Choose "None" for open access (not recommended for production) or configure authentication (e.g., API key or header).
- Connect Tool Nodes: Attach nodes that represent the tools you want to expose (e.g., HTTP Request, Send Email, custom functions).

Step 2: Expose Your Tools

Native and Custom Tools: You can expose both built-in n8n tools (like Google Calendar, HTTP Request) and your own custom logic as MCP tools.
Workflow as a Tool: Use the "Custom n8n Workflow Tool" node to expose entire workflows as callable MCP tools.

Step 3: Activate and Share

Activate the Workflow: Toggle the workflow to active.
Share the MCP Endpoint: The MCP Server Trigger node displays the endpoint URL. Share this with AI agents or MCP clients that need to call your tools.

Step 4: Connect with the MCP Client Tool Node

Add an MCP Client Tool Node in another workflow or instance.
Configure the Node:
- SSE Endpoint: Enter the MCP Server URL you created earlier.
- Authentication: Set up bearer token or header authentication if required.
- Select Tools: Choose which tools to expose to your AI agent—All, Selected, or All Except.
Use with AI Agents: Connect the MCP Client Tool node to your AI Agent node or other workflow logic. The AI agent can now discover and use your exposed tools dynamically.

Step 5: Test Your MCP Server

You can test your MCP endpoint by using Postman MCP client (with appropriate authentication if enabled):

If configured correctly, n8n will execute the connected tool node and return the result.

Example Use Cases

Expose a Send Email Tool: Trigger an email-sending workflow via MCP.
Integrate with Google Calendar: Let AI agents schedule events by calling your n8n workflow.
Custom Data Processing: Build custom tools (e.g., data cleaning, API aggregation) and expose them for programmatic use.

Security Best Practices

Always use authentication (API key, bearer token, or header) on production MCP endpoints.
Restrict access to your MCP endpoints using firewall rules, Cloudflare Access, or reverse proxy.
Monitor usage and logs for unusual activity.

Summary Table

Node	Purpose
MCP Server Trigger	Exposes n8n tools/workflows as MCP endpoints
MCP Client Tool	Connects to external MCP servers as a client

With these built-in nodes, you can turn n8n into a powerful, AI-ready automation server—no extra installation or configuration required. Just add, connect, activate, and your MCP server is live!

Separate and Protect n8n Webhooks and MCP Endpoints from the Login UI

Dale Nguyen — Sat, 28 Jun 2025 04:41:36 +0000

Self-hosting n8n offers flexibility and privacy, but exposing both the UI and webhooks to the public internet can create security risks. The best practice is to separate your webhook endpoints and MCP (Model Context Protocol) from the n8n login UI, and apply different security measures to each. Here's a practical guide on how to do this using Cloudflare Tunnel, subdomains, and access controls.

For those who want to jump straight to the code, I've created a starter template repository on GitHub. It includes all the configurations and scripts mentioned in this guide.

n8n-self-hosted-starter on GitHub

Why Separate Webhooks from the n8n UI?

Security: The n8n UI (editor/login) should be tightly secured and only accessible to trusted users.
Functionality: Webhooks often need to be accessible publicly for integrations but should not expose your management interface.
Flexibility: You can apply different security policies to each endpoint.

Architecture Overview

Subdomain	Purpose	Exposure	Protection
`n8n.example.com`	n8n UI (Editor/Login)	Private	Cloudflare Access, VPN, or IP allowlist
`webhook.example.com`	Webhook / MCP endpoints	Public (limited)	Token/IP checks, Cloudflare rules

Step 1: Use Separate Subdomains

Configure your DNS and Cloudflare Tunnel to use distinct subdomains for the UI and webhooks. For example:

n8n.example.com → n8n UI
webhook.example.com → n8n webhooks

This separation allows you to route and protect each endpoint differently.

Step 2: Route Traffic Internally with a Reverse Proxy

Note: Using a reverse proxy to separate traffic is optional. Both the UI and webhook subdomains can point to the same n8n instance. You can rely on Cloudflare to provide additional security for the webhook subdomain now or in the future, even if both subdomains route to the same backend.

Use a reverse proxy (like Traefik or Caddy) to internally route requests:

All /webhook/* traffic goes to the n8n webhook handler.
All other traffic (UI, login, MCP) goes to the n8n UI.

Example with Traefik:

# docker-compose.yml (snippet)
services:
  traefik:
    # ...traefik config...
  n8n:
    # ...n8n config...
    environment:
      - WEBHOOK_URL=https://webhook.example.com/
      - N8N_HOST=n8n.example.com

Step 3: Secure the n8n UI with Cloudflare Access

Set up a Cloudflare Access policy for n8n.example.com.
Require login with your identity provider (Google, GitHub, etc.), IP allowlist, or other Zero Trust rules.
This ensures only authorized users can access the n8n editor and login page.

Step 4: Protect Webhook Endpoints

Webhooks often need to be public, but you can still apply protection:

Bearer Token: Require a secret token in the Authorization header.
IP Whitelisting: Restrict allowed source IPs in Cloudflare Firewall Rules.
Cloudflare WAF: Set up custom rules to block suspicious or abusive traffic.
Obscure URLs: n8n generates long, random webhook URLs, but don't rely solely on obscurity.

Example: Cloudflare Tunnel and Access Policy

Cloudflare Tunnel:

Create two tunnels or two hostname routes:
- n8n.example.com → n8n UI (private)
- webhook.example.com → n8n webhooks (public, but with WAF)

Cloudflare Access Policy for UI:

Go to Cloudflare Zero Trust > Access > Applications
Add your UI subdomain
Set a policy: allow only specific emails, groups, or IPs

Cloudflare Firewall Rule for Webhooks:

Go to Security > WAF > Firewall Rules
Add a rule: Allow only specific IPs or require a custom header/token

Summary Table

Endpoint	Subdomain	Exposure	Protection
n8n UI	n8n.example.com	Private	Cloudflare Access, VPN, IP allowlist
Webhooks	webhook.example.com	Public (limited)	Bearer token, IP rules, WAF

Final Thoughts

By separating your n8n UI and webhook endpoints onto different subdomains and applying tailored security controls, you dramatically reduce the risk of unauthorized access to your automation platform. Use Cloudflare Tunnel and Access for the UI, and firewall/token protections for webhooks. For advanced setups, a reverse proxy like Traefik or Caddy can help route and isolate traffic internally.

For a detailed, step-by-step configuration, see guides like dalenguyen's n8n Cloudflare starter and community write-ups on Cloudflare Zero Trust.

Secure automating!

DEV Community: Dale Nguyen

How I Almost Got Pwned - A Tale of Supply Chain Attacks and GitHub Actions Gone Wrong

What Even Is a Supply Chain Attack?

The Smoking Gun: The Lockfile Had Been Tampered With

Enter the "Helpful" Contributor

The GhostAction Campaign: When GitHub Actions Turn Evil

The Attack Vector Breakdown

The Broader Context: The Great NPM Hack of 2025

Red Flags I Should Have Caught Earlier

1. The Contributor Profile

2. The "Mistakes" Were Too Convenient

3. The Timing

What Could Have Gone Wrong

Best Practices: How to Not Get Pwned

1. Lockfile Hygiene

2. CI/CD Security

3. Dependency Management

4. PR Review Guidelines

5. Repository Protection

The Human Element

Lessons Learned

The Silver Lining

References

Mastering Email Rate Limits — A Deep Dive into Resend API and Cloud Run Debugging

The Challenge: When Emails Start Failing

Understanding the Problem

The Initial Architecture

The Root Cause

The Investigation: Debugging Cloud Run Like a Pro

Step 1: Enhanced Logging Strategy

Step 2: Cloud Run Log Analysis Techniques

The Solution: Multi-Layer Rate Limiting Strategy

Layer 1: Proper Error Detection

Layer 2: Intelligent Batch Email Implementation with Auto-Chunking

Layer 3: Architectural Refactoring

Layer 4: Smart Retry Logic

Key Debugging Techniques for Cloud Run

1. Structured Logging

2. Revision Tracking

3. Real-time Monitoring

Results and Performance Impact

Before Optimization

After Optimization

Performance Metrics

Best Practices Learned

1. Email Service Design Patterns

2. Rate Limiting Strategies

Conclusion

Further Reading

SupaWP Storage Filter Hooks - Seamless Supabase Storage Integration for WordPress

What Are SupaWP Storage Filter Hooks?

Prerequisites

The Three Essential Hooks

1. supawp_upload_image_to_supabase

2. supawp_delete_image_from_supabase

3. supawp_get_storage_config

Simple File Upload Implementation

Advanced Implementation Examples

E-commerce Product Gallery

User Document Management

Integration with Popular Plugins

Contact Form 7 Integration

WooCommerce Integration

Security Best Practices

Row Level Security (RLS) Policies

Simple File Validation

Performance Optimization

Batch Upload

Using Your File Upload System

Common Supabase Storage Query Filters

Troubleshooting Common Issues

Troubleshooting

Common Issues

Conclusion

Resources

Learn with Daily Mastery - From AI Generation to Email Delivery

The Challenge: Personalization at Scale

Architecture Overview: From User Preferences to Inbox

1. User Selection Engine

2. AI Content Generation Pipeline

1. `supawp_upload_image_to_supabase`

2. `supawp_delete_image_from_supabase`

3. `supawp_get_storage_config`