DEV Community: lvn1

Monitor websites changes with Firecrawl Observer and Docker

lvn1 — Mon, 22 Sep 2025 02:00:59 +0000

Prerequisites

Linux/Unix.
Docker & Docker compose
Firecrawl Observer
Convex account with production deployment

Deployment Guide

Step 1: Clone, initialse and prepare the environment

git clone https://github.com/mendableai/firecrawl-observer.git
cd firecrawl-observer
npm install
npx convex dev

Open a new terminal

# Here we set up authentication for production
npx @convex-dev/auth --prod

# Set encryption key (REQUIRED - only run if not already set)
npx convex env set ENCRYPTION_KEY "$(openssl rand -base64 32)" --prod

# Verify all required variables are set
npx convex env list --prod

Required variables should include:

SITE_URL ✓ (already set)
JWT_PRIVATE_KEY ✓ (already set)
JWKS ✓ (already set)
ENCRYPTION_KEY (set this now)

Deploy Convex functions to production

npx convex deploy --prod

Step 2: Update Environment File. Replace YOUR_PUBLIC_URL with the domain provided by convex.

# Create/update .env file
cat > .env << 'EOF'
NEXT_PUBLIC_CONVEX_URL=YOUR_PUBLIC_URL
NODE_ENV=production
EOF

Step 3: Update Dockerfile

# Stage 1: Build the application
FROM node:20-slim AS builder
WORKDIR /app

# Declare build-time arguments
ARG NEXT_PUBLIC_CONVEX_URL
ARG NODE_ENV=production

# Set environment variables for build
ENV NEXT_PUBLIC_CONVEX_URL=$NEXT_PUBLIC_CONVEX_URL
ENV NODE_ENV=$NODE_ENV

# Install dependencies
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
    if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
    elif [ -f package-lock.json ]; then npm ci --only=production; \
    elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile --prod; \
    else echo "Lockfile not found." && exit 1; \
    fi

# Copy source and build
COPY . .
RUN npm run build

# Stage 2: Production runtime
FROM node:20-slim AS runner
WORKDIR /app

# Install curl for health checks
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# Create non-root user
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Copy built application with proper ownership
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

# Switch to non-root user
USER nextjs

# Expose port and set environment
EXPOSE 3000
ENV PORT=3000
ENV NODE_ENV=production

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:3000/api/health || exit 1

# Start application
CMD ["npm", "start"]

Step 4: Update docker-compose.yml (Production Ready)

version: '3.8'

services:
  app:
    image: firecrawl-observer-app
    build:
      context: .
      args:
        - NEXT_PUBLIC_CONVEX_URL=${NEXT_PUBLIC_CONVEX_URL}
        - NODE_ENV=production
    restart: unless-stopped
    env_file:
      - .env
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    # Resource limits (adjust based on your server)
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '0.5'
        reservations:
          memory: 512M
          cpus: '0.25'

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "5001:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/nginx.htpasswd:/etc/nginx/conf.d/nginx.htpasswd:ro
    depends_on:
      app:
        condition: service_healthy
    networks:
      - app-network
    # Security and performance
    deploy:
      resources:
        limits:
          memory: 128M
          cpus: '0.1'

networks:
  app-network:
    driver: bridge

# Optional: Volumes for persistence
volumes:
  nginx_cache:

Step 5: Optimize Nginx Configuration

# Update nginx.conf with production optimizations
cat > nginx/nginx.conf << 'EOF'
# Upstream definition
upstream app_backend {
    server app:3000;
    keepalive 32;
}

server {
    listen 80;
    server_name _;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    # Basic auth for all routes
    auth_basic "Restricted Content";
    auth_basic_user_file /etc/nginx/conf.d/nginx.htpasswd;

    # Health check endpoint (bypass auth)
    location /api/health {
        access_log off;
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }

    # Main application
    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;

        # Buffer settings
        proxy_buffering on;
        proxy_buffer_size 8k;
        proxy_buffers 8 8k;

        # Cache static assets
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            proxy_pass http://app_backend;
        }
    }
}
EOF

Step 6: Add Health Check Endpoint

# Create health check API route
mkdir -p src/app/api/health
cat > src/app/api/health/route.ts << 'EOF'
import { NextResponse } from 'next/server';

export async function GET() {
  try {
    // Basic health check - can be expanded to check dependencies
    return NextResponse.json({ 
      status: 'healthy',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
      environment: process.env.NODE_ENV || 'development'
    }, { status: 200 });
  } catch (error) {
    return NextResponse.json({ 
      status: 'unhealthy',
      error: 'Health check failed',
      timestamp: new Date().toISOString()
    }, { status: 503 });
  }
}
EOF

Step 7: Deploy with Zero-Downtime Strategy

# Stop current containers gracefully
docker-compose down

# Clean up old images (optional, saves disk space)
docker image prune -f

# Build and deploy with improved logging
docker-compose up --build -d

# Monitor startup
echo "Waiting for services to start..."
sleep 10

# Check service health
docker-compose ps
docker-compose logs --tail=50 app

Step 8: Verification and Monitoring. Replace SERVER_IP & PORT with yours

# Test health endpoint
curl -I http://SERVER_IP:PORT/api/health

# Test full application (will prompt for basic auth)
curl -I http://SERVER_IP:PORT/

# Monitor logs in real-time
docker-compose logs -f --tail=20

# Check resource usage
docker stats --no-stream

Production Monitoring Script

# Create monitoring script
cat > monitor.sh << 'EOF'
#!/bin/bash
echo "=== Container Status ==="
docker-compose ps

echo -e "\n=== Health Check ==="
curl -s http://localhost:3000/api/health | jq '.' 2>/dev/null || echo "Health check failed"

echo -e "\n=== Resource Usage ==="
docker stats --no-stream --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}"

echo -e "\n=== Recent Logs ==="
docker-compose logs --tail=5 app
EOF

chmod +x monitor.sh

Automated Deployment Script

# Create deployment script for future updates
cat > deploy.sh << 'EOF'
#!/bin/bash
set -e

echo "Starting deployment..."

# Pull latest changes (if using git)
# git pull origin main

# Deploy Convex functions
echo "Deploying Convex functions..."
npx convex deploy --prod

# Build and deploy containers
echo "Building and deploying containers..."
docker-compose down
docker-compose up --build -d

# Wait for health check
echo "Waiting for application to be healthy..."
for i in {1..30}; do
    if curl -f http://localhost:3000/api/health >/dev/null 2>&1; then
        echo "Application is healthy!"
        break
    fi
    echo "Waiting... ($i/30)"
    sleep 10
done

echo "Deployment complete!"
docker-compose ps
EOF

chmod +x deploy.sh

Security Checklist

✅ Non-root containers: App runs as user nextjs
✅ Basic authentication: Password protection via nginx
✅ Security headers: XSS, CSRF, and frame protection
✅ Resource limits: Memory and CPU constraints
✅ Health checks: Automated container health monitoring
✅ Encrypted secrets: API keys stored in Convex cloud
⚠️ HTTPS: Consider adding SSL/TLS for production
⚠️ Firewall: Ensure only necessary ports are open

Troubleshooting

Quick Diagnostics

# Full system check
./monitor.sh

# View all logs
docker-compose logs

# Restart specific service
docker-compose restart app

# Force rebuild
docker-compose up --build --force-recreate -d

Common Issues

Auth errors: Check Convex environment variables with npx convex env list --prod
Build failures: Verify .env file and NEXT_PUBLIC_CONVEX_URL
Health check failures: Check if port 3000 is accessible inside container
nginx issues: Verify nginx.htpasswd file permissions

If you need a cloud server: $200 Digital Ocean Credit

Building a surveillance system with an old Raspberry Pi

lvn1 — Wed, 17 Sep 2025 03:30:57 +0000

This guide walks you through setting up a Raspberry Pi camera with Shinobi Open Source CCTV software. We'll address common hardware, networking, and performance issues to create a stable monitoring solution that actually works on resource constrained devices like the Raspberry Pi 2.

Prerequisites

Hardware: Raspberry Pi (tested on Pi 2), compatible CSI camera module (OV5647), reliable power supply, 32GB+ SD card
Software: Fresh Raspberry Pi OS installation, SSH client, network access
Network: Local network access and basic router configuration knowledge

Step 1: Initial Raspberry Pi Setup

Start with a proper foundation to avoid headaches later.

Basic Configuration

Flash Raspberry Pi OS: Use the official Raspberry Pi Imager for a clean Raspberry Pi OS Lite installation (headless) or with Desktop.
Enable SSH: During imaging, enable SSH in the advanced options, or enable it post-boot with sudo raspi-config.
First Boot: Connect via SSH and update everything:

   sudo apt-get update && sudo apt-get upgrade -y

Camera Hardware Verification

Before installing anything, verify your camera actually works:

libcamera-hello -t 2000

You should see a 2-second preview (on connected display) or the command should complete without "camera not found" errors. If this fails, check your ribbon cable connection - everything else depends on this working.

Step 2: Installing Shinobi

The official installer handles most of the heavy lifting, but you need to know the specific steps.

Run the Official Installer

Switch to root and run installer:

   sudo su
   sh <(curl -s https://cdn.shinobi.video/installers/shinobi-install.sh)

Select "Ubuntu Touchless" when prompted - this works best for Raspberry Pi installations.
Handle IPv6 prompt: If asked about disabling IPv6, choose "Yes" to avoid connectivity issues during installation.

Critical Network Configuration Fix

Here's the part most guides miss: Shinobi will only bind to IPv6 by default, making it inaccessible from other devices on your network.

Edit the configuration file:

   sudo nano /home/Shinobi/conf.json

Add the IP parameter (not "host") at the beginning of the JSON:

   {
      "ip": "192.168.20.15",
      "port": 8080,
      ...

Replace 192.168.20.15 with your actual Pi's IP address.

Restart Shinobi:

   sudo pm2 restart camera

Verify it's working:

   sudo netstat -tlnp | grep :8080

You should see both tcp and tcp6 entries, not just tcp6.

Initial Shinobi Setup

Access the superuser panel: Open http://YOUR_PI_IP:8080/super in your browser.
Default credentials:
- Username: admin@shinobi.video
- Password: admin
Create your admin account through the superuser panel.
Log into main interface: Access http://YOUR_PI_IP:8080 (without /super) using your new credentials.
Change superuser credentials immediately in the Preferences tab for security.

Step 3: Camera Streaming Pipeline

Create a reliable video stream that Shinobi can actually connect to.

Install Required Packages

sudo apt-get install -y gstreamer1.0-tools gstreamer1.0-plugins-good gstreamer1.0-plugins-bad netcat-openbsd

Create the Streaming Script

Create the script file:

   nano /home/first/streamscript

Add this pipeline (optimized for reliability over quality):

   #!/bin/bash

   # Reliable MJPEG stream using software encoding
   # Hardware encoding isn't available on older Pi models

   BOUNDARY="--boundary"

   PIPELINE="gst-launch-1.0 -q libcamerasrc ! video/x-raw,width=320,height=240,framerate=10/1 ! jpegenc ! multipartmux boundary=${BOUNDARY} ! filesink location=/dev/stdout"

   while true; do
     {
       echo -e "HTTP/1.0 200 OK\r\nContent-Type: multipart/x-mixed-replace; boundary=${BOUNDARY}\r\n";
       ${PIPELINE};
     } | nc -l -p 8090
   done

Make it executable:

   chmod +x /home/first/streamscript

Step 4: Background Service Setup

Set up automatic startup and crash recovery using systemd user services.

Create the Service

Create service directory:

   mkdir -p ~/.config/systemd/user/

Create service file:

   nano ~/.config/systemd/user/shinobi-stream.service

Add service configuration:

   [Unit]
   Description=Shinobi Camera Streamer
   Wants=graphical-session.target
   After=graphical-session.target

   [Service]
   ExecStart=/home/first/streamscript
   Restart=always
   RestartSec=5

   [Install]
   WantedBy=default.target

Enable and Start

Run these commands without sudo (important for user services):

systemctl --user daemon-reload
systemctl --user enable shinobi-stream.service
systemctl --user start shinobi-stream.service

Enable Auto-Start on Boot

This crucial step makes the service start even when you're not logged in:

sudo loginctl enable-linger first

Reboot your Pi to test everything starts correctly.

Step 5: Configure Shinobi Monitor

Connect Shinobi to your camera stream.

Add new monitor: Click the + icon in Shinobi dashboard.
Connection settings:
- Input Type: MJPEG
- Full URL Path: http://127.0.0.1:8090
Stream settings:
- Frame Rate: 10
- Width: 320
- Height: 240
Save and test: You should see live video immediately.

Step 6: Performance Tuning

Resource-constrained hardware requires careful balance between quality and performance.

Understanding the Limitations

Older Raspberry Pi models lack hardware video encoders that GStreamer can access. Everything runs on CPU, so optimization is critical.

Tuning Parameters

Adjust the PIPELINE variable in /home/first/streamscript:

For better performance (lower CPU usage):

PIPELINE="gst-launch-1.0 -q libcamerasrc ! video/x-raw,width=160,height=120,framerate=5/1 ! jpegenc quality=50 ! multipartmux boundary=${BOUNDARY} ! filesink location=/dev/stdout"

For better quality (higher CPU usage):

PIPELINE="gst-launch-1.0 -q libcamerasrc ! video/x-raw,width=640,height=480,framerate=15/1 ! jpegenc quality=90 ! multipartmux boundary=${BOUNDARY} ! filesink location=/dev/stdout"

Monitor CPU usage with htop and adjust accordingly.

Troubleshooting Common Issues

"Can't Access from Other Devices"

This is usually the IPv4/IPv6 binding issue:

Check what Shinobi is listening on:

   sudo netstat -tlnp | grep :8080

If you only see tcp6, check your config:

   sudo grep -A3 -B3 '"ip"' /home/Shinobi/conf.json

Make sure you used "ip" not "host" parameter.

"Stream Won't Start"

Check service status:

   systemctl --user status shinobi-stream.service

View service logs:

   journalctl --user -u shinobi-stream.service -f

Test camera directly:

   libcamera-hello -t 2000

"High CPU Usage"

Lower resolution and framerate in your streamscript.
Reduce JPEG quality by adding quality=50 to jpegenc.
Check for multiple streams running accidentally.

Security Considerations

Network Security

Change default Shinobi credentials immediately after setup
Don't expose port 8080 to the internet via router port forwarding
Use strong passwords for all accounts
Consider firewall rules to limit access to specific IP ranges:

  sudo ufw allow from 192.168.0.0/16 to any port 8080

System Security

Change default Pi password if you haven't already
Keep system updated with regular sudo apt update && sudo apt upgrade
Monitor access logs in Shinobi's admin panel

Final Notes

This setup prioritizes reliability over fancy features. You'll have a stable, 24/7 monitoring solution that actually works on older hardware. The key insights that make this work:

Use software encoding - hardware encoders aren't reliably available
Fix the IPv4 binding issue - use "ip" parameter, not "host"
Proper systemd service setup - ensures automatic recovery
Conservative performance settings - prevents crashes under load

Once you have this basic setup running reliably, you can experiment with higher resolutions, multiple cameras, or advanced Shinobi features.

A Chrome Extension That Redesigns Any Website in Seconds - WebImgs

lvn1 — Mon, 18 Aug 2025 01:37:40 +0000

This post is my submission for DEV Education Track: Build Apps with Google AI Studio.

Have you ever stumbled across a promising startup's website, only to find it filled with generic stock photos and placeholder logos? Or maybe you're a developer who's brilliant at backend code but struggles with visual design?

What if there was a way to instantly transform any website's visuals with AI-generated images that actually belong there?

That's how WebImgs was born – a Chrome extension that scans any website, understands its design DNA, and regenerates every visual asset to match perfectly. No more mismatched stock photos or bland placeholders. Just click, scan, and watch a website come to life.

The Magic Behind the Curtain

WebImgs isn't just another AI image generator – it's a design detective. Here's what makes it special:

🔍 Universal Scanning - Detects logos, hero images, banners, icons, and background elements on any website
🎨 Style Aware Generation - Analyzes the website's color scheme, typography, and design patterns
⚡ Real Time Preview - Toggle between original and AI generated images instantly
🎯 Selective Generation - Choose exactly which assets to regenerate
📦 Batch Export - Download all generated assets as a ZIP file
⌨️ Keyboard Shortcuts - Quick generation with Ctrl+Shift+G

Google AI Studio

Here's the core prompt that started it all:

"You are building a Chrome extension that automatically detects and generates ALL visual assets for any website using AI image generation. The extension transforms text-only or placeholder-filled websites into fully designed, visually cohesive sites.

Core functionality: Scan any webpage → Detect all image zones → Categorize assets needed → Generate consistent visuals → Replace/export images.

We'll build this step by step. After each major step, I'll verify completion before proceeding."

Through countless iterations in AI Studio, this evolved into a sophisticated four step process:

Website DNA Analysis - Extract colors, typography, spacing patterns, and overall aesthetic mood
Smart Categorization - Identify whether each image is a logo, hero banner, product shot, or decorative element
Contextual Prompt Generation - Create highly specific prompts for Google's Imagen API
Consistency Enforcement - Ensure all generated assets feel like they belong to the same brand family

The difference between "generate a logo" and "generate a minimalist tech startup logo with navy blue and white color scheme, clean sans-serif typography influence, and modern geometric styling" became the difference between random images and perfect images.

Demo

Here's how WebImgs works in practice:

Step 1: Scan Any Website

Click the extension icon and hit "Scan Page" - WebImgs instantly identifies every image zone on the page, from logos in the header to product shots in the footer.

Step 2: Visual Asset Detection

The extension overlays colored zones showing exactly what it detected:

🟡 Logos and branding elements
🔵 Hero images and banners
🟢 Product and gallery images
🟣 Icons and decorative elements

Step 3: AI Magic Happens

Here's where Google AI Studio's prompt engineering shines. Instead of generic requests, WebImgs generates contextual prompts like:

"Professional fintech logo with navy blue gradient, modern sans-serif influence, clean geometric design, startup aesthetic"
"Hero banner for financial dashboard app, contemporary UI design language, subtle shadows, 1200x400 format"

Step 4: Instant Transformation

The results? Images that look like they were designed by the original team. Toggle between versions to see the dramatic difference – same layout, but now it feels like a real brand.

Step 5: Ready for Production

Export everything as an organized ZIP file. Each asset is properly named and sized, ready to drop into your codebase.

If this gets enough interest, I will release the extension in the Chrome webstore and give out some free credits. I have already secured the domain, just haven't launched the extension yet

Try it yourself: WebImgs Chrome Extension

Under the Hood

Core Technology:

JavaScript & Webpack for the Chrome extension architecture
Google AI Studio for rapid prompt development and testing
Google Vertex AI Imagen API for high-quality image generation
Firebase backend handling authentication and usage credits

The Secret Sauce: WebImgs doesn't just generate random images. It's essentially a design detective that analyzes websites like a human designer would by extracting color palettes, understanding typography choices, recognizing layout patterns, and even inferring business context. This analysis becomes the foundation for creating prompts that generate visually cohesive assets that actually belong.

What I Learned Building This

Three months ago, I was frustrated. Every side project I built looked like it was designed by a developer (because it was). Stock photos felt fake, placeholder logos screamed "temporary," and I couldn't afford a designer for every idea.

That frustration led me down a rabbit hole that changed how I think about AI.

Building WebImgs taught me that the real challenge isn't generating images – it's generating the right images. Here's the tech stack that makes it work:

Try it yourself soon: WebImgs Chrome Extension

Want to see more? Check out the Imagen API pricing to understand the cost structure behind AI-powered design.

How to Update AWS Amplify After Renaming Your GitHub Repository

lvn1 — Thu, 16 Jan 2025 15:48:25 +0000

Here's a helpful guide for developers who need to update their Amplify app after renaming a GitHub repository:

How to Update AWS Amplify After Renaming Your GitHub Repository

When you rename a GitHub repository connected to AWS Amplify, your builds will fail because Amplify can't find the original repository. Here's a guide to fix this.

Prerequisites

Already have an app hosted in AWS Amplify
GitHub account

Step 1: Generate a GitHub Access Token

Go to GitHub.com, sign in. Navigate to Settings → Developer settings → Personal access tokens → Tokens (classic)
Click "Generate new token (classic)". Give it a descriptive name (e.g., "Amplify Repo Access")
Select the repo scope. Click "Generate token" and copy it immediately (you won't see it again)

Step 2: Find Your Amplify App ID

Open the AWS Amplify ConsoleChange it to your region prefix
Select your app, look for the app ID. It starts with 'd' followed by letters and numbers (e.g., d2x3uf5yeo5smt)

Step 3: Update Repository Connection

Open AWS CloudShell in your browser, click on the terminal on this page: Change it to your region prefix or your local terminal
Run the following command, replacing the placeholders:

aws amplify update-app \
  --app-id YOUR_APP_ID \
  --repository https://github.com/USERNAME/NEW-REPO-NAME \
  --access-token YOUR_GITHUB_TOKEN

Step 4: Verify the Connection

Go back to the Amplify Console
Check your app's build history
Trigger a new build to verify the connection works

Security Best Practices

Revoke the GitHub token after successful connection if you won't need it again
Never commit or share your GitHub access token
Use the minimum required scopes for the token

Troubleshooting

If you encounter issues:

Verify your app ID is correct
Ensure the GitHub token has the correct permissions
Check that the repository URL is exact (case-sensitive)
Make sure you have admin access to both Amplify and the GitHub repository

Important Notes

This process doesn't affect your local development environment
Your build settings and environment variables remain unchanged
The GitHub repository history is preserved
If you have multiple branches, they will all be reconnected automatically

By following these steps, you can quickly update your Amplify app to point to your renamed GitHub repository without losing any configuration or deployment history.

Google Authentication in a Chrome Extension with Firebase

lvn1 — Thu, 05 Sep 2024 18:05:59 +0000

We're writing this guide because the official one by Google is missing a few important steps, linked below:

Official Google guide: Authenticate with Firebase in a Chrome extension

Our guide: Dev.to

You can clone the repo here or start from scratch by following the tutorial below.

Github repo

If you find this guide or repo helpful, please star it:)

Prerequisites

This will work on any operating system. For the purposes of this guide we'll be using Mac OS

Google Chrome browser
A Google account (Will be linked to Firebase and Chrome Web Store)
A Chrome web store developer account ($5 one time fee)
Node.js and npm installed (Latest or LTS version)

Step 1: Create the Project Structure

a) Create a new directory for your project:

mkdir firebase-chrome-auth
cd firebase-chrome-auth

b) Create two subdirectories:

mkdir chrome-extension
mkdir firebase-project

Step 2: Set up the Firebase Project

a) Go to the Firebase Console.
b) Click "Add project" and follow the steps to create a new project.
c) Once created, click on "Web" to add a web app to your project.
d) Register your app with a nickname (e.g., "Chrome Extension Auth"). Also select hosting, we'll add it later in command line.
e) Copy the Firebase configuration object. You'll need this later.

const firebaseConfig = {
  apiKey: "example",
  authDomain: "example.firebaseapp.com",
  projectId: "example",
  storageBucket: "example",
  messagingSenderId: "example",
  appId: "example"
};

f) Navigate to the firebase-project directory cd firebase-project
g) Initialize a new npm project npm init -y
h) Create a public dir mkdir public
i) Create an index.html file
firebase-project/public/index.html

<!DOCTYPE html>
<html>
 <head>
  <title>Firebase Auth for Chrome Extension</title>
 </head>
 <body>
  <h1>Firebase Auth for Chrome Extension</h1>
  <script type="module" src="signInWithPopup.js"></script>
 </body>
</html>

j) Create a signInWithPopup.js file
firebase-project/public/signInWithPopup.js

import { initializeApp } from 'firebase/app';
import { getAuth, signInWithPopup, GoogleAuthProvider } from 'firebase/auth';

const firebaseConfig = {
  // Your web app's Firebase configuration
  // Replace with the config you copied from Firebase Console
};

const app = initializeApp(firebaseConfig);
const auth = getAuth();

// This gives you a reference to the parent frame, i.e. the offscreen document.
const PARENT_FRAME = document.location.ancestorOrigins[0];

const PROVIDER = new GoogleAuthProvider();

function sendResponse(result) {
  window.parent.postMessage(JSON.stringify(result), PARENT_FRAME);
}

window.addEventListener('message', function({data}) {
  if (data.initAuth) {
    signInWithPopup(auth, PROVIDER)
      .then(sendResponse)
      .catch(sendResponse);
  }
});

k) Deploy the Firebase project

npm install -g firebase-tools (You might need to run this as sudo)
firebase login
firebase init hosting (Use existing project which we created in the firebase console earlier)

What do you want to use as your public directory? public
Configure as a single-page app (rewrite all urls to /index.html)? Yes
Set up automatic builds and deploys with GitHub? No
File public/index.html already exists. Overwrite? No

firebase deploy

Note the hosting URL provided after deployment. You'll need this for the Chrome extension.

Step 3: Set up the Chrome Extension

a) Navigate to the chrome-extension directory

cd ../chrome-extension
npm init -y
mkdir src
mkdir src/public
mkdir src/background
mkdir src/popup

b) We'll be using webpack to build our extension, you can install it with the following command along with firebase
npm i -D webpack webpack-cli html-webpack-plugin copy-webpack-plugin firebase and create a basic webpack config file
chrome-extension/webpack.config.js

const path = require('path'),
 CopyWebpackPlugin = require('copy-webpack-plugin'),
 HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  entry: {
    background: './src/background/background.js',
    popup: './src/popup/popup.js',
  },
  mode: 'development',
  output: {
    filename: '[name].js',
    path: path.resolve(__dirname, 'dist'),
    clean: true,
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: path.join(__dirname, "src", "popup", "popup.html"),
      filename: "popup.html",
      chunks: ["firebase_config"]
    }),
    new CopyWebpackPlugin({
      patterns: [
        { from: './public/' }
      ],
    }),
  ],
};

In the package.json file, add the script:

"scripts": {
    "release": "webpack --config webpack.config.js && zip -r dist.zip dist/*"
  },

c) Create a manifest.json file
chrome-extension/src/public/manifest.json

{
  "manifest_version": 3,
  "name": "Firebase Auth Extension",
  "version": "1.0",
  "description": "Chrome extension with Firebase Authentication",
  "permissions": [
    "identity",
    "storage",
    "offscreen"
  ],
  "host_permissions": [
    "https://*.firebaseapp.com/*"
  ],
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "action": {
    "default_popup": "popup.html"
  },
  "web_accessible_resources": [
    {
      "resources": ["offscreen.html"],
      "matches": ["<all_urls>"]
    }
  ],
  "oauth2": {
    "client_id": "YOUR-GOOGLE-OAUTH-CLIENT-ID.apps.googleusercontent.com",
    "scopes": [
      "openid", 
      "email", 
      "profile"
    ]
  },
  "key": "-----BEGIN PUBLIC KEY-----\nYOURPUBLICKEY\n-----END PUBLIC KEY-----"
}

d) Create a popup.html file
chrome-extension/src/popup/popup.html

<!DOCTYPE html>
<html>
<head>
    <title>Firebase Auth Extension</title>
</head>
<body>
    <h1>Firebase Auth Extension</h1>
    <div id="userInfo"></div>
    <button id="signInButton">Sign In</button>
    <button id="signOutButton" style="display:none;">Sign Out</button>
    <script src="popup.js"></script>
</body>
</html>

e) Create a popup.js file
chrome-extension/src/popup/popup.js

document.addEventListener('DOMContentLoaded', function() {
    const signInButton = document.getElementById('signInButton');
    const signOutButton = document.getElementById('signOutButton');
    const userInfo = document.getElementById('userInfo');

    function updateUI(user) {
        if (user) {
            userInfo.textContent = `Signed in as: ${user.email}`;
            signInButton.style.display = 'none';
            signOutButton.style.display = 'block';
        } else {
            userInfo.textContent = 'Not signed in';
            signInButton.style.display = 'block';
            signOutButton.style.display = 'none';
        }
    }

    chrome.storage.local.get(['user'], function(result) {
        updateUI(result.user);
    });

    signInButton.addEventListener('click', function() {
        chrome.runtime.sendMessage({action: 'signIn'}, function(response) {
            if (response.user) {
                updateUI(response.user);
            }
        });
    });

    signOutButton.addEventListener('click', function() {
        chrome.runtime.sendMessage({action: 'signOut'}, function() {
            updateUI(null);
        });
    });
});

f) Create a background.js file
chrome-extension/src/background/background.js

const OFFSCREEN_DOCUMENT_PATH = 'offscreen.html';
const FIREBASE_HOSTING_URL = 'https://your-project-id.web.app'; // Replace with your Firebase hosting URL

let creatingOffscreenDocument;

async function hasOffscreenDocument() {
    const matchedClients = await clients.matchAll();
    return matchedClients.some((client) => client.url.endsWith(OFFSCREEN_DOCUMENT_PATH));
}

async function setupOffscreenDocument() {
    if (await hasOffscreenDocument()) return;

    if (creatingOffscreenDocument) {
        await creatingOffscreenDocument;
    } else {
        creatingOffscreenDocument = chrome.offscreen.createDocument({
            url: OFFSCREEN_DOCUMENT_PATH,
            reasons: [chrome.offscreen.Reason.DOM_SCRAPING],
            justification: 'Firebase Authentication'
        });
        await creatingOffscreenDocument;
        creatingOffscreenDocument = null;
    }
}

async function getAuthFromOffscreen() {
    await setupOffscreenDocument();
    return new Promise((resolve, reject) => {
        chrome.runtime.sendMessage({action: 'getAuth', target: 'offscreen'}, (response) => {
            if (chrome.runtime.lastError) {
                reject(chrome.runtime.lastError);
            } else {
                resolve(response);
            }
        });
    });
}

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    if (message.action === 'signIn') {
        getAuthFromOffscreen()
            .then(user => {
                chrome.storage.local.set({user: user}, () => {
                    sendResponse({user: user});
                });
            })
            .catch(error => {
                console.error('Authentication error:', error);
                sendResponse({error: error.message});
            });
        return true; // Indicates we will send a response asynchronously
    } else if (message.action === 'signOut') {
        chrome.storage.local.remove('user', () => {
            sendResponse();
        });
        return true;
    }
});

g) Create an offscreen.html file
chrome-extension/src/public/offscreen.html

<!DOCTYPE html>
<html>
<head>
    <title>Offscreen Document</title>
</head>
<body>
    <script src="offscreen.js"></script>
</body>
</html>

h) Create an offscreen.js file
chrome-extension/src/public/offscreen.js

const FIREBASE_HOSTING_URL = 'https://your-project-id.web.app'; // Replace with your Firebase hosting URL

const iframe = document.createElement('iframe');
iframe.src = FIREBASE_HOSTING_URL;
document.body.appendChild(iframe);

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    if (message.action === 'getAuth' && message.target === 'offscreen') {
        function handleIframeMessage({data}) {
            try {
                const parsedData = JSON.parse(data);
                window.removeEventListener('message', handleIframeMessage);
                sendResponse(parsedData.user);
            } catch (e) {
                console.error('Error parsing iframe message:', e);
            }
        }

        window.addEventListener('message', handleIframeMessage);
        iframe.contentWindow.postMessage({initAuth: true}, FIREBASE_HOSTING_URL);
        return true; // Indicates we will send a response asynchronously
    }
});

Step 4: Create an oauth ID in Google console

a) Open the Google Cloud console It should open on the Credentials page.
b) Click Create credentials > OAuth client ID.
c) Select the Chrome extension application type.
d) Name your OAuth 2.0 client and click Create. You may have to verify your app ownership.
e) Copy your Google OAUTH Client ID into the manifest.json where it says 'YOUR-GOOGLE-OAUTH-CLIENT-ID'

Step 5: Build and Upload your extension to the Chrome Web Store

a) Sign up and pay the one time $5 fee if you want to create and publish extensions in the Chrome Web Store (If you don't do this then you won't be able to get a public key or Extension ID which are needed for this tutorial to work and you will only be able to run your chrome extensions locally)
b) Navigate to the Chrome Web Store Developer Dashboard, click on the Items menu option on the left hand side and then click the '+ New item' on the right side of the page
c) Build and zip your extension using the script we created earlier like so: npm run release

(Note: I use webpack, you can use Vite or anything else you prefer)

d) Upload your Dist.zip file to the Chrome Web Store after clicking the new item button
e) Now you'll have a draft listing, you can fill in the info and save draft or complete it later.
f) You can find your Extension ID at the top of the page on the left side and to get your Public key, click on Package in the menu on the left and then click 'View public key'
g) Copy your public key in between the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines into your manifest where it says 'YOURPUBLICKEY' make sure it's between the two '/n' statements

Step 6: Configure Firebase Authentication

a) In the Firebase Console, go to Authentication > Sign-in method.
b) Enable Google as a sign-in provider.
c) Add your Chrome extension's ID ( Step 5 -> f) ) to the authorized domains list:
The format is: chrome-extension://YOUR_EXTENSION_ID

Step 7: Load and Test the Extension

a) Open Google Chrome and go to chrome://extensions/.
b) Enable "Developer mode" in the top right corner.
c) Click "Load unpacked" and select your chrome-extension directory.
d) Click on the extension icon in Chrome's toolbar to open the popup.
e) Click the "Sign In" button and test the authentication flow.

Troubleshooting

If you encounter CORS issues, ensure your Firebase hosting URL is correctly set in both background.js and offscreen.js.

Make sure your Chrome extension's ID is correctly added to Firebase's authorized domains.

Check the console logs in the popup, background script, and offscreen document for any error messages.

Conclusion

You now have a Chrome extension that uses Firebase Authentication with an offscreen document to handle the sign-in process. This setup allows for secure authentication without exposing sensitive Firebase configuration details directly in the extension code.

Remember to replace placeholder values (like YOUR_EXTENSION_ID, YOUR-CLIENT-ID, YOUR_PUBLIC_KEY, and your-project-id) with your actual values before publishing your extension.

If you found this guide helpful please give us a star and follow us on Dev.to for more guides
Dev.to