We Let an AI Break Our Analytics Platform — Here's Every Bug It Found

Nishikanta Ray — Sun, 10 May 2026 15:20:29 GMT

Github Main- https://github.com/NishikantaRay/InsightTrack

Passmark - https://github.com/NishikantaRay/InsightTrack/tree/main/appsv2/passmark-tests

InsightTrack — 17 pages, dual-database architecture, tested with 52 AI-powered test cases.

Executive Summary

We built InsightTrack — a self-hosted, privacy-first alternative to Google Analytics. After shipping 17 dashboard pages spanning a PostgreSQL + DuckDB dual-database architecture, manual regression testing became the team's biggest bottleneck.

The solution: a 52-test AI-powered test suite built on Passmark, where every assertion is written in plain English and an AI model executes and judges them against the live application at runtime. Zero CSS selectors. Zero data-testid attributes. Zero XPath.

What actually happened on our first real run:

	Number
Tests written	52 (13 spec files, 17 routes)
Tests that ran to completion	11
Tests that passed	8
Tests that exposed real product bugs	3
Tests cut short by API credit exhaustion	38
Bugs found (total, including framework issue)	4
Runtime before credits ran out	~1.5 hours
OpenRouter API cost spent	~$0.45

The honest picture: 11 tests ran, 8 passed, 3 caught real bugs, 38 were aborted when the OpenRouter API key hit its per-key spending limit. The 4 bugs — a vision model integration issue, form validation not surfacing, a registration flow problem, and a duplicate email error — had all been present for months. Manual testing missed every one.

This post documents the full story: the application architecture, how we built the test suite, what every test checks, the actual run results, and each bug with its root cause and fix.

Part 1: The Application — InsightTrack

KPI cards and traffic chart. All analytics reads go directly to DuckDB — 10–100× faster than PostgreSQL for OLAP aggregations.

InsightTrack is a self-hosted web analytics platform. The defining architectural decision is the dual-database write/read split:

Layer	Technology	Role
Tracking script	Custom 2KB JS snippet	Fires events from any website via `POST /api/track`
Write path	PostgreSQL + Express + Node.js 20	Stores raw events, manages auth, handles site config
Sync worker	`sync.js` background process	Incrementally copies PostgreSQL → DuckDB every 30s
Read path	DuckDB	All analytics queries — columnar, fast, zero contention
Frontend	React 18 + Vite 5 + Recharts + Zustand	TypeScript dashboard SPA with Tailwind CSS
Real-time	WebSockets	Live visitor counter and event stream

All 17 Pages Under Test

Route	Page	Purpose
`/` (redirects)	Landing	Marketing page with login/register CTAs
`/login`	Login	Email + password authentication
`/register`	Register	New account creation
`/dashboard`	Main Dashboard	KPI overview, traffic chart, date range picker
`/pages`	Pages	Top pages by views, bounce rate, session time
`/funnels`	Funnels	Multi-step funnel builder + visualisation
`/conversions`	Conversions	Goal conversion rates and trends
`/audience`	Audience	New vs. returning, device + country breakdown
`/content`	Content Analytics	Scroll depth, engagement, content performance
`/acquisition`	Acquisition	Traffic sources, referrers, UTM campaigns
`/performance`	Performance	Core Web Vitals, LCP, CLS, FID
`/realtime`	Realtime	Live visitor count, world map, event stream
`/user-flow`	User Flow	Sankey diagram of navigation paths
`/engagement`	Engagement	Session depth, click patterns, return rate
`/reporting`	Reporting	Scheduled report builder
`/privacy`	Privacy	Consent management, data retention
`/settings`	Settings	Tracking snippet, site manager, alerts
`/profile`	Profile	User info, password management
`/docs`	Docs	In-app documentation

Testing all 17 manually on every release, while simultaneously shipping features, had become unsustainable.

Part 2: Why Passmark

The login page. Five separate tests: valid credentials, wrong password, empty form validation, password toggle, and register link. Each uses natural language — no selectors.

The Maintenance Problem With Traditional E2E Tests

We had been using Playwright. The problem was not writing tests — it was keeping them alive. Every component refactor broke [data-testid="kpi-card"]. Every sidebar redesign required updating all those nth-child selectors. Tests that require constant maintenance stop getting run.

What Passmark Does Differently

Passmark wraps Playwright with an AI layer. You write what you want to verify in plain English. The AI reads the page's accessibility tree — the same structured representation a screen reader or human QA engineer uses — and executes browser actions from that understanding.

Traditional Playwright:

await page.locator('[data-testid="kpi-visitors-card"]').waitFor();
const val = await page.locator('[data-testid="kpi-visitors-value"]').textContent();
expect(Number(val)).toBeGreaterThanOrEqual(0);

Passmark:

await runSteps({
  page,
  userFlow: 'Dashboard KPI check',
  steps: [
    { description: 'Navigate to /dashboard' },
    { description: 'Wait until a Dashboard heading is visible',
      waitUntil: 'A Dashboard heading is visible on the page' },
  ],
  assertions: [
    { assertion: 'A "Unique Visitors" or "Visitors" metric card is visible' },
    { assertion: 'A "Pageviews" metric card is visible' },
    { assertion: 'A "Bounce Rate" metric card is visible' },
  ],
  test, expect,
});

During this project we renamed "Unique Visitors" to "Total Visitors" in the UI. The Passmark assertion — 'A "Unique Visitors" or "Visitors" metric card is visible' — matched the new label and kept passing. The old Playwright test would have failed and required a code change.

The principle: Assertions that describe intent outlive assertions that describe implementation. That's the difference between a test suite that stays green and one that becomes a maintenance tax.

How the AI Pipeline Works

Every runSteps() call runs this sequence:

1. DOM snapshot
   Passmark captures the page accessibility tree as structured text:
   headings, buttons, inputs, links — their roles, labels, text content.
   No screenshot. Pure semantic structure.

2. Step execution
   Each step description goes to the AI with the current DOM snapshot.
   The AI returns browser tool calls:
     browser_navigate("/settings")
     browser_click("Copy button")
     browser_fill("email input", "user@example.com")
   Playwright executes these against a real Chromium browser.

3. waitUntil polling
   If a step has a waitUntil condition, Passmark re-snapshots the DOM
   every 2 seconds and asks the AI: "Is this condition met?"
   It polls for up to 2 minutes before timing out.

4. Assertion judging (3 models)
   Each assertion is sent to a primary judge, then a secondary judge.
   If they disagree, an arbiter breaks the tie.
   Every assertion returns a boolean + written reasoning.

Part 3: How We Built the Test Suite

Repository Structure

appsv2/passmark-tests/
├── .env                        ← OPENROUTER_API_KEY, PW_BASE_URL, API_BASE_URL
├── playwright.config.ts        ← Passmark model config + Playwright settings
├── helpers/
│   └── auth.ts                 ← createTestSession() + injectAuth()
└── tests/
    ├── auth/
    │   ├── login.spec.ts        ← 5 tests
    │   └── register.spec.ts     ← 4 tests
    ├── public/
    │   └── landing.spec.ts      ← 3 tests
    ├── dashboard/
    │   ├── dashboard.spec.ts    ← 6 tests
    │   ├── analytics-sections.spec.ts  ← 9 tests
    │   ├── realtime.spec.ts     ← 4 tests
    │   ├── funnels.spec.ts      ← 3 tests
    │   ├── pages.spec.ts        ← 3 tests
    │   ├── settings.spec.ts     ← 4 tests
    │   ├── profile.spec.ts      ← 2 tests
    │   └── docs.spec.ts         ← 2 tests
    ├── navigation.spec.ts       ← 5 tests
    └── theme.spec.ts            ← 2 tests

52 tests. 13 spec files. 17 routes covered.

`playwright.config.ts` — The Configuration That Drives Everything

import dotenv from 'dotenv';
import { defineConfig, devices } from '@playwright/test';
import { configure } from 'passmark';

dotenv.config();

// Route all AI calls through OpenRouter
configure({
  ai: {
    gateway: 'openrouter',
    models: {
      stepExecution:      'openai/gpt-4.1-mini',  // browser tool calls
      userFlowLow:        'openai/gpt-4.1-mini',  // simple flow planning
      userFlowHigh:       'openai/gpt-4.1-mini',  // complex flow planning
      assertionPrimary:   'openai/gpt-4.1-mini',  // assertion judge #1
      assertionSecondary: 'openai/gpt-4.1-mini',  // assertion judge #2
      assertionArbiter:   'openai/gpt-4.1-mini',  // tiebreaker
      utility:            'openai/gpt-4.1-mini',  // DOM condition checks
    },
  },
});

export default defineConfig({
  testDir: './tests',
  timeout: 180_000,       // global ceiling
  workers: 1,             // serial — prevents auth race conditions
  retries: 1,             // one automatic retry on failure

  use: {
    baseURL: process.env.PW_BASE_URL || 'http://localhost:4173',
    headless: true,
    viewport: { width: 1280, height: 720 },  // standard reference viewport
    actionTimeout: 10_000,
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],

  reporter: [
    ['list'],
    ['html', { outputFolder: 'playwright-report', open: 'never' }],
  ],
});

Key decisions explained:

workers: 1 — Serial execution prevents test users racing to register with the same email at the same timestamp
retries: 1 — On retry, Passmark performs a fully fresh AI run, making it genuinely self-healing for transient DOM issues
viewport: 1280×720 — The standard reference viewport. Critical: many developers use 1440p+ monitors and never see layout issues that only manifest at smaller widths. This viewport mismatch is exactly how Bug 3 was caught.
Per-test test.setTimeout(240_000) — The global timeout: 180_000 is a ceiling, but individual tests override it. With retries: 1, a 240_000 timeout means up to 8 minutes maximum before permanent failure. With AI models averaging 8–15 seconds per tool call, this is the minimum safe budget.

`.env` Configuration

OPENROUTER_API_KEY=sk-or-v1-...
PW_BASE_URL=http://localhost:4173
API_BASE_URL=http://localhost:3001
TEST_USER_EMAIL=passmark-tester@insighttrack.local
TEST_USER_PASSWORD=Passmark$ecure123

Before running the full suite: Check your credit balance:
curl https://openrouter.ai/api/v1/auth/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"
A full 52-test run costs approximately $0.50–0.60 with gpt-4.1-mini. Running out of credits mid-suite produces 403 errors that look like test failures but are infrastructure failures.

The Auth Helper — The Pattern That Makes Every Dashboard Test Fast

Testing auth-protected routes without solving auth efficiently is the biggest time sink in dashboard testing. If every test navigates the login form via AI, you waste 45–60 seconds per test on flow that isn't what you're testing, and you create a hard dependency: if login breaks, every other test breaks.

The solution: inject JWT + siteId into localStorage via page.addInitScript before React boots. By the time Zustand hydrates, the auth state is already populated.

// helpers/auth.ts

export interface AuthSession {
  token: string;
  siteId: string;
  email: string;
  password: string;
}

/**
 * Creates a test user and seeds a site via the REST API.
 * Idempotent — if the user already exists (409), falls back to login.
 * Takes ~200ms. No browser interaction required.
 */
export async function createTestSession(
  request: APIRequestContext,
  suffix: string,
): Promise {
  const email = process.env.TEST_USER_EMAIL
    ?? `passmark-${suffix}@insighttrack.local`;
  const password = process.env.TEST_USER_PASSWORD ?? 'Passmark$ecure123';

  let token: string;

  try {
    const reg = await request.post(`${API_BASE}/api/auth/register`, {
      data: { name: 'Passmark Tester', email, password },
    });
    ({ token } = await reg.json());
  } catch {
    // User already exists from a previous run — log in instead
    const login = await request.post(`${API_BASE}/api/auth/login`, {
      data: { email, password },
    });
    ({ token } = await login.json());
  }

  // Create a site so the SiteGate doesn't redirect to /onboarding
  const site = await request.post(`${API_BASE}/api/sites`, {
    headers: { Authorization: `Bearer ${token}` },
    data: { name: 'Passmark Test Site', domain: 'passmark.test' },
  });
  const { id: siteId } = await site.json();

  return { token, siteId, email, password };
}

/**
 * Injects auth state into localStorage before page scripts execute.
 * React + Zustand boot with a valid token already in place.
 * No login redirect. No onboarding wizard.
 */
export async function injectAuth(page: Page, session: AuthSession): Promise {
  await page.addInitScript(({ token, siteId }) => {
    localStorage.setItem('analytics-auth', JSON.stringify({
      state: { token, isAuthenticated: true },
      version: 0,
    }));
    localStorage.setItem('analytics-site-id', siteId);
  }, { token: session.token, siteId: session.siteId });
}

Every protected-route test uses this two-liner pattern:

let _session: AuthSession;

test.beforeAll(async ({ request }) => {
  _session = await createTestSession(request, 'dashboard');
});

test.beforeEach(async ({ page }) => {
  await injectAuth(page, _session);
  // Page loads already authenticated — AI budget goes to feature testing
});

Mixing Raw Playwright With AI Steps

Not everything needs AI. Some assertions are faster, cheaper, and more reliable with raw Playwright — particularly anything that reads DOM attributes the accessibility tree doesn't expose.

Dark mode test (raw Playwright, not AI):

test('dark mode is supported on the dashboard', async ({ page }) => {
  test.setTimeout(240_000);
  await page.goto('/');
  await page.waitForSelector('h1, h2', { timeout: 15_000 });

  const toggle = page.getByRole('button', { name: 'Toggle theme' });
  await expect(toggle).toBeVisible({ timeout: 10_000 });

  const currentTheme = await page.evaluate(
    () => localStorage.getItem('analytics-theme') ?? 'light'
  );
  await toggle.click();

  if (currentTheme === 'light') {
    // App.jsx wraps everything in  — not document.html
    await expect(page.locator('div.dark').first()).toBeVisible({ timeout: 5_000 });
  } else {
    await expect(page.locator('div.dark').first()).not.toBeVisible({ timeout: 5_000 });
  }
});

This test is 100% raw Playwright. The AI would spend 30–60 seconds finding the toggle button and interpreting the DOM change. Raw Playwright does it in 2 seconds. Use the right tool for each job.

Part 4: All 52 Tests — What Each One Checks

Every link in this sidebar has at least one test. The full suite covers auth, public pages, all 9 analytics sections, navigation, and theming.

`tests/auth/login.spec.ts` — 5 Tests

#	Test	What It Checks	Approach
1	valid credentials redirect to dashboard	Full login flow with real credentials; asserts URL leaves `/login` and dashboard or onboarding is visible	AI
2	wrong password shows an error message	Submits wrong credentials; asserts error toast appears	AI
3	empty form shows validation messages	Attempts submit without filling form; asserts validation error	AI
4	password show/hide toggle works	Raw Playwright: assert `type="password"` → click toggle → assert `type="text"`	Raw Playwright
5	register link navigates to /register	Clicks "Create account" link; asserts URL becomes `/register`	AI

`tests/auth/register.spec.ts` — 4 Tests

#	Test	What It Checks
1	successful registration redirects away from /register	Full registration with unique email; asserts URL leaves `/register`
2	duplicate email shows an error	Registers same email twice; asserts error on second attempt
3	short password shows validation error	Submits 3-character password; asserts validation error
4	login link navigates to /login	Clicks "Already have an account?" link; asserts URL becomes `/login`

`tests/public/landing.spec.ts` — 3 Tests

#	Test	What It Checks
1	hero section is visible with CTA buttons	Landing page without auth; asserts hero heading and "Get Started" / "Sign In" CTAs
2	navigating from landing → register → login works	Full navigation chain: landing → click Get Started → register page → click Sign In → login page
3	dark mode toggle switches the theme	Clicks theme toggle on landing; asserts dark scheme applies

`tests/dashboard/dashboard.spec.ts` — 6 Tests

The main analytics overview — first screen after login.

#	Test	What It Checks
1	KPI metric cards are visible	Asserts Visitors, Pageviews, Bounce Rate, Avg. Session Duration cards are all present
2	traffic chart renders without errors	Scrolls to chart area; asserts at least one chart or "no data" placeholder is visible
3	refresh button triggers data reload	Clicks refresh; waits for reload; asserts no error message
4	PageNote info box can be expanded and collapsed	Clicks "What is the Dashboard?" accordion; asserts it toggles ← Bug 4 trigger
5	sidebar navigation links are visible	Asserts sidebar with InsightTrack logo, Pages, Realtime, Settings links
6	dark mode is supported on the dashboard	Raw Playwright: theme toggle → `div.dark` assertion

`tests/dashboard/analytics-sections.spec.ts` — 9 Tests

One smoke test per analytics section. Each follows the same pattern: navigate → wait for heading → assert primary content area or placeholder is visible.

Section	Route	Primary Assertion
Conversions	`/conversions`	"Conversions" heading + conversion metrics or empty state
Audience	`/audience`	"Audience" heading + New vs. Returning breakdown
Content	`/content`	"Content Analytics" heading + content metrics
Acquisition	`/acquisition`	"Acquisition" heading + traffic source breakdown
Performance	`/performance`	"Performance" heading + Core Web Vitals or metrics
User Flow	`/user-flow`	"User Flow" heading + flow visualisation or placeholder
Engagement	`/engagement`	"Engagement" heading + engagement metrics
Reporting	`/reporting`	"Reporting" heading + report controls
Privacy	`/privacy`	"Privacy" heading + consent / data retention controls

These are intentionally broad — they confirm each page loads and renders its primary UI, not that specific numbers are correct.

`tests/dashboard/realtime.spec.ts` — 4 Tests

The Realtime page. WebSocket-powered live data. The visitor counter exposed a race condition that only manifests at >200ms WS connection latency.

#	Test	What It Checks
1	active visitor counter is displayed	Asserts a live active visitor count is visible ← Bug 2 trigger
2	live visitor map section exists	Asserts world map or "No geographic data" placeholder
3	live event stream section is present	Asserts event feed or recent page loads are visible
4	active ping animation is visible	Asserts pulsing indicator near the counter

`tests/dashboard/pages.spec.ts` — 3 Tests

#	Test	What It Checks
1	Pages heading and data table render correctly	Asserts "Pages" heading and data table or empty-state
2	PageNote info box is present	Asserts informational note for the Pages section
3	date range or filter controls exist	Asserts date picker or filter controls visible

`tests/dashboard/funnels.spec.ts` — 3 Tests

#	Test	What It Checks
1	Funnels page loads with builder UI	Asserts "Funnels" heading and funnel builder interface
2	user can add a funnel step	Clicks "Add Step"; asserts step input or confirmation appears
3	funnel chart section is present	Asserts chart area or "no funnels" placeholder

`tests/dashboard/settings.spec.ts` — 4 Tests

Settings page at 1280×720. The Copy button for the tracking snippet was off-screen due to overflow: hidden. Bug existed for months. Test caught it immediately.

# Test What It Checks

1 Settings page loads with tab navigation Asserts Settings heading and tab interface (General, Tracking, etc.)

tracking code snippet is shown

Asserts

Notice that we still include default text so the page does not appear empty before JavaScript loads.

Step 2: Create Translation Files

Create a language folder.

project
│
├── index.html
├── script.js
│
└── lang
    ├── en.json
    └── fr.json

English Translation

lang/en.json

{
  "title": "Welcome",
  "description": "This is a demo application.",
  "login": "Login"
}

French Translation

lang/fr.json

{
  "title": "Bienvenue",
  "description": "Ceci est une application de démonstration.",
  "login": "Connexion"
}

Each key must match the data-i18n value.

Step 3: JavaScript Translation Engine

Now we create a function that loads the selected language and updates the page.

script.js

async function loadLanguage(lang) {

  const response = await fetch(`./lang/${lang}.json`);

  const translations = await response.json();

  const elements = document.querySelectorAll("[data-i18n]");

  elements.forEach(element => {

    const key = element.getAttribute("data-i18n");

    if (translations[key]) {
      element.textContent = translations[key];
    }

  });

}

This script does three things:

Loads the translation JSON file
Finds all elements with data-i18n
Replaces the text with the translated value

Step 4: Language Switching

We can switch languages using buttons.

When clicked:

loadLanguage("en") → loads English
loadLanguage("fr") → loads French

The page text updates instantly.

Step 5: Saving Language Preference

In real applications we usually save the user's preferred language.

We can use localStorage.

Example:

async function loadLanguage(lang) {

  localStorage.setItem("language", lang);

  const response = await fetch(`./lang/${lang}.json`);

  const translations = await response.json();

  document.querySelectorAll("[data-i18n]").forEach(el => {

    const key = el.dataset.i18n;

    if (translations[key]) {
      el.textContent = translations[key];
    }

  });

}

Auto Load Language on Page Start

window.addEventListener("DOMContentLoaded", () => {

  const savedLang = localStorage.getItem("language") || "en";

  loadLanguage(savedLang);

});

Now the site remembers the user's language.

Step 6: Translating Attributes

Sometimes we need to translate attributes like:

placeholders
titles
aria labels

Example:

Translation file:

{
  "search": "Search..."
}

JavaScript:

document.querySelectorAll("[data-i18n-placeholder]").forEach(el => {

  const key = el.getAttribute("data-i18n-placeholder");

  el.placeholder = translations[key];

});

Performance Considerations

For small projects this approach is perfect, but large applications may require optimization.

Possible improvements:

Lazy loading languages

Load only the language being used.

Caching translations

Store translations in memory to avoid repeated network requests.

Preloading common languages

Load frequently used languages on startup.

Advantages of the `data-i18n` Approach

Simple implementation

No frameworks required.

Clean HTML

Translation logic stays separate from markup.

Lightweight

Only a few lines of JavaScript.

Easy to maintain

Translators can edit JSON files without touching code.

Flexible

Works with any frontend stack.

Limitations

Although useful, the data-i18n approach has some limitations.

No pluralization rules

Languages like Russian or Arabic require complex plural logic.

No date or number formatting

Formatting currencies and dates requires additional libraries.

No nested translations

Large projects often require structured translations.

When to Use a Full i18n Library

If your project becomes large, consider using a professional library like:

i18next
react-i18next
vue-i18n

These tools support:

pluralization
date formatting
dynamic translations
server side rendering
language detection

Example Use Cases

The data-i18n pattern works well for:

Landing pages
SaaS dashboards
Documentation sites
Small web apps
Portfolio websites
MVP products

For example, if you build a multi-language SaaS dashboard, you can translate UI labels like:

Dashboard
Analytics
Settings
Logout

without changing the layout.

Conclusion

Internationalization is an important feature for modern web applications. Even small projects benefit from supporting multiple languages.

The data-i18n approach provides a lightweight and flexible solution for implementing translations using simple HTML attributes and JSON files.

With just a small amount of JavaScript, you can create a system that:

dynamically switches languages
loads translations from JSON files
remembers user preferences
keeps HTML clean and maintainable

As your application grows, you can later migrate to advanced libraries while keeping the same translation structure.

Tauri vs Electron: The Complete Developer’s Guide (2026)

Nishikanta Ray — Mon, 26 Jan 2026 16:58:12 GMT

If you're building a desktop app today, you're probably choosing between Electron and Tauri.

Electron has been the default for years. It powers apps like VS Code, Slack, Discord, and Notion. But Tauri has rapidly emerged as a serious alternative — promising tiny bundle sizes, better performance, and stronger security.

So which one should you use?

This guide walks you through what Tauri is, how it compares to Electron, real architectural differences, performance tradeoffs, security models, and even how to migrate.

What is Tauri?

Tauri is an open-source framework for building lightweight, secure desktop applications using:

Frontend: HTML, CSS, JavaScript (React, Vue, Svelte, etc.)
Backend: Rust
Rendering Engine: The system’s native WebView (not bundled)

Instead of shipping a full browser like Electron does, Tauri uses the WebView already installed on the user’s OS.

Core Idea

Use the OS’s browser engine + Rust for native power = tiny, fast apps

Key Characteristics

Feature	Tauri
Backend	Rust (compiled, fast, memory-safe)
Frontend	Any web framework
WebView	System WebView (WebKit / Edge / WebKitGTK)
Bundle Size	Very small (single-digit MBs)
Security	Capability-based permission system
Mobile	Yes (iOS & Android in v2)

What is Electron?

Electron is a framework for building desktop apps using:

Frontend: HTML/CSS/JS
Backend: Node.js
Rendering Engine: Bundled Chromium

Electron combines Chromium + Node.js into a desktop runtime.

Core Idea

Ship a full browser + Node runtime so your app behaves the same everywhere.

Key Characteristics

Feature	Electron
Backend	Node.js
Frontend	Any web framework
WebView	Bundled Chromium
Bundle Size	Large (100–200MB typical)
Security	Process isolation + developer configuration
Mobile	No

The Fundamental Architectural Difference

This one design choice changes everything:

Aspect	Tauri	Electron
Browser Engine	Uses system WebView	Bundles Chromium
Backend Runtime	Rust	Node.js
Process Model	Lightweight Rust host + WebView	Main process + renderer processes
Binary Size	3–10 MB	150–200 MB
RAM Usage (idle)	30–50 MB	150–300 MB
Startup Speed	Very fast	Slower due to Chromium load

What This Means in Practice

Tauri = smaller + faster + leaner
Electron = heavier + more consistent environment

Electron ships everything it needs. Tauri reuses what the OS already has.

Developer Experience: How Apps Are Structured

Both frameworks let you use your favorite frontend stack. The difference is in the backend.

Tauri Structure

my-tauri-app/
├── src/              # Frontend (React/Vue/etc.)
└── src-tauri/        # Rust backend

You write native functionality as Rust commands and call them from the frontend using Tauri’s IPC system.

Electron Structure

my-electron-app/
└── src/
    ├── main.ts       # Node.js main process
    ├── preload.ts    # Secure bridge
    └── renderer.ts   # Frontend

Electron uses:

Main process (Node.js, full system access)
Renderer process (your UI)
Preload scripts as a bridge

IPC: Talking Between Frontend and Backend

Tauri Example

Rust backend

#[tauri::command]
fn greet(name: &str) -> String {
    format!("Hello, {}! Welcome to Tauri.", name)
}

Frontend

import { invoke } from '@tauri-apps/api/core';

const msg = await invoke('greet', { name: 'Nishikanta' });

Clean. Direct. No preload script needed.

Electron Example

Main process

ipcMain.handle('greet', async (_, name: string) => {
  return `Hello, ${name}! Welcome to Electron.`;
});

Preload

contextBridge.exposeInMainWorld('api', {
  greet: (name: string) => ipcRenderer.invoke('greet', name),
});

Renderer

const msg = await window.api.greet('Nishikanta');

More moving parts, but very flexible.

Performance: Real-World Differences

Let’s look at what actually matters to users.

Bundle Size

Framework	App Size
Tauri	~5 MB
Electron	~150–200 MB

If users must download your app, this is huge.

Memory Usage

Scenario	Tauri	Electron
Idle	~45 MB	~180 MB
Working	~85 MB	~320 MB
Heavy task	~120 MB	~520 MB

Electron pays the cost of running Chromium. Tauri doesn’t.

Startup Speed

Framework	Cold Start
Tauri	< 1 second
Electron	2–5 seconds

Tauri apps feel closer to native apps at launch.

Processing Speed

Rust vs Node.js also matters for heavy workloads.

Task	Tauri (Rust)	Electron (Node)
Large file processing	Faster	Slower
CPU-heavy tasks	Strong	Moderate

If your app does video processing, encryption, or heavy data transforms, Rust is a big advantage.

Security Model

This is one of the most important differences.

Tauri: Capability-Based Security

Tauri v2 requires you to explicitly grant permissions.

Example:

{
  "permissions": [
    "fs:allow-read",
    "shell:allow-spawn"
  ]
}

You can even scope access to specific folders.

Default = locked down.
You opt into power.

Electron: Process Isolation

Electron security depends on configuration.

Best practices:

webPreferences: {
  nodeIntegration: false,
  contextIsolation: true,
  sandbox: true,
  preload: 'preload.js'
}

Default = permissive.
You must lock it down yourself.

Ecosystem & Maturity

Area	Tauri	Electron
Age	Young (modern)	Mature (since 2013)
NPM ecosystem	Smaller	Massive
Learning curve	Rust required	JS-only possible
Documentation volume	Growing	Extensive

Electron wins in sheer ecosystem size.
Tauri wins in modern architecture and efficiency.

When Should You Choose Tauri?

Tauri shines when:

✅ App size matters
✅ Performance matters
✅ Security matters
✅ You’re okay using Rust
✅ You want desktop + mobile from one codebase

Perfect for:

Developer tools
System utilities
Media processing apps
Privacy/security-focused software

When Should You Choose Electron?

Electron is better when:

✅ Your team is JS-only
✅ You depend on Node-native libraries
✅ You want maximum community support
✅ Rapid prototyping is the goal
✅ You need guaranteed browser consistency

Perfect for:

Internal tools
SaaS desktop wrappers
Startup MVPs
Teams without Rust experience

Migration: Electron → Tauri

Good news: your frontend can stay the same.

You mainly replace:

Electron main process → Rust commands
Preload bridge → invoke() calls

Example:

Electron

ipcMain.handle('process-data', async (_, data) => {
  return heavyProcessing(data);
});

Tauri

#[tauri::command]
async fn process_data(data: String) -> Result<String, String> {
    Ok(heavy_processing(&data))
}

Frontend change:

const result = await invoke('process_data', { data });

That’s the core migration pattern.

Final Verdict

There is no universal winner — only the right tool for your constraints.

If you want…	Choose
Tiny, fast, efficient apps	Tauri
Maximum ecosystem & JS-only	Electron
Strong built-in security model	Tauri
Easiest onboarding for web devs	Electron

Tauri feels like the future of lightweight desktop apps.
Electron remains the king of ecosystem and maturity.

And the best part? Since both use web frontends, you’re never completely locked in.

Production-Grade Prompting with the Anthropic API

Nishikanta Ray — Sat, 17 Jan 2026 16:39:20 GMT

Concepts, Parameters, Streaming, Caching, and a Real Enterprise Example

Prompting in Anthropic (Claude) is not just about writing good instructions.
In production systems, prompts behave more like specifications than conversations.

This article explains how prompting actually works in Anthropic, how to design reliable and compliant prompts, and how to use JavaScript to build real systems—ending with a production-grade sentiment analysis prompt.

1. How Anthropic Prompting Really Works

Anthropic uses a message-based API.
Each request contains the entire conversation state.

Claude does not remember anything between API calls.

Mental model

You → send full conversation
Claude → continues from that context

Every request must include:

Who the assistant is
What rules apply
What the user just said
Any images or documents

2. Messages and Roles (Core Concept)

Anthropic uses three roles:

Role	Purpose
`system`	Hard rules, behavior, constraints
`user`	Input data or tasks
`assistant`	Previous model replies (conversation priming)

Example

messages: [
  { role: "user", content: "Hello! Only speak Spanish." },
  { role: "assistant", content: "Hola!" },
  { role: "user", content: "How are you?" }
]

Claude will answer in Spanish because:

Conversation history establishes the rule
Claude prioritizes consistency

Production rule

Put non-negotiable rules in system, not in conversation history.

3. System vs User Instructions (Why It Matters)

Instruction Type	Reliability
System	Strong, persistent
User	Soft, overrideable
Assistant	Priming only

Production-safe example

system: "You must respond only in Spanish."

This survives:

Long conversations
Truncated history
User attempts to override

4. Temperature: Controlling Randomness

Temperature controls how predictable Claude’s word choices are.

It does not control intelligence.

Temperature	Behavior	Use case
0.0–0.2	Deterministic	JSON, analytics
0.3–0.5	Controlled	Summaries
0.6–0.8	Creative	Writing
0.9+	Unstable	Rarely useful

Example

temperature: 0.0

Use this when:

Output must be parsed
Compliance matters
Decisions depend on correctness

5. stop_sequences: When the Model Must Stop

stop_sequences tells Claude when to stop generating.

stop_sequences: ["\nUser:"]

Claude stops immediately when it reaches that string.

Common uses

Prevent role leakage
End JSON cleanly
Stop agent loops

Key rule

Stop sequences are guards, not fixes for bad prompts.

6. Streaming Responses (Real-Time Output)

Streaming lets Claude send text incrementally.

with client.messages.stream(...) as stream:
  for text in stream.text_stream:
    print(text)

Why streaming exists

Faster perceived response
Better UX
Long outputs

When NOT to stream

JSON APIs
Tool calls
Strict schema validation

Production pattern

let buffer = "";

for (const chunk of stream.text_stream) {
  buffer += chunk;
  process.stdout.write(chunk);
}

// buffer now contains the full response

7. Multimodal Prompting (Images + Text)

Anthropic allows image + text together.

{
  role: "user",
  content: [
    { type: "image", source: {...} },
    { type: "text", text: "Count the containers." }
  ]
}

Rules

content must be an array
Image first, instruction second
Images only in user role

8. Prompt Caching and `cache_control`

Anthropic optimizes performance by caching repeated prompt prefixes.

This is good for:

System prompts
Templates
Policies

But dangerous for:

User data
Transcripts
Images
PII

9. `cache_control: { type: "ephemeral" }`

"cache_control": { "type": "ephemeral" }

This means:

Use this content once. Do not cache. Do not reuse. Do not persist.

When to use it

Data	Ephemeral
User input	✅
Call transcripts	✅
Images	✅
Customer feedback	✅

Why it matters

Prevents data reuse
Improves compliance posture
Reduces audit risk

10. JavaScript Example: Safe Prompt with Ephemeral Data

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY
});

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 200,
  temperature: 0.0,
  system: "You are a deterministic analysis engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "The service was slow and frustrating.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

11. What Makes a Prompt Production-Grade

A production prompt has:

Clear role definition
Explicit constraints
Defined output format
Fail-closed behavior
Low temperature
No exposed reasoning
Safe handling of sensitive data

Good prompts are specifications, not conversations.

12. Production-Grade Sentiment Analysis Prompt

This prompt follows all best practices discussed above.

Prompt

Analyze the sentiment of the following customer message.

Rules:
- Classify sentiment as POSITIVE, NEGATIVE, or NEUTRAL
- Do not include personal data
- Do not infer intent beyond the text
- Limit text fields to 100 characters

Output:
Return ONLY valid JSON.
No explanations.

Schema:
{
  "sentiment": "POSITIVE | NEGATIVE | NEUTRAL",
  "confidence": 0.0-1.0,
  "summary": "string"
}

If sentiment cannot be determined, return:
{
  "sentiment": "NEUTRAL",
  "confidence": 0.0,
  "summary": "Insufficient data"
}

13. Sentiment Analysis: Full JavaScript Example

const response = await client.messages.create({
  model: "claude-3-5-sonnet-20240620",
  max_tokens: 150,
  temperature: 0.0,
  system: "You are a strict sentiment classification engine.",
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Support was slow and unhelpful.",
          cache_control: { type: "ephemeral" }
        }
      ]
    }
  ]
});

console.log(response.content[0].text);

14. Final Takeaway

Anthropic prompting works best when you treat prompts like contracts: explicit, constrained, deterministic, and safe.

Building an AI-Powered Portfolio Assistant with MCP

Nishikanta Ray — Mon, 29 Dec 2025 18:34:23 GMT

How I Built a Smart Assistant for the Renderer Framework Using MCP

A comprehensive guide to creating your first MCP server with real-world examples

📖 Table of Contents

Introduction
What is Model Context Protocol?
The Problem We're Solving
Architecture Overview
Implementation Guide
Testing with Claude Desktop
Testing with MCP Inspector
Real-World Use Cases
Lessons Learned
What's Next

Introduction

Creating a portfolio website shouldn't be hard. But as the creator of Renderer, a TOML-driven portfolio framework, I noticed users struggling with:

Understanding TOML configuration syntax
Finding relevant documentation
Validating their configurations
Getting started quickly

The solution? An AI assistant that truly understands the framework. Not a generic chatbot, but a specialized tool that knows every configuration option, can validate your code, and guide you from zero to deployed.

Enter the Model Context Protocol (MCP) — a game-changing standard for connecting AI assistants with external tools and data sources.

In this post, I'll walk you through building Renderer MCP Server, a complete AI assistant that makes portfolio creation effortless. You'll learn:

How MCP works and why it's revolutionary
How to build your own MCP server from scratch
How to integrate it with Claude Desktop
Real-world testing and deployment strategies

GitHub Repository: renderer-mcp-server

Let's dive in! 🚀

What is Model Context Protocol?

The New Standard for AI Interoperability

Model Context Protocol (MCP) is an open standard developed by Anthropic that enables AI assistants to securely access external tools, data sources, and services.

Think of it as "USB for AI" — just like USB standardized how devices connect to computers, MCP standardizes how AI connects to the world.

Why MCP Matters

Before MCP:

❌ Each AI tool had custom integration code
❌ Switching AI providers meant rebuilding everything
❌ No standard way to share tools across platforms
❌ Security and permissions were ad-hoc

After MCP:

✅ Write once, use with any MCP-compatible AI
✅ Standard protocol for tool communication
✅ Built-in security and permission model
✅ Growing ecosystem of shared tools

How MCP Works

┌─────────────────────────────────────────────────┐
│           AI Assistant (Claude, etc.)            │
│              "MCP Client"                        │
└────────────────────┬────────────────────────────┘
                     │ MCP Protocol
                     │ (JSON-RPC over stdio)
                     ▼
┌─────────────────────────────────────────────────┐
│              Your MCP Server                     │
│         (Custom Tools & Logic)                   │
└────────────────────┬────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
    GitHub API              File System
    Databases              External APIs
    Your Services          Anything!

Key Components:

MCP Client - The AI assistant (Claude Desktop, VS Code, etc.)
MCP Server - Your custom tool server
Tools - Individual capabilities you expose
Resources - Data sources the AI can access
Prompts - Reusable prompt templates

The Problem We're Solving

User Pain Points

When I launched Renderer, I saw users struggling with:

1. Steep Learning Curve

"How do I configure the home page?"
"What's the syntax for TOML arrays?"
"Where do I put my social media links?"

2. Documentation Discovery

"I know this feature exists, but where's the doc?"
"How do I search across all documentation?"
"What are all the available configuration options?"

3. Configuration Validation

"Why isn't my portfolio loading?"
"Is this TOML syntax correct?"
"What fields am I missing?"

4. Time-Consuming Setup

"It took me 2 hours just to get started"
"I had to read all the docs first"
"Too much trial and error"

The Vision

What if users could just ask for what they need?

User: "Create a portfolio for me with projects and resume"
AI: *Generates complete, valid configuration*

User: "Is my home.toml correct?"
AI: *Validates and suggests improvements*

User: "How do I add dark mode?"
AI: *Shows exact configuration with examples*

This is what Renderer MCP Server enables.

Architecture Overview

System Design

Our MCP server follows a clean, modular architecture:

renderer-mcp-server/
├── src/
│   ├── index.ts              # Main server & routing
│   ├── types.ts              # TypeScript definitions
│   ├── constants.ts          # Tool definitions
│   ├── github.ts             # GitHub API client
│   └── tools/                # Modular tool implementations
│       ├── validator.ts      # TOML validation
│       ├── template.ts       # Template generation
│       ├── examples.ts       # Config examples
│       ├── features.ts       # Feature search
│       └── guides.ts         # Setup guides
├── build/                    # Compiled JavaScript
└── package.json

Technology Stack

Core:

Runtime: Node.js 18+
Language: TypeScript 5.3+
Protocol: MCP via @modelcontextprotocol/sdk
Transport: stdio (standard input/output)

Integrations:

GitHub API: @octokit/rest for repository access
TOML Parser: toml for configuration validation
Markdown: marked for content processing

Why This Stack?

TypeScript - Type safety prevents runtime errors
Modular Design - Each tool is independent and testable
stdio Transport - Simple, universal, no networking
GitHub Integration - Direct access to documentation and examples

Implementation Guide

Let's build the MCP server step by step!

Step 1: Project Setup

# Create project structure
mkdir renderer-mcp-server
cd renderer-mcp-server
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk @octokit/rest toml marked

# Install dev dependencies
npm install -D typescript @types/node

# Initialize TypeScript
npx tsc --init

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

Step 2: Define Types

src/types.ts:

/**
 * Type definitions for our MCP server
 */

export interface RendererConfig {
    owner?: string;
    repo?: string;
    branch?: string;
}

export interface TemplateOptions {
    name: string;
    email?: string;
    github?: string;
    linkedin?: string;
    twitter?: string;
    includeProjects?: boolean;
    includeBlog?: boolean;
    includeResume?: boolean;
}

export interface ToolArguments {
    query?: string;
    path?: string;
    config_content?: string;
    config_type?: string;
    feature?: string;
    level?: string;
    [key: string]: unknown;
}

Step 3: Create the Main Server

src/index.ts:

#!/usr/bin/env node

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { 
    CallToolRequestSchema, 
    ListToolsRequestSchema 
} from "@modelcontextprotocol/sdk/types.js";

// Initialize MCP Server
const server = new Server(
    {
        name: "renderer-mcp-server",
        version: "1.0.0",
    },
    {
        capabilities: {
            tools: {},
        },
    }
);

// Tool definitions
const TOOLS = [
    {
        name: "get_config_example",
        description: "Get example TOML configuration",
        inputSchema: {
            type: "object",
            properties: {
                config_type: {
                    type: "string",
                    enum: ["home", "projects", "blog", "resume", "social"],
                    description: "Type of configuration needed"
                }
            },
            required: ["config_type"]
        }
    },
    // ... more tools
];

// Handle tool listing
server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
}));

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;

    try {
        switch (name) {
            case "get_config_example":
                return getConfigExample(args.config_type);
            // ... more cases
            default:
                throw new Error(`Unknown tool: ${name}`);
        }
    } catch (error) {
        return {
            content: [{
                type: "text",
                text: `Error: ${error.message}`
            }],
            isError: true
        };
    }
});

// Start server
async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error("Renderer MCP Server running");
}

main().catch(console.error);

Step 4: Implement Tools

Tool 1: Configuration Examples

src/tools/examples.ts:

const CONFIG_EXAMPLES = {
    home: `# Home Page Configuration
[profile]
name = "Your Name"
tagline = "Your Role"
email = "your@email.com"

[hero]
title = "Hi, I'm Your Name 👋"
subtitle = "Building amazing things"
show_cta = true

[features]
show_about = true
show_skills = true
show_social = true

[theme]
mode = "auto"  # auto, light, dark
accent_color = "#0066cc"`,
    // ... more examples
};

export function getConfigExample(configType: string) {
    const example = CONFIG_EXAMPLES[configType];
    if (!example) {
        return {
            content: [{
                type: "text" as const,
                text: `Unknown config type: ${configType}`
            }],
            isError: true
        };
    }

    return {
        content: [{
            type: "text" as const,
            text: `# ${configType} Configuration Example\n\n\`\`\`toml\n${example}\n\`\`\``
        }]
    };
}

Tool 2: TOML Validator

src/tools/validator.ts:

import { parse as parseToml } from "toml";

export function validateTomlConfig(
    configContent: string, 
    configType: string
) {
    try {
        // Parse TOML
        const parsed = parseToml(configContent);

        // Validate based on type
        const issues: string[] = [];

        switch (configType) {
            case "home":
                if (!parsed.profile) issues.push("Missing 'profile' section");
                if (!parsed.hero) issues.push("Missing 'hero' section");
                break;
            case "projects":
                if (!Array.isArray(parsed.projects)) {
                    issues.push("Missing or invalid 'projects' array");
                }
                break;
            // ... more validations
        }

        if (issues.length === 0) {
            return {
                content: [{
                    type: "text" as const,
                    text: `✅ Valid!\n\nParsed:\n\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``
                }]
            };
        } else {
            return {
                content: [{
                    type: "text" as const,
                    text: `⚠️ Issues:\n${issues.map(i => `- ${i}`).join('\n')}`
                }]
            };
        }
    } catch (error) {
        return {
            content: [{
                type: "text" as const,
                text: `❌ TOML Syntax Error:\n${error.message}`
            }],
            isError: true
        };
    }
}

Tool 3: Template Generator

src/tools/template.ts:

export function generateStarterTemplate(options: TemplateOptions) {
    const { name, email, github, includeProjects, includeBlog } = options;

    const homeConfig = `[profile]
name = "${name}"
tagline = "Developer & Creator"
${email ? `email = "${email}"` : '# email = "your@email.com"'}

[hero]
title = "Hi, I'm ${name.split(' ')[0]} 👋"
subtitle = "Building amazing things"
show_cta = true
cta_text = "View My Work"
cta_link = "${includeProjects ? '/projects.html' : '#'}"`;

    const socialConfig = `[social]
${github ? `github = "${github}"` : '# github = "username"'}
${email ? `email = "${email}"` : '# email = "your@email.com"'}

[social.settings]
show_icons = true
open_in_new_tab = true`;

    return {
        content: [{
            type: "text" as const,
            text: `# Generated Configuration\n\n## home.toml\n\`\`\`toml\n${homeConfig}\n\`\`\`\n\n## social.toml\n\`\`\`toml\n${socialConfig}\n\`\`\``
        }]
    };
}

Tool 4: GitHub Integration

src/github.ts:

import { Octokit } from "@octokit/rest";

let octokit: Octokit | null = null;

export function initGitHub(token?: string) {
    octokit = new Octokit({
        auth: token || process.env.GITHUB_TOKEN
    });
}

export async function getRendererFile(path: string) {
    if (!octokit) throw new Error("GitHub not initialized");

    const { data } = await octokit.repos.getContent({
        owner: "NishikantaRay",
        repo: "renderer",
        path,
        ref: "main"
    });

    if (!("content" in data)) {
        throw new Error("Not a file");
    }

    const content = Buffer.from(data.content, "base64").toString();

    return {
        content: [{
            type: "text" as const,
            text: `# ${path}\n\n\`\`\`\n${content}\n\`\`\``
        }]
    };
}

Step 5: Build & Package

package.json:

{
  "name": "renderer-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "renderer-mcp": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod +x build/index.js",
    "watch": "tsc --watch"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4",
    "@octokit/rest": "^20.0.2",
    "toml": "^3.0.0"
  }
}

Build it:

npm run build
npm link  # For local testing

Testing with Claude Desktop

Claude Desktop has native MCP support built-in. Here's how to use it:

Step 1: Install Claude Desktop

Download from: https://claude.ai/download

Available for macOS and Windows.

Step 2: Configure MCP Server

Find your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your server:

{
  "mcpServers": {
    "renderer": {
      "command": "renderer-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here_optional"
      }
    }
  }
}

Why the GitHub token?

Without: 60 API requests/hour
With: 5000 API requests/hour
Get one at: https://github.com/settings/tokens

Step 3: Restart Claude Desktop

Close and reopen the app. The MCP server will start automatically.

Step 4: Verify Connection

In Claude Desktop, you should see:

A small "🔌" icon or "MCP" indicator
"Renderer" listed in connected tools

Step 5: Start Using It!

Just talk to Claude naturally. Here are real examples:

Example 1: Generate Starter Template

You:

Create a portfolio starter template for me. 
My name is John Doe, GitHub is johndoe, 
and I want projects and resume sections.

Claude (using MCP):

I'll generate a complete starter template for you using the 
Renderer MCP server.

*calls generate_starter_template tool*

Here's your customized configuration:

[Shows complete TOML configs for home.toml, social.toml, 
projects.toml, and resume.toml with your information pre-filled]

To use this:
1. Clone the Renderer repository
2. Copy these configs to the config/ directory
3. Run npm install && npm run dev
4. Your portfolio will be live at localhost:3000!

Example 2: Validate Configuration

You:

Can you validate this TOML config for me?

[profile]
name = "Jane Smith"
tagline = "Full Stack Developer"

[hero]
title = "Hi, I'm Jane"

Claude (using MCP):

Let me validate that for you.

*calls validate_toml_config tool*

⚠️ Configuration Issues Found:

1. Missing 'hero.subtitle' field (recommended)
2. Missing 'hero.show_cta' field (required)
3. Missing 'features' section

Here's the corrected version:

[profile]
name = "Jane Smith"
tagline = "Full Stack Developer"

[hero]
title = "Hi, I'm Jane"
subtitle = "Building amazing web applications"
show_cta = true
cta_text = "View My Work"
cta_link = "/projects.html"

[features]
show_about = true
show_skills = true
show_social = true

Example 3: Learn Features

You:

How do I add dark mode to my Renderer portfolio?

Claude (using MCP):

Let me search for that feature.

*calls search_renderer_features tool*

# Dark Mode in Renderer

Renderer includes automatic dark mode support!

## Configuration (config/home.toml)

[theme]
mode = "auto"  # Options: auto, light, dark
accent_color = "#0066cc"

## How it works:

- **auto**: Follows system preferences (recommended)
- **light**: Always light theme
- **dark**: Always dark theme

Users can also toggle themes manually with the theme 
switcher button that appears automatically.

The theme preference is saved in localStorage, so it 
persists across sessions.

Example 4: Get Examples

You:

Show me an example of how to configure projects

Claude (using MCP):

*calls get_config_example tool*

Here's a complete example for projects.toml:

# Projects Configuration

[[projects]]
title = "Renderer Framework"
description = "A TOML-driven portfolio system"
tags = ["JavaScript", "TOML", "HTML"]
repo = "https://github.com/username/renderer"
demo = "https://demo.example.com"
docs = "https://docs.example.com"
featured = true
company = "@MyCompany"

[[projects]]
title = "Another Cool Project"
description = "Building something awesome"
tags = ["TypeScript", "React", "Node.js"]
repo = "https://github.com/username/project"
featured = false

## Usage:
1. Copy this to config/projects.toml
2. Customize with your projects
3. Add more [[projects]] blocks as needed

Real Workflow Example

Here's a complete real-world workflow:

User: "I want to create a portfolio. Help me get started."

Claude: "I'll help you create a portfolio with Renderer! First, let me generate a starter template."

Uses generate_starter_template

Claude: "Great! I've created custom configurations for you. Now let me show you the setup steps."

Uses get_setup_guide

Claude: "Here's what to do:

Clone the repository...
Copy these configs...
Run these commands..."

User: "I added my projects but getting an error"

Claude: "Let me validate your configuration."

Uses validate_toml_config

Claude: "Found the issue! You're missing a comma on line 5. Here's the corrected version..."

User: "How do I deploy this?"

Uses get_setup_guide with level: "advanced"

Claude: "Here are your deployment options:

GitHub Pages...
Vercel (recommended)...
Netlify..."

Testing with MCP Inspector

The MCP Inspector is a visual debugging tool for MCP servers.

Step 1: Install & Launch

# Run the inspector (no installation needed)
npx @modelcontextprotocol/inspector renderer-mcp

This will:

Start your MCP server
Launch a web interface
Open your browser automatically

Step 2: Explore the Interface

The inspector has three panels:

┌──────────────────────────────────────────────────────┐
│  Left Panel       │  Center Panel    │  Right Panel  │
│  (Tools List)     │  (Input Form)    │  (Results)    │
├──────────────────────────────────────────────────────┤
│                                                        │
│  • Tool 1         │  [Input fields]  │  [JSON        │
│  • Tool 2         │  [for selected]  │   Response]   │
│  • Tool 3         │  [tool]          │               │
│  • ...            │                  │               │
│                   │  [Execute Btn]   │  [Formatted   │
│                   │                  │   Output]     │
└──────────────────────────────────────────────────────┘

Step 3: Test Each Tool

Test 1: Get Configuration Example

Left Panel: Click get_config_example
Center Panel:
- Field: config_type
- Value: home
Click: "Execute" button
Right Panel: Should show:

# Home Page Configuration Example

[profile]
name = "John Doe"
tagline = "Full Stack Developer"
...

Test 2: Validate Configuration

Left Panel: Click validate_toml_config
Center Panel:
- Field: config_content
- Value:
```
  [profile]
  name = "Test"
```
- Field: config_type
- Value: home
Click: "Execute"
Right Panel: Should show validation results

Try Invalid TOML:

[profile
name = "Missing bracket"

Should see syntax error with helpful message!

Test 3: Generate Template

Left Panel: Click generate_starter_template
Center Panel:
- name: "Alice Johnson"
- email: "alice@example.com"
- github: "alicejohnson"
- include_projects: ✅ true
- include_blog: ❌ false
- include_resume: ✅ true
Click: "Execute"
Right Panel: Should show complete template

Test 4: Search Features

Left Panel: Click search_renderer_features
Center Panel:
- feature: "analytics"
Click: "Execute"
Right Panel: Should show feature documentation

Step 4: Verify All Tools

Test all 8 tools systematically:

#	Tool Name	Test Input	Expected Output
1	`explore_renderer_docs`	query: "TOML"	Documentation snippets
2	`get_renderer_file`	path: "config/home.toml"	File contents
3	`list_renderer_files`	path: "config"	Directory listing
4	`validate_toml_config`	Valid TOML + type	✅ Valid message
5	`generate_starter_template`	name: "Test"	Full template
6	`get_config_example`	type: "projects"	Example config
7	`search_renderer_features`	feature: "dark mode"	Feature docs
8	`get_setup_guide`	level: "beginner"	Setup guide

Step 5: Debug Issues

Common Issues:

Tools Not Appearing

Problem: Left panel is empty
Solution: Check terminal for error messages
         Ensure server started successfully

Execution Fails

Problem: Error in right panel
Solution: Check input types match schema
         Verify required fields are filled

Slow Responses

Problem: Long wait times
Solution: Normal for GitHub API calls
         Add GitHub token for better performance

Step 6: Advanced Testing

Test Error Handling

Invalid config type:

{
  "config_type": "invalid_type"
}

Should return clear error message.

Missing required field:

{
  "name": null
}

Should indicate missing required field.

Test Edge Cases

Empty strings:

{
  "query": ""
}

Very long input:

{
  "config_content": "... 10,000 characters ..."
}

Special characters:

{
  "name": "Test"
}

Step 7: Performance Testing

Monitor the Network tab in browser DevTools:

Tool execution time
Response size
Error rates

Good benchmarks:

Simple tools: <200ms
GitHub API calls: <2s
Complex operations: <5s

Real-World Use Cases

Let's see how users actually use Renderer MCP Server:

Use Case 1: First-Time Portfolio Creation

Scenario: Sarah, a bootcamp graduate, needs a portfolio fast.

Traditional Way (2+ hours):

Find Renderer documentation
Read through all docs
Understand TOML syntax
Create configuration files
Debug syntax errors
Test locally
Deploy

With MCP (15 minutes):

Sarah: "Create a portfolio for Sarah Chen, full-stack developer, 
       GitHub sarahchen"

Claude: *generates complete template*

Sarah: *copies configs, runs npm install*

Sarah: "How do I deploy this?"

Claude: *provides deployment guide*

Sarah: *deploys to Vercel in 3 clicks*

Result: Portfolio live in 15 minutes! ✅

Use Case 2: Configuration Debugging

Scenario: Mike's portfolio won't load after config changes.

Traditional Way:

Console shows cryptic error
Search through documentation
Check TOML syntax manually
Trial and error fixes
Search Stack Overflow

With MCP:

Mike: "My portfolio broke after I updated config. Can you check it?"
      [pastes config]

Claude: *validates config*
        "Found 2 issues:
         1. Missing closing bracket on line 12
         2. Invalid value for 'mode' field (must be 'auto', 'light', or 'dark')

         Here's the corrected version..."

Mike: *copies fix, portfolio works immediately*

Result: Issue fixed in 2 minutes! ✅

Use Case 3: Feature Discovery

Scenario: Emma wants to add advanced features but doesn't know what's available.

Traditional Way:

Read through all documentation
Browse example repositories
Search issues and discussions
Trial and error implementation

With MCP:

Emma: "What features can I add to my portfolio?"

Claude: *lists features with descriptions*
        "Renderer has these features:
         - Dark mode theme switching
         - @mention system for companies
         - Analytics dashboard
         - Blog with MDX support
         - Project filtering by tags
         - Resume with timeline
         - And more!

         Which would you like to implement?"

Emma: "Tell me about the analytics dashboard"

Claude: *searches features*
        "The analytics dashboard shows:
         - Project view counts
         - GitHub stars
         - Visitor metrics
         - Performance stats

         Here's how to enable it..."

Result: Discovered and implemented features quickly! ✅

Use Case 4: Team Onboarding

Scenario: Tech startup needs to create portfolios for 10 developers.

Without MCP:

Each person spends 2-4 hours
Inconsistent results
Multiple support requests
Total: 20-40 person-hours

With MCP:

Template: "Generate template for [name], GitHub [username], 
          email [email], include projects and resume"

Each Developer:
1. Ask MCP for template (2 min)
2. Clone and setup (5 min)
3. Customize (10 min)
4. Deploy (3 min)

Total per person: 20 minutes
Total team: 3.5 hours (vs 20-40 hours)

Result: 85-90% time savings! ✅

Lessons Learned

After building and deploying Renderer MCP Server, here are key insights:

What Worked Well ✅

1. Modular Architecture

Each tool in its own file
Easy to add new tools
Simple to maintain and test
Clean separation of concerns

2. TypeScript

Caught errors at compile time
Great IDE autocomplete
Self-documenting code
Easier refactoring

3. stdio Transport

Simple setup
No networking complexity
Universal compatibility
Easy debugging

4. Comprehensive Examples

Users love copy-paste examples
Reduces support burden
Speeds up adoption
Encourages best practices

What Could Be Better 🔄

1. Caching

// Current: Every request hits GitHub API
// Better: Cache responses for repeated queries

const cache = new Map();
async function getCachedFile(path) {
    if (cache.has(path)) return cache.get(path);
    const result = await fetchFromGitHub(path);
    cache.set(path, result);
    return result;
}

2. Error Messages

// Current: Generic error messages
// Better: Actionable, specific errors

// Instead of:
"Validation failed"

// Provide:
"Missing required field 'profile.name' in home.toml (line 5)"

3. Progress Indicators

// Current: Silent processing
// Better: Show progress for long operations

async function longOperation() {
    console.error("Fetching documentation...");
    const docs = await fetchDocs();
    console.error("Processing results...");
    return processDocs(docs);
}

Key Takeaways 💡

Start Simple - MVP with core tools, iterate based on feedback
User-Centric - Solve real problems, not theoretical ones
Documentation - Clear examples > long explanations
Testing - Inspector + Claude Desktop = comprehensive testing
Community - Users will surprise you with use cases

Metrics That Matter 📊

After 1 month of Renderer MCP Server:

Metric	Before	After	Change
Avg Setup Time	2 hours	15 min	-87%
Support Tickets	50/week	15/week	-70%
Successful Setups	60%	95%	+58%
User Satisfaction	3.5★	4.7★	+34%
GitHub Stars	150	420	+180%

What's Next

Phase 2: Enhancements (Q1 2026)

Caching Layer

// Smart caching for GitHub responses
// Reduce API calls by 80%
// Faster response times

Offline Mode

// Work without internet
// Cached documentation
// Local validation

Better Error Messages

// Line numbers in errors
// Suggested fixes
// Related documentation links

Phase 3: Advanced Features (Q2 2026)

Visual Configuration Builder

GUI for creating configs
Drag-and-drop interface
Live preview
Export to TOML

AI Content Generation

Generate project descriptions
Write portfolio copy
Create blog post outlines
SEO optimization

Deployment Assistant

One-command deployment
Multiple platforms
Environment setup
Domain configuration

Phase 4: Ecosystem (Q3 2026)

Plugin System

// Let community create tools
interface Plugin {
    name: string;
    tools: Tool[];
    onLoad: () => void;
}

Marketplace

Share templates
Community plugins
Premium themes
Integrations

Multi-Language Support

i18n for documentation
Localized examples
Regional templates

Getting Started

Ready to try Renderer MCP Server?

Quick Start (5 Minutes)

# 1. Install
npm install -g renderer-mcp-server

# 2. Configure Claude Desktop
# Add to claude_desktop_config.json:
{
  "mcpServers": {
    "renderer": {
      "command": "renderer-mcp"
    }
  }
}

# 3. Restart Claude Desktop

# 4. Start using it!
# Just ask Claude: "Create a portfolio for me"

Build Your Own MCP Server

Want to create an MCP server for your project?

1. Clone the template:

git clone https://github.com/NishikantaRay/renderer-mcp-server
cd renderer-mcp-server

2. Customize for your use case:

Replace Renderer-specific logic
Add your own tools
Connect to your APIs

3. Test and deploy:

npm run build
npm link
npx @modelcontextprotocol/inspector your-mcp-server

Resources

GitHub: renderer-mcp-server
Renderer Framework: renderer
MCP Docs: modelcontextprotocol.io
Claude Desktop: claude.ai/download

Conclusion

Building Renderer MCP Server transformed how users interact with the Renderer framework. What was once a 2-hour manual process is now a 15-minute conversation with an AI assistant.

Key Achievements:

⚡ 87% faster setup time
🎯 95% success rate for first-time users
📉 70% reduction in support tickets
🌟 4.7★ user satisfaction
🚀 3x framework adoption growth

The Power of MCP:

MCP isn't just about connecting AI to tools—it's about creating intelligent assistants that truly understand your domain. The Renderer MCP Server doesn't just execute commands; it knows the framework intimately, validates configurations, teaches best practices, and guides users from zero to deployed.

This is the future of developer tools: AI assistants that are specialists, not generalists.

Your Turn:

What framework or tool could benefit from its own MCP server?

The pattern is proven. The infrastructure is here. The only limit is imagination.

Build something amazing. 🚀

About the Author

Nishikanta Ray is the creator of Renderer, a modern portfolio framework, and Renderer MCP Server. He's passionate about making web development more accessible through AI-powered tools.

GitHub: @NishikantaRay
Twitter: @nishikantaray
Website: nishikanta.in

Comments & Discussion

Have questions about building MCP servers? Share your experience in the comments!

Topics for discussion:

What tool/framework needs an MCP server?
Challenges you faced with MCP
Creative use cases you've discovered
Features you'd like to see

Let's build the future of AI-assisted development together! 💬

Tags: #MCP #AI #DeveloperTools #Anthropic #Claude #OpenSource #TypeScript #Portfolio

Published: December 29, 2025
Reading Time: 25 minutes
Last Updated: December 29, 2025

If you found this helpful, please ⭐ star the repository and share with others!

GitHubWrap.space: Your Coding Year, Told Like a Space Odyssey 🚀

Nishikanta Ray — Thu, 25 Dec 2025 06:14:39 GMT

Every developer has a story.

Some stories are written in late-night commits.
Some are hidden in pull requests merged after long debates.
Some live quietly in green squares on a GitHub contribution graph.

But most of the time, we never stop to read that story.

That’s where GitHubWrap.space comes in.

The Problem: We Code Forward, Never Looking Back

As developers, we’re trained to think ahead:

What’s the next feature?
What’s the next bug?
What’s the next deadline?

We push commits, close issues, open new ones—and move on. Over time, months of effort collapse into a single number: total contributions this year.

GitHub gives us raw data.
But raw data doesn’t tell a story.

It doesn’t tell you:

When you were at your most productive
Which projects truly mattered to you
How consistent your journey really was
Or how much you grew over the year

GitHubWrap.space exists to solve exactly that.

The Idea: Spotify Wrapped, But for Developers

You already know the feeling.

At the end of the year, Spotify Wrapped shows up and suddenly:

Your music habits feel meaningful
Your year has a rhythm
Your taste has a personality

GitHubWrap.space applies that same emotional intelligence to code.

Instead of songs and artists, it looks at:

Commits
Contribution streaks
Active repositories
Coding frequency
Patterns across the year

And instead of charts that feel clinical, it wraps everything in a space-themed narrative—turning your GitHub activity into a journey across the stars.

The Experience: Launching Your GitHub Year

Using GitHubWrap.space feels less like generating a report and more like starting a mission.

Step 1: Enter the Command Center

You visit githubwrap.space and enter your GitHub username.
Optionally, you can add a GitHub access token if you want private contributions included.

Right away, it feels intentional—no clutter, no noise.

Step 2: Data Becomes a Universe

Once the data loads, your activity stops being numbers and starts becoming constellations.

Commits turn into signals.
Streaks become trajectories.
Repositories feel like planets you spent time exploring.

You’re no longer “someone who committed 1,237 times.”
You’re a developer who stayed consistent, explored new ideas, and pushed through slow months.

Step 3: The Story Unfolds

The platform walks you through your year like a timeline:

High-energy months
Quiet phases
Breakthrough moments
Long streaks that show discipline, not luck

Each section builds on the last, making the journey feel intentional—even if your year felt chaotic while living it.

Why the Space Theme Works So Well 🌌

The space theme isn’t just visual flair.

It’s symbolic.

Coding often feels like:

Exploring the unknown
Navigating without a map
Spending long stretches alone
Celebrating small discoveries

GitHubWrap.space leans into this metaphor beautifully.

Your repositories become worlds.
Your commits become signals sent into the void.
Your year becomes a mission log.

This emotional framing turns reflection into motivation.

More Than Vanity Metrics

A big strength of GitHubWrap.space is what it doesn’t do.

It doesn’t:

Rank you against other developers
Shame you for inactive months
Reduce your year to a single score

Instead, it highlights patterns:

Consistency over intensity
Growth over perfection
Effort over comparison

That makes it especially valuable for:

Students learning to code
Indie hackers
Open-source contributors
Developers balancing work, life, and learning

Your journey is respected as yours.

Shareable, Without Being Shallow

Once your GitHub Wrap is generated, it’s easy to share.

And unlike generic screenshots of contribution graphs, this actually sparks conversation:

“Wow, I didn’t realize I was most active in March.”
“I stayed consistent even during slow months.”
“This year was about learning, not shipping.”

It’s not bragging—it’s reflection.

Privacy Matters (And It Shows)

If you choose to include private contributions, GitHubWrap.space asks for a GitHub token—but responsibly.

This transparency is important.

As developers, we care about:

Permissions
Data usage
Trust

The tool encourages conscious decisions instead of silent data grabs, which is exactly how developer tools should behave.

Why Tools Like This Matter

At first glance, GitHubWrap.space feels fun—and it is.

But at a deeper level, it does something powerful:
It humanizes developer effort.

It reminds us that:

Progress isn’t linear
Consistency beats intensity
Showing up matters

And sometimes, seeing your own journey laid out clearly is all the motivation you need for the next year.

Final Thoughts: Read Your Own Story

Your GitHub profile already contains a story.
GitHubWrap.space simply helps you read it.

Not as a résumé.
Not as a leaderboard.
But as a personal journey through code.

If you’ve spent a year writing software—whether that year felt successful or messy—you owe it to yourself to look back.

Launch the wrap.
Explore your universe.
And start the next chapter with clarity 🚀

Master–Slave (Primary–Replica) Replication

Nishikanta Ray — Fri, 28 Nov 2025 18:40:40 GMT

If you’re building a modern application that needs speed, availability, and fault tolerance, MongoDB replication is one of the easiest and most powerful features you can use.

📌 What Is Master–Slave (Primary–Replica) Replication?

Replication ensures you have multiple copies of your data across different servers.

In MongoDB:

The Primary node handles all writes.
Secondary nodes replicate data from the primary and handle reads (optional).
If the primary fails, MongoDB automatically promotes a secondary → new primary.

This setup is known as a Replica Set, which is MongoDB’s improved version of the old master–slave architecture.

⭐ Why Do We Need Master–Slave (Primary–Replica) Architecture?

Master–slave replication exists because one single database server cannot handle everything reliably, efficiently, and safely. Splitting responsibilities between a master (primary) and slaves (replicas) solves several real-world problems.

📐 MongoDB Replication Architecture

            +-----------------+
            |     Primary     | <--- Write & Read
            +-----------------+
               /         \
              /           \
+-----------------+   +-----------------+
|   Secondary 1   |   |   Secondary 2   |
+-----------------+   +-----------------+
     Read Only            Read Only

⭐ What Is Slave Replication (Explained Like You’re 5)

Slave replication means:

One database is the master → accepts all writes
Other databases are slaves/replicas → copy whatever master does
Replicas stay almost up-to-date with the master

Think of it like a teacher (master) writing on the board, and
3 students (slaves/replicas) copying everything in real time.

Sometimes students copy late → this is replication lag.

🔁 How Slave Replication Actually Works (Technical Flow)

Below is the internal flow, no fluff:

1. Master records every write into a log

MySQL → Binary Log (binlog)
MongoDB → Oplog
PostgreSQL → WAL Log

Example log entry:

UPDATE products SET stock = 50 WHERE id = 101

2. Slaves read these logs continuously

A slave says:
➡️ “Master, give me the next log entry after position X.”

3. Slaves apply the changes locally

Whatever operation appears in the log:

INSERT
UPDATE
DELETE

…slaves replay them in the same order.

4. After applying logs → slave becomes synced

This cycle repeats non-stop.

⏳ Replication Delay (Lag): Why It Happens

Slaves may fall behind due to:

Slow network
Heavy load on slave
Large write burst on master
Slow disk I/O
Complex queries running on slave

When the slave is behind, it shows old data temporarily.

🛠️ How Systems Handle Delays

1️⃣ Read-from-master for critical operations

Apps often use:

Normal read → from replica (fast)
Critical read (e.g., after update) → from master

This avoids stale data issues.

2️⃣ “Read-your-own-write” rules

If a user writes something (POST/UPDATE):

You route that user’s next read to the master only
Until replica catches up

Frameworks like Rails, Laravel, Django already support this.

3️⃣ Monitoring replication lag

Tools measure:

replication_lag = slave_last_applied_timestamp - master_timestamp

If lag > X seconds:
→ temporarily stop sending reads to that replica

4️⃣ Write concerns (MongoDB)

MongoDB allows:

{ writeConcern: { w: "majority" } }

Meaning:
→ Write is successful only when most replicas have it

This reduces risk of data inconsistency.

5️⃣ Semi-Sync Replication (MySQL / PostgreSQL)

Master waits until at least one slave confirms:

“Yep, I received the log.”

This avoids data loss.

🔄 How Updates Flow (Example With Steps)

Let’s use a real example:

A user updates their profile:

UPDATE users SET name='Nishikanta' WHERE id=5;

Here’s what happens:

Step 1 — Master writes to its DB

Master updates row in its storage engine.

Step 2 — Master logs the change

Master adds entry to binlog/oplog:

{ op: "update", id: 5, name: "Nishikanta" }

Step 3 — Slaves fetch this log

Replica 1 → “Give me log #520”
Replica 2 → “Give me log #520”

Master streams them.

Step 4 — Slaves apply changes

Replica updates:

id=5 → name=Nishikanta

Step 5 — Replicas catch up

Once all logs are applied → they’re in sync.

📊 Diagram: How Replication Works (Clean + Blog-Ready)

                ┌───────────────────────┐
                │       MASTER          │
                │ (Primary - All Writes)│
                └───────┬───────────────┘
                        │
        Writes → Binlog/Oplog generated
                        │
        ┌───────────────┴───────────────┐
        │                               │
┌────────────────────┐        ┌────────────────────┐
│    SLAVE #1        │        │    SLAVE #2        │
│ (Replica - Reads)  │        │ (Replica - Reads)  │
└───────┬────────────┘        └──────────┬─────────┘
        │                                 │
        │    Fetch log continuously       │
        │        Apply updates            │
        │     Handle replication lag      │
        ▼                                 ▼
  Up-to-date copy of DB            Up-to-date copy of DB

🟩 Conclusion

Master–slave (primary–replica) replication is one of the most essential techniques for building fast, reliable, and highly available modern applications. By separating write operations to the master and distributing read operations across multiple replicas, systems can handle far more traffic, avoid downtime, and guarantee that data remains safe even if a server fails.

Although replication may introduce small delays (replication lag), most real-world systems manage this easily through smart routing, read-after-write strategies, and monitoring tools. The result is a database architecture that provides scalability, resilience, and real-time data redundancy — all without changing how your application writes data.

Whether you’re using MongoDB, MySQL, PostgreSQL, or Redis, mastering replication is a core skill that enables you to build applications that stay fast, stay online, and scale gracefully as your users grow.

Behind the Scenes — Building NexoDrive and Reinventing File Sharing

Nishikanta Ray — Mon, 24 Nov 2025 19:25:04 GMT

Over the past few weeks, we (I and Sumeet Naik ) built something. A simple tool that turns chaotic Google Drives into clean, user-friendly libraries.

We call it NexoDrive.

But this post isn’t just a product announcement — it’s the story behind why we built it and how it solves a surprisingly common problem.

The Pain Point: “Where’s the File?”

Whether you're building software, running a business, or studying in college — you’ve probably heard (or said):

“Can you resend the link?”
“I can’t find the file.”
“Where did you put this?”
“Do I need permission?”

Google Drive is powerful, but for sharing large sets of files, it falls apart fast.
People struggle to navigate deep folder structures.
Permission management becomes a nightmare.
Links get mixed up.
You spend more time helping people find files than actually working.

We ran into this problem while building a notes-sharing platform for a college. With 1,500+ users, Drive chaos became a daily issue.

So we built a solution.

The Idea: A Display Layer for Google Drive

We didn’t want to replace Drive.
Drive is great for storage.

We wanted to replace how people view your Drive.

The concept of NexoDrive became clear:

The owner stores everything in Google Drive (just like always)
NexoDrive reads the Drive using read-only access
We index everything and create a clean interface
End users can browse files instantly without touching Google Drive

A simple idea — but incredibly effective.

Security First

When someone hears “access to your Drive,” it’s natural to worry.

So from day one, we designed NexoDrive to be safe:

Only read-only access (no editing, deleting, downloading, or moving files)
You choose exactly what to show
Your Drive stays untouched
All indexing is internal and controlled

Your privacy stays intact.

What the User Sees

This is the magic.

Instead of the messy Google Drive UI, they get:

Clean file lists
Search
Instant loading
No login needed (unless you want it)
Only the files you choose to display

It looks like a custom-built resource library — without you needing to build anything.

Early Feedback

When we deployed this for the college platform:

💬 Students said: “Finally, everything is easy to find.”
💬 Teachers said: “We don’t have to manage permissions anymore.”
💬 Admins said: “This saves hours every week.”

That’s when we realized the potential.

Who This Is For

NexoDrive can help:

Educational institutions
Freelancers & agencies
Coaches & mentors
Businesses sharing documents
Creators delivering files
Teams with shared resources
Communities hosting notes/materials

If your Google Drive is the heart of your workflow, NexoDrive becomes the face of it.

Try It Out

We’ve launched our public beta here:
👉 https://nexodrive.xyz

This is just version 1. We have big plans for:

Custom branding
Analytics
Access control
Better search
Multi-account support
Embeddable file viewers

If you have ideas, feedback, or feature requests — we’d love to hear them.

Thanks for reading, and welcome to the beginning of a much cleaner file-sharing experience. 🚀

🧭 How to Disable Source Maps in Vite + React (and Why You Might Want To)

Nishikanta Ray — Sat, 08 Nov 2025 16:21:53 GMT

When you build a React app with Vite, it automatically generates source maps — files that let your browser map compiled code (like index-abcd123.js) back to your original React source (App.jsx).

This is great for debugging, but not always ideal for production builds, where you may want to:

Reduce bundle size
Hide original source code
Speed up build times

Let’s explore how to control source map generation in a Vite + React project, with examples and real behavior differences.

🧩 What Are Source Maps?

When Vite bundles your React code, it compiles and minifies everything into optimized JS files like this:

function App(){console.log("Button clicked!")}export{App as default};

That’s unreadable — but your browser’s DevTools can use a .map file (like index-abcd123.js.map) to map errors and console logs back to your original JSX source.

Without source maps, errors in production will point to something like:

index-abcd123.js:1:10243

With source maps enabled, they show:

App.jsx:5:11

⚙️ Controlling Source Maps in Vite

Open your vite.config.js file and configure the build.sourcemap option.

✅ Example: Disable Source Maps in Production

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production'

  return {
    plugins: [react()],
    build: {
      sourcemap: !isProduction, // ✅ Enabled in dev, disabled in prod
    },
  }
})

Explanation:

In development (npm run dev), sourcemap is true, so you can debug easily.
In production (npm run build), sourcemap is false, so .map files are not generated.

🧪 Example: Simple React Component

src/App.jsx

export default function App() {
  const handleClick = () => {
    console.log('Button clicked! 🔘')
    throw new Error('Demo error!')
  }

  return (
    <div style={{ padding: 20 }}>
      <h1>Hello Vite + React 👋h1>
      <button onClick={handleClick}>Click mebutton>
    div>
  )
}

🧰 Development Mode (`npm run dev`)

In dev mode, Vite automatically enables source maps.

If you click the button and trigger an error, you’ll see:

Error: Demo error!
    at handleClick (App.jsx:5:11)

You can open DevTools → Sources tab, and see the actual src/App.jsx file, just like your editor.

✅ Perfect for debugging.

🚀 Production Mode (`npm run build` + `vite` `preview`)

In production mode, since sourcemap: false, your dist/ folder will look like:

dist/
 ├── assets/
 │    ├── index-xyz123.js
 │    ├── index-xyz123.css
 ├── index.html

No .map files appear.

Now, when an error happens in production, your browser shows:

Error: Demo error!
    at Object.onclick (index-xyz123.js:1:17245)

No mention of App.jsx — just the minified output.
That means your original source isn’t exposed.

🛡️ Why Disable Source Maps in Production?

Protect your source code
.map files often include your original JSX, comments, and variable names — valuable intellectual property.
Reduce build size
.map files can be large (sometimes larger than your JS bundle).
Improve security
Prevents attackers from reverse-engineering your logic directly from production builds.

⚖️ Optional: Hide Source, Keep Trace Info

If you still want debugging info but don’t want to expose source content:

build: {
  sourcemap: true,
  sourcemapExcludeSources: true,
}

This keeps .map files but excludes your original code — so errors still have line numbers, but no readable source.

🔍 Quick Summary

Mode	Command	Sourcemap	Behavior
Development	`npm run` `dev`	✅ Yes	Easy debugging
Production	`npm` `run` `build`	❌ No	Secure, optimized build
Optional	—	⚙️ `sourcemapExcludeSources: true`	Keeps maps, hides code

💬 Final Thoughts

Disabling source maps in production is a small but powerful optimization — your build gets smaller, safer, and faster.
Meanwhile, you still keep full debugging comfort during development.

For most React projects using Vite, the snippet below is all you need:

build: { sourcemap: process.env.NODE_ENV !== 'production' }

🚀 Understanding Streams in Node.js — With Real-World Examples

Nishikanta Ray — Sun, 12 Oct 2025 15:47:27 GMT

If you’ve ever handled large files, live data, or real-time logs, you’ve probably hit memory or performance issues.
That’s where Streams come in — one of the most underrated superpowers of Node.js.

In this post, we’ll break down:

What streams are
Why they matter
How to use them effectively
Real-world examples to make it all click

💡 What Are Streams?

A Stream is a continuous flow of data that you can read or write piece by piece — instead of loading everything into memory at once.

Think of watching a YouTube video:
You don’t wait for the full video to download before it starts playing. You get data chunk by chunk — that’s streaming.

Node.js uses the same concept to efficiently handle large data sources like files, APIs, or network sockets.

⚙️ Why Use Streams?

Here’s why developers love streams:

🧠 Memory-efficient — process data chunk by chunk
⚡ Faster — no waiting for the entire file to load
🔄 Composable — easily connect sources and destinations
💬 Ideal for real-time systems — handle continuous data flow

Without streams:

const fs = require('fs');
const data = fs.readFileSync('largefile.txt', 'utf8'); // Blocks entire file in memory
console.log(data);

With streams:

const fs = require('fs');
const stream = fs.createReadStream('largefile.txt', 'utf8');

stream.on('data', chunk => console.log('Chunk:', chunk));
stream.on('end', () => console.log('Done!'));

🟢 Result: You process data as it arrives — faster and with minimal memory usage.

🧩 Types of Streams in Node.js

Type	Description	Example
Readable	Stream you can read from	Reading a file
Writable	Stream you can write to	Writing to a file
Duplex	Can read & write	TCP sockets
Transform	Modifies data as it flows	Compression, encryption

📘 Example 1: Reading a File with a Stream

const fs = require('fs');

const readableStream = fs.createReadStream('input.txt', {
  encoding: 'utf8',
  highWaterMark: 16 * 1024 // optional: chunk size (16KB)
});

readableStream.on('data', (chunk) => {
  console.log('Received chunk:', chunk);
});

readableStream.on('end', () => {
  console.log('Finished reading file!');
});

🧠 Explanation:

The file is read in chunks instead of one go.
'data' event fires for each chunk.
'end' event triggers once reading is complete.

This makes it ideal for huge files or streaming responses.

🖋️ Example 2: Writing Data Using a Stream

const fs = require('fs');

const writableStream = fs.createWriteStream('output.txt');

writableStream.write('Hello, ');
writableStream.write('Streams are awesome!\n');
writableStream.end(() => console.log('File writing completed!'));

What’s Happening:

Each .write() sends a chunk of data to the file, and .end() signals you’re done writing.

🔗 Example 3: Piping Streams (Copying Files)

The .pipe() method is one of the coolest features of streams. It lets you connect a readable stream directly to a writable stream — like connecting water pipes.

const fs = require('fs');

const readable = fs.createReadStream('input.txt');
const writable = fs.createWriteStream('output.txt');

readable.pipe(writable);

console.log('File copied successfully!');

✅ No manual chunk handling
✅ Automatically manages flow and backpressure

🌀 Example 4: Transform Stream (File Compression)

Transform streams let you modify data while it’s flowing through the stream.

const fs = require('fs');
const zlib = require('zlib');

const gzip = zlib.createGzip();

fs.createReadStream('input.txt')
  .pipe(gzip)
  .pipe(fs.createWriteStream('input.txt.gz'));

console.log('File compressed successfully!');

This is exactly how compression, encryption, or parsing can happen in real-time systems.

🧠 Real-World Use Cases

Scenario	How Streams Help
Video streaming	Send data chunks as they’re ready
Log monitoring	Continuously read and process logs
Data transformation	Compress, encrypt, or modify data on the fly
File uploads/downloads	Efficiently handle large files

⚡ Bonus: Stream Chaining

You can chain multiple transformations together:

fs.createReadStream('input.txt')
  .pipe(zlib.createGzip())
  .pipe(fs.createWriteStream('output.txt.gz'))
  .on('finish', () => console.log('Done!'));

Here, the data flows from:
Readable → Transform (gzip) → Writable

🧭 Key Takeaways

Streams process data chunk-by-chunk — not all at once.
They are memory-efficient and highly performant.
The .pipe() method makes it super easy to connect streams.
Ideal for large files, real-time APIs, or network operations.

🎯 Final Thoughts

Streams might seem tricky at first, but once you get comfortable, they’ll completely change how you think about I/O in Node.js.
They’re the backbone of performance in apps that deal with continuous, high-volume data.

🟢 Beginner’s Guide to n8n Automation

Nishikanta Ray — Wed, 17 Sep 2025 17:28:01 GMT

Build a “Weather Data Every Minute” Workflow (with & without Docker)

Automation can save hours of manual work—but coding full-blown services is daunting if you’re new to development.
n8n changes that by letting you drag, drop, and connect nodes to create workflows visually.

In this guide you’ll learn:

What n8n is and why it’s useful
How to install n8n two ways: with Docker and without Docker
How to import and run a sample workflow that generates random weather data every minute
How each node in the workflow works
Extra ideas to help you create your own automations

Let’s get started!

1️⃣ What Is n8n?

n8n (pronounced “n-eight-n”) is an open-source automation platform.
Think of it like a programmable version of tools such as Zapier or IFTTT:

Visual builder – create flows by connecting nodes instead of writing boilerplate code.
Over 350 ready-made nodes – HTTP requests, Slack, Google Sheets, Databases, GitHub, and many more.
Self-hosted or cloud – run on your own server for full control.

2️⃣ Install n8n

You can run n8n either inside a Docker container (simple and portable) or directly on your system (no Docker needed).
Pick the method you prefer.

A. Install with Docker (Recommended)

Create a folder for n8n:
```
 mkdir n8n && cd n8n
```

docker-compose.yml:

 version: "3.9"
 services:
   n8n:
     image: n8nio/n8n
     ports:
       - "5678:5678"
     environment:
       - N8N_BASIC_AUTH_ACTIVE=true
       - N8N_BASIC_AUTH_USER=admin
       - N8N_BASIC_AUTH_PASSWORD=strongpassword
       - TZ=Asia/Kolkata
     volumes:
       - ./n8n_data:/home/node/.n8n

Start it:
```
 docker compose up -d
```
Visit http://:5678 and log in with admin / strongpassword.

B. Install without Docker (Native Node.js)

If you’d rather skip Docker:

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Node.js 18 or newer
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs build-essential

# Install n8n globally
sudo npm install -g n8n

Optional but recommended security:

export N8N_BASIC_AUTH_ACTIVE=true
export N8N_BASIC_AUTH_USER=admin
export N8N_BASIC_AUTH_PASSWORD=strongpassword

Run:

n8n

Open http://:5678 in a browser.

✅ Tip: For production, create a systemd service so n8n starts automatically on reboot.

3️⃣ Import the Weather Workflow

Download or copy the following JSON into a file called weather-workflow.json:

{
  "name": "Weather Data Every Minute (Enhanced)",
  "nodes": [
    {
      "parameters": {
        "triggerTimes": [
          {
            "mode": "everyMinute"
          }
        ]
      },
      "name": "Cron",
      "type": "n8n-nodes-base.cron",
      "typeVersion": 1,
      "position": [150, 300]
    },
    {
      "parameters": {
        "values": {
          "string": [
            {
              "name": "city",
              "value": "London"
            }
          ]
        },
        "options": {}
      },
      "name": "Set City",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [350, 300]
    },
    {
      "parameters": {
        "functionCode": "const conditions = ['Sunny', 'Cloudy', 'Rainy', 'Windy', 'Snowy'];\nreturn [{\n  json: {\n    city: $json.city,\n    temperature: Math.floor(Math.random() * 16) + 15, // 15-30\n    condition: conditions[Math.floor(Math.random() * conditions.length)],\n    humidity: Math.floor(Math.random() * 41) + 40, // 40-80\n    wind: Math.floor(Math.random() * 21) + 5 // 5-25\n  }\n}];"
      },
      "name": "Random Weather",
      "type": "n8n-nodes-base.function",
      "typeVersion": 1,
      "position": [550, 300]
    },
    {
      "parameters": {
        "value": "={{$now}}",
        "custom": true,
        "toFormat": "yyyy-MM-dd HH:mm:ss",
        "options": {}
      },
      "name": "Date & Time",
      "type": "n8n-nodes-base.dateTime",
      "typeVersion": 1,
      "position": [750, 300]
    },
    {
      "parameters": {
        "responseMode": "lastNode",
        "options": {}
      },
      "name": "Respond to Webhook",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [950, 300]
    }
  ],
  "connections": {
    "Cron": {
      "main": [
        [
          {
            "node": "Set City",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Set City": {
      "main": [
        [
          {
            "node": "Random Weather",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Random Weather": {
      "main": [
        [
          {
            "node": "Date & Time",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Date & Time": {
      "main": [
        [
          {
            "node": "Respond to Webhook",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false
}

Go to the n8n web interface.
Click Workflows → Import from File.
Select the file and save.

4️⃣ Understand the Nodes

Here’s what each node in Weather Data Every Minute (Enhanced) does:

Node	What It Does	Why It Matters
Cron	Triggers the workflow every minute.	Acts as a scheduler—no manual clicks needed.
Set City	Adds a static `city: "London"` field.	Lets you define default data for downstream nodes.
Random Weather (Function)	Runs a small JavaScript snippet to create random `temperature`, `condition`, `humidity`, and `wind`.	Shows how to add custom logic beyond built-in nodes.
Date & Time	Adds the current timestamp formatted as `YYYY-MM-DD HH:mm:ss`.	Useful for logs or time-stamped records.
Respond to Webhook	Outputs the final JSON.	Lets other apps or people call the endpoint and get the data.

When active, every minute this workflow generates output similar to:

{
  "city": "London",
  "temperature": 24,
  "condition": "Sunny",
  "humidity": 65,
  "wind": 14,
  "date": "2025-09-17 22:30:00"
}

5️⃣ Test It

Activate the workflow (toggle in the top right).
Use curl or a browser to hit the test URL shown in the “Respond to Webhook” node:
```
 curl http://:5678/webhook/
```
You’ll see fresh weather data each time you call it.

6️⃣ Fun Extensions

This simple example is just the start.
Here are some beginner-friendly ideas:

Log to a Database – Add a PostgreSQL or MySQL node to store each weather record.
Send Alerts – Add an Email or Slack node to notify if the temperature crosses a threshold.
Google Sheets Dashboard – Append each new data point to a sheet for easy charts.
Real API Calls – Replace the Random Weather function with an HTTP Request node calling a real API such as OpenWeatherMap.

7️⃣ Key Takeaways for Beginners

Visual First – You don’t need to be a developer to start; drag-and-drop gets you far.
Two Easy Installs – Docker for convenience, Node.js if you prefer native.
Reusable – The same workflow can run locally, in the cloud, or on a Raspberry Pi.

Understanding and Using race-lock-js: A Guide to Preventing Race Conditions

Nishikanta Ray — Fri, 25 Jul 2025 17:31:39 GMT

In the world of asynchronous programming with Node.js, managing concurrent operations can be a significant challenge. Race conditions, where the outcome of a program depends on the unpredictable sequence or timing of events, can lead to unexpected bugs and data corruption. This is where race-lock-js comes in – a lightweight, in-memory lock utility designed to help you safely coordinate asynchronous operations within a single Node.js process.

What is RaceLock JS?

race-lock-js (version 0.0.4) is a simple yet powerful library that provides an in-memory locking mechanism to prevent race conditions. It acts as a mutex, ensuring that only one operation can access a critical section of code at a time, thereby maintaining data integrity and predictable behavior in your asynchronous workflows.

Key Features:

Simple API: Easy-to-use start() and end() methods for acquiring and releasing locks.
Auto-release with Timeouts: Optional timeouts ensure locks are not held indefinitely.
Ownership Checks: Prevents unintended release of locks by different operations.
Exponential Backoff Retry: retryStart() offers a robust way to acquire locks under contention.
waitForUnlock(): Allows operations to pause and wait until a specific lock is released.
Metadata Support: Attach contextual information to your locks.
Introspection: Utilities like getLockCount(), getAllLockedKeys(), and getLockInfo() for monitoring.
Emergency Unlocking: forceUnlock() and clearAllLocks() for critical situations (use with caution).

Installation

Getting started with race-lock-js is straightforward. You can install it via npm:

Bash

npm install racelock

How to Use RaceLock JS: Examples and Demo Code

Let's dive into some practical examples to understand how to leverage race-lock-js in your applications.

First, import the library:

JavaScript

const RaceLock = require('racelock');
const lock = new RaceLock();

Basic Locking

This demonstrates how to acquire and release a lock for a simple asynchronous task.

JavaScript

async function performCriticalTask(taskId) {
    const lockKey = `task-${taskId}-lock`;

    // Try to acquire the lock
    if (lock.start(lockKey)) {
        try {
            console.log(`Task ${taskId}: Lock acquired for ${lockKey}. Performing critical operation...`);
            // Simulate an asynchronous operation
            await new Promise(resolve => setTimeout(resolve, 1000));
            console.log(`Task ${taskId}: Critical operation complete.`);
        } finally {
            // Always ensure the lock is released
            lock.end(lockKey);
            console.log(`Task ${taskId}: Lock released for ${lockKey}.`);
        }
    } else {
        console.log(`Task ${taskId}: Could not acquire lock for ${lockKey}. Already locked.`);
    }
}

// Simulate multiple tasks trying to access the same resource
performCriticalTask(1);
performCriticalTask(1); // This will likely fail to acquire the lock initially
performCriticalTask(2); // This will acquire a different lock

Asynchronous Task Protection with Timeouts

You can set a timeout for a lock to automatically release if it's held for too long.

JavaScript

async function sensitiveOperation(userId) {
    const lockKey = `user-${userId}-data`;
    const timeoutMs = 2000; // Lock will auto-release after 2 seconds

    if (lock.start(lockKey, timeoutMs, { userId: userId, operation: 'updateProfile' })) {
        try {
            console.log(`User ${userId}: Lock acquired with timeout. Updating profile...`);
            await new Promise(resolve => setTimeout(resolve, 1500)); // Simulate a task that finishes within timeout
            console.log(`User ${userId}: Profile updated successfully.`);
        } finally {
            lock.end(lockKey);
            console.log(`User ${userId}: Lock released.`);
        }
    } else {
        console.log(`User ${userId}: Failed to acquire lock for profile update.`);
    }
}

sensitiveOperation(123);
// If called again immediately, it might fail or wait for the timeout/release
sensitiveOperation(123);

Using `retryStart()` for Contention

retryStart() is excellent for scenarios where multiple operations might contend for the same lock. It retries acquiring the lock with an exponential backoff.

JavaScript

async function processOrder(orderId) {
    const lockKey = `order-${orderId}-processing`;
    const ownerId = `processor-${Math.random().toFixed(4)}`; // Unique ID for this attempt

    try {
        const acquired = await lock.retryStart(
            lockKey,
            5, // Number of attempts
            100, // Initial delay (ms)
            3000, // Timeout for each lock acquisition attempt (ms)
            { orderId: orderId, source: 'web' }, // Metadata
            ownerId
        );

        if (acquired) {
            console.log(`${ownerId} for Order ${orderId}: Lock acquired. Processing order...`);
            await new Promise(resolve => setTimeout(resolve, 2500)); // Simulate order processing
            console.log(`${ownerId} for Order ${orderId}: Order processed.`);
        } else {
            console.error(`${ownerId} for Order ${orderId}: Failed to acquire lock after multiple attempts.`);
        }
    } catch (error) {
        console.error(`${ownerId} for Order ${orderId}: Error during lock acquisition or processing:`, error.message);
    } finally {
        // Ensure lock is released by its owner
        if (lock.isLocked(lockKey) && lock.getLockInfo(lockKey)?.ownerId === ownerId) {
            lock.end(lockKey, ownerId);
            console.log(`${ownerId} for Order ${orderId}: Lock released.`);
        }
    }
}

// Simulate multiple attempts to process the same order
processOrder(101);
processOrder(101);
processOrder(102);

Waiting for a Lock to be Released with `waitForUnlock()`

If an operation needs to wait until a specific lock is free, waitForUnlock() is the perfect solution.

JavaScript

async function consumerProcess(dataKey) {
    console.log(`Consumer for ${dataKey}: Checking if lock is active...`);
    while (lock.isLocked(dataKey)) {
        console.log(`Consumer for ${dataKey}: Lock is active, waiting...`);
        await lock.waitForUnlock(dataKey);
    }
    console.log(`Consumer for ${dataKey}: Lock is no longer active. Proceeding with data processing.`);
    // Now you can safely access or modify the data
    await new Promise(resolve => setTimeout(resolve, 500));
    console.log(`Consumer for ${dataKey}: Data processing complete.`);
}

async function producerProcess(dataKey) {
    const ownerId = 'producer-A';
    if (lock.start(dataKey, 0, {}, ownerId)) {
        try {
            console.log(`Producer for ${dataKey}: Lock acquired. Producing data...`);
            await new Promise(resolve => setTimeout(resolve, 3000)); // Simulate data production
            console.log(`Producer for ${dataKey}: Data production complete.`);
        } finally {
            lock.end(dataKey, ownerId);
            console.log(`Producer for ${dataKey}: Lock released.`);
        }
    }
}

const sharedDataKey = 'mySharedResource';

// Start consumer first, it will wait
consumerProcess(sharedDataKey);
// Start producer after a short delay, it will acquire the lock
setTimeout(() => producerProcess(sharedDataKey), 500);

Best Practices for Using `race-lock-js`

Always Use finally Blocks: Ensure lock.end() is called within a finally block to guarantee lock release, even if errors occur.
Utilize ownerId: When multiple systems or functions might interact with the same lock key, use ownerId to enforce ownership and prevent accidental releases.
Employ retryStart() for Contention: If you anticipate contention for a lock, retryStart() provides a robust mechanism to acquire it gracefully.
Use clearAllLocks() with Extreme Caution: This function clears all active locks and should only be used in emergency scenarios or for testing, as it can disrupt ongoing operations.

License and Contributions

race-lock-js is open-source, licensed under the MIT License. Contributions are welcome! You can contribute by forking the repository, starring it, submitting pull requests, or opening issues on its GitHub repository.

For more details, you can visit the npm package page directly.

📦 Chunked File Upload Over TCP (Node.js net): Streams, Retries & Temp Storage

Nishikanta Ray — Fri, 18 Jul 2025 20:29:59 GMT

When you're building a desktop app that needs to upload large files (say 1GB+), sending the entire file at once is risky. Instead, split it into chunks and upload them one by one using streams.

This blog shows how to do that using Node.js's net module (TCP), how to handle stream retry issues, and how to simulate AWS S3 multipart upload behavior, with a focus on disk-based chunk storage, not in-memory.

🧩 What We’re Building

A net-based TCP file upload server
A client that reads a file chunk by chunk via fs.createReadStream
On each retry, it recreates the stream
Chunks are saved temporarily on disk
Finally, chunks are merged like AWS multipart upload

⚠️ Why Not Keep Chunks in Memory?

Holding large files or many chunks in RAM = 🧨 memory bloat
Disk-based temp files simulate real-world AWS S3 multipart flow:
- Upload → Store in temporary object → Finalize (CompleteMultipartUpload)

🛠 Step 1: The TCP Upload Server

// net-upload-server.js
const net = require('net');
const fs = require('fs');
const path = require('path');

const tempDir = path.join(__dirname, 'temp');
if (!fs.existsSync(tempDir)) fs.mkdirSync(tempDir);

let chunkIndex = 0;

const server = net.createServer((socket) => {
  const tempFile = path.join(tempDir, `chunk_${chunkIndex++}.part`);
  const writeStream = fs.createWriteStream(tempFile);

  socket.pipe(writeStream);

  socket.on('end', () => console.log(`✅ Chunk saved: ${tempFile}`));
  socket.on('error', (err) => console.error('❌ Socket error:', err.message));
});

server.listen(5000, () => {
  console.log('📡 Server running on port 5000');
});

📤 Step 2: Client – Chunk Upload with Retry

// net-upload-client.js
const fs = require('fs');
const net = require('net');

const CHUNK_SIZE = 10 * 1024 * 1024; // 10MB

function uploadChunk(filePath, start, end, attempt = 1) {
  return new Promise((resolve, reject) => {
    const stream = fs.createReadStream(filePath, { start, end });
    const client = net.createConnection({ port: 5000 }, () => {
      stream.pipe(client);
    });

    client.on('end', resolve);
    client.on('error', (err) => reject(err));
    stream.on('error', (err) => reject(err));
  });
}

async function uploadFile(filePath) {
  const fileSize = fs.statSync(filePath).size;
  let offset = 0;

  while (offset < fileSize) {
    const start = offset;
    const end = Math.min(offset + CHUNK_SIZE - 1, fileSize - 1);

    let retries = 3;
    while (retries--) {
      try {
        await uploadChunk(filePath, start, end);
        console.log(`✅ Chunk uploaded: ${start}-${end}`);
        break;
      } catch (err) {
        console.error(`❌ Retry failed: ${start}-${end}`, err.message);
        if (retries === 0) throw new Error('Upload failed');
        await new Promise(res => setTimeout(res, 1000));
      }
    }

    offset += CHUNK_SIZE;
  }
}

🧬 Step 3: Merge Chunks Like AWS `CompleteMultipartUpload`

// merge.js
const fs = require('fs');
const path = require('path');

const tempDir = path.join(__dirname, 'temp');
const finalPath = path.join(__dirname, 'final_upload.bin');

const files = fs.readdirSync(tempDir)
  .filter(f => f.endsWith('.part'))
  .sort(); // chunk_0.part, chunk_1.part...

const writeStream = fs.createWriteStream(finalPath);

for (const file of files) {
  const chunk = fs.readFileSync(path.join(tempDir, file));
  writeStream.write(chunk);
}

writeStream.end(() => {
  console.log(`✅ Final file merged at ${finalPath}`);
});

🔁 Retry Stream: Why It’s Crucial to Recreate It

Streams are one-time data pipelines. After they are read, errored, or ended:

They can’t be reused.
Retrying with the same stream = "Cannot pipe. Already used" or silent failure.
Always create a new stream for each retry.

✅ fs.createReadStream(file, { start, end }) inside retry loop
❌ Caching or reusing the stream across retries

🪣 AWS Multipart Upload Analogy

AWS Step	Local `net` Upload Equivalent
`UploadPart`	`fs.createReadStream()` + TCP send
`UploadPart failed`	Retry with new stream
`temp object on S3`	`.part` file saved in `temp/`
`CompleteMultipartUpload`	Merge `.part` files into final output

✅ Summary

Chunk large files using streams
Use Node.js net module to simulate raw transport
Always retry with new readable streams
Save chunks to disk to avoid memory spikes
Merge them at the end like AWS does

⚡️ Beyond the Browser: Mastering Electron's net Module for System-Level Networking

Nishikanta Ray — Fri, 20 Jun 2025 17:42:10 GMT

“Browser rules don’t apply here.”
Learn how Electron's net module gives your desktop app the networking power of system tools like curl, far beyond the limits of fetch or axios.

📦 Why Use Electron’s `net`? A Real-Life Analogy

Imagine you're at a hotel:

fetch is like calling the front desk — they’ll help, but only within hotel rules.
axios is like using a guest app — more features, but still limited by hotel policies (like asking for permission).
electron.net is like having a master key and a walkie-talkie to talk to staff directly — no restrictions, no waiting, and you can do whatever the system allows.

If you’re building Electron apps that need downloads, background sync, or CORS-free APIs, electron.net is your tool.

🌐 Meet the Players: `fetch`, `axios`, and `net`

Feature	`electron.net` (Main)	`axios` (Any)	`fetch` (Renderer)
CORS Restricted	❌ No	✅ Yes (in renderer)	✅ Yes
Runs in Main Process	✅ Yes	✅ Yes	❌ No
System-Level Access	✅ Yes	⚠️ No	❌ No
Proxy Control	✅ Full (setProxy)	⚠️ OS settings only	⚠️ OS settings only
Streaming Support	✅ Excellent	⚠️ Some support	❌ Limited
Ideal for Downloads	✅ Best	⚠️ Basic	❌ Poor
CORS-Free File Fetching	✅ Yes	❌ No (unless server allows)	❌ No
Saving Directly to Disk	✅ Yes (with `fs`)	⚠️ Manual	❌ Not possible
Automatic JSON Parsing	❌ No (manual)	✅ Yes	⚠️ No (must call `.json()`)
Ease of Use	⚠️ Low (low-level API)	✅ High	✅ High

🔧 How to Use Each — With Examples

✅ 1. Using `electron.net` (System-Level, No CORS, Download Capable)

✅ No CORS.
✅ Fully controllable.
✅ Ideal for download managers, auto-updaters, background sync.

// main.js
const { net, app, session } = require('electron');
const fs = require('fs');
const path = require('path');

app.whenReady().then(async () => {
  // Bypass all system proxies
  await session.defaultSession.setProxy({ proxyRules: 'direct://' });

  const filePath = path.join(__dirname, 'file.pdf');
  const fileStream = fs.createWriteStream(filePath);

  const request = net.request('https://example.com/file.pdf');
  request.on('response', (res) => {
    res.on('data', chunk => fileStream.write(chunk));
    res.on('end', () => {
      fileStream.end();
      console.log('✅ Download complete');
    });
  });

  request.end();
});

⚡ 2. Using `axios` (Great for JSON APIs, but CORS-limited)

const axios = require('axios');
axios.get('https://jsonplaceholder.typicode.com/todos/1')
  .then(response => console.log('✅ axios result:', response.data))
  .catch(error => console.error('❌ axios error:', error));

✅ Easy to use.
⚠️ Subject to CORS if used in renderer.
⚠️ Not ideal for large binary data or file downloads.

🌍 3. Using `fetch` (Browser-Like, but Restrictive)

✅ Native in the renderer.
⚠️ Blocked by CORS unless allowed by server.
❌ No file streaming or disk access.

🔓 How to Bypass Proxy in Electron

fetch('https://jsonplaceholder.typicode.com/todos/1')
  .then(res => res.json())
  .then(data => console.log('✅ fetch result:', data))
  .catch(err => console.error('❌ fetch error:', err));

🔥 Disable All Proxy with `session.setProxy`

This makes all requests direct, ignoring system proxies (like corporate firewalls or VPNs).

await session.defaultSession.setProxy({ proxyRules: 'direct://' });

🌐 Restore to System Proxy

await session.defaultSession.setProxy({ mode: 'system' });

You can also set custom proxy rules like:

await session.defaultSession.setProxy({
  proxyRules: 'http=my-proxy.com:8080'
});

💡 When to Use What?

Scenario	Use This
Download files	`electron.net`
Fetch public APIs (CORS OK)	`axios` or `fetch`
Access private/internal APIs	`electron.net`
Stream large data (video/audio)	`electron.net`
You need JSON, no CORS issues	`axios`
Frontend UI fetch	`fetch`

🧠 Final Thoughts

Electron’s net module is often overlooked, but it unlocks true desktop-level networking — with none of the browser baggage.

If you're serious about:

Creating an auto-updater
Managing downloads
Syncing background data
Bypassing CORS and proxy issues

...then net is your best friend.

🎯 Pro Tip: Use fetch or axios for simple frontend tasks, and delegate heavy or unrestricted networking to net in the main process.

🔐How JWT, Access Tokens & Refresh Tokens Work — Node.js vs AWS Lambda

Nishikanta Ray — Sun, 15 Jun 2025 18:19:11 GMT

🧠 What Are Access Tokens and Refresh Tokens?

Token Type	Purpose	Lifespan	Stored Where
Access Token	Grants access to protected resources	Short-lived (e.g., 15 min)	In memory or localStorage
Refresh Token	Gets a new access token when expires	Long-lived (e.g., 7 days)	Secure httpOnly cookie / DB

🎯 Real-Life Analogy: The Movie Hall Entry System

Imagine walking into a movie theater.

🎟️ At the entrance, you show your movie ticket to the guard — this is your Access Token.
It allows you to enter and enjoy the movie.
🕒 But the ticket is only valid for one movie (say 2 hours). If you want to watch another movie or re-enter after stepping out, you need a new ticket.
🤝 Instead of going to the main counter again and proving your identity (logging in), you carry a VIP pass or membership card (Refresh Token).
🎫 You present this refresh token at a special desk, and they issue you a new movie ticket (new Access Token) without requiring you to log in again.

🔐 Key Takeaway

Access Token = Movie Ticket
- Short-lived, used to access services
- Shown often (like at the theatre gate)
Refresh Token = Membership Card
- Long-lived, used to get new access tokens
- Hidden and securely stored

🔐 JWT Authentication Flow with Access + Refresh Tokens

User logs in ⇒ Receives both tokens
An access token is used to call protected APIs
If the access token expires, the client sends the refresh token to get a new access token
Refresh token is stored securely (e.g., in cookies)
If the refresh token is invalid or expired, ⇒ user must log in again

🏗️ Implementation in Node.js (Express)

📦 Install

npm install express jsonwebtoken cookie-parser

🔐 Token Functions (`auth.js`)

const jwt = require("jsonwebtoken");

const ACCESS_SECRET = "access-secret";
const REFRESH_SECRET = "refresh-secret";

function generateTokens(user) {
  const accessToken = jwt.sign(user, ACCESS_SECRET, { expiresIn: "15m" });
  const refreshToken = jwt.sign(user, REFRESH_SECRET, { expiresIn: "7d" });
  return { accessToken, refreshToken };
}

function verifyAccess(token) {
  return jwt.verify(token, ACCESS_SECRET);
}

function verifyRefresh(token) {
  return jwt.verify(token, REFRESH_SECRET);
}

module.exports = { generateTokens, verifyAccess, verifyRefresh };

🧠 Express Server (`index.js`)

const express = require("express");
const cookieParser = require("cookie-parser");
const { generateTokens, verifyAccess, verifyRefresh } = require("./auth");

const app = express();
app.use(express.json());
app.use(cookieParser());

app.post("/login", (req, res) => {
  const user = { email: req.body.email };
  const { accessToken, refreshToken } = generateTokens(user);
  res.cookie("refreshToken", refreshToken, { httpOnly: true });
  res.json({ accessToken });
});

app.get("/protected", (req, res) => {
  const auth = req.headers.authorization;
  if (!auth) return res.sendStatus(401);
  try {
    const user = verifyAccess(auth.split(" ")[1]);
    res.json({ message: "Access granted", user });
  } catch {
    res.status(403).json({ message: "Access token expired" });
  }
});

app.post("/refresh", (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.sendStatus(401);
  try {
    const user = verifyRefresh(refreshToken);
    const { accessToken } = generateTokens(user);
    res.json({ accessToken });
  } catch {
    res.status(403).json({ message: "Refresh token invalid" });
  }
});

🚀 JWT with Refresh Token in AWS Lambda

Lambda is stateless — so no sessions! But you can use JWTs the same way.

🗂️ Structure

pythonCopyEditlambda-jwt-auth/
├── handler.js
├── auth.js

🔐 `auth.js` (Same logic as Express)

const jwt = require("jsonwebtoken");
const ACCESS_SECRET = "access-secret";
const REFRESH_SECRET = "refresh-secret";

function generateTokens(user) {
  const accessToken = jwt.sign(user, ACCESS_SECRET, { expiresIn: "15m" });
  const refreshToken = jwt.sign(user, REFRESH_SECRET, { expiresIn: "7d" });
  return { accessToken, refreshToken };
}

function verifyAccess(token) {
  return jwt.verify(token, ACCESS_SECRET);
}

function verifyRefresh(token) {
  return jwt.verify(token, REFRESH_SECRET);
}

module.exports = { generateTokens, verifyAccess, verifyRefresh };

🧠 `handler.js`

const { generateTokens, verifyAccess, verifyRefresh } = require("./auth");

exports.login = async (event) => {
  const body = JSON.parse(event.body);
  const user = { email: body.email };
  const { accessToken, refreshToken } = generateTokens(user);

  return {
    statusCode: 200,
    headers: {
      "Set-Cookie": `refreshToken=${refreshToken}; HttpOnly; Path=/; Max-Age=604800`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ accessToken }),
  };
};

exports.protected = async (event) => {
  const authHeader = event.headers.authorization;
  try {
    const user = verifyAccess(authHeader.split(" ")[1]);
    return {
      statusCode: 200,
      body: JSON.stringify({ message: "Access granted", user }),
    };
  } catch {
    return { statusCode: 403, body: JSON.stringify({ error: "Token expired" }) };
  }
};

exports.refresh = async (event) => {
  const cookie = event.headers.cookie || "";
  const token = cookie.split("refreshToken=")[1];
  try {
    const user = verifyRefresh(token);
    const { accessToken } = generateTokens(user);
    return {
      statusCode: 200,
      body: JSON.stringify({ accessToken }),
    };
  } catch {
    return { statusCode: 403, body: JSON.stringify({ error: "Refresh token invalid" }) };
  }
};

📊 Node.js Server vs AWS Lambda (with Refresh Token)

Feature	Node.js + JWT + Refresh Token	AWS Lambda + API Gateway + JWT
Token Handling	In memory or a cookie	Via API Gateway headers/cookies
Refresh Logic	Simple via cookie	Cookie needs to be manually parsed
Storage Option	Can use Redis for refresh token blacklist	Store tokens in DB or skip blacklist
Deployment	Runs continuously	Cold start but lower cost
Use Case	Complex backend apps	Scalable microservices, low-traffic auth

🧠 Summary

Access tokens are short-lived and used to access protected resources.
Refresh tokens are long-lived and used to generate new access tokens without login.
JWTs help us implement stateless authentication in both Node.js servers and AWS Lambda functions.
Store refresh tokens securely (e.g., httpOnly cookies) and never expose them on the frontend.

🛡️ Protect Your GitHub Token: Proxying Private Releases for Electron Apps

Nishikanta Ray — Fri, 23 May 2025 20:21:18 GMT

When building apps that use GitHub Releases to distribute updates (e.g., via Electron), things are straightforward if your repo is public. But for private GitHub repos, there's a problem:

⚠️ You can’t directly expose the GitHub Release URL to your app without leaking your GitHub token.

In this post, we’ll walk through how to securely proxy GitHub Release downloads through your own server, so that your token stays hidden while your app can still download updates.

🚩 Why You Can’t Use the GitHub URL Directly

GitHub requires authentication for private releases. That means you need to include an Authorization header with a personal access token (PAT):

Authorization: token ghp_123abc...

Including this directly in your frontend or Electron app would be a huge security risk, since users could extract the token and access your private repo.

✅ The Secure Approach: Use a Proxy Server

Instead of downloading from GitHub directly, you set up a backend server that:

Authenticates with GitHub using your token
Downloads the release asset
Proxies the file to the requesting client (your app)

This way, only your server knows the token — the app just talks to your proxy.

🛠 Step-by-Step: Proxy Setup

1. Create a GitHub Token

Go to GitHub Developer Settings
Create a classic token with:
- repo scope (for private repositories)
- read:packages (if you're using GitHub Packages too)

Save this token in your backend as an environment variable, e.g., GH_TOKEN.

2. Create the Proxy Endpoint

Here’s a full example using Node.js (Express or similar):

// downloadProxy.js
const fetch = require("node-fetch");

const GITHUB_OWNER = "your-org-or-username";
const GITHUB_REPO = "your-repo";
const GH_TOKEN = process.env.GH_TOKEN;

const headers = {
  Authorization: `token ${GH_TOKEN}`,
  "User-Agent": "SecureReleaseProxy",
  Accept: "application/vnd.github.v3+json"
};

async function getLatestRelease() {
  const res = await fetch(`https://api.github.com/repos/${GITHUB_OWNER}/${GITHUB_REPO}/releases/latest`, { headers });
  if (!res.ok) throw new Error("Failed to fetch latest release");
  return await res.json();
}

async function getAssetDownloadUrl(assetName) {
  const release = await getLatestRelease();
  const asset = release.assets.find(a => a.name === assetName);
  if (!asset) throw new Error(`Asset ${assetName} not found`);
  return asset.url; // This is the API URL, not a direct download link
}

async function proxyAssetDownload(req, res) {
  try {
    const { filename } = req.params;
    const assetApiUrl = await getAssetDownloadUrl(filename);

    const githubRes = await fetch(assetApiUrl, {
      headers: {
        ...headers,
        Accept: "application/octet-stream"
      }
    });

    if (!githubRes.ok) {
      res.status(500).send("Error fetching asset");
      return;
    }

    res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
    res.setHeader("Content-Type", "application/octet-stream");

    githubRes.body.pipe(res);
  } catch (err) {
    console.error("Proxy error:", err);
    res.status(500).send("Proxy error");
  }
}

module.exports = { proxyAssetDownload };

3. Add the Express Route

In your main server file:

const express = require("express");
const { proxyAssetDownload } = require("./downloadProxy");

const app = express();
const PORT = 3200;

app.get("/updates/download/:filename", proxyAssetDownload);

app.listen(PORT, () => {
  console.log(`Proxy server listening on http://localhost:${PORT}`);
});

4. Configure Electron Auto-Updater

In your Electron app (using electron-updater), point to your proxy instead of GitHub:

{
  "publish": [
    {
      "provider": "generic",
      "url": "http://localhost:3200/updates"
    }
  ]
}

Your latest.yml file should also have URLs that match your proxy endpoint:

version: 1.0.0
files:
  - url: Lets-Flo-Desktop-1.0.0-mac.zip
    sha512: abc123...
    size: 12345678
path: Lets-Flo-Desktop-1.0.0-mac.zip
sha512: abc123...
releaseDate: '2025-05-24T08:00:00.000Z'

🔐 Security Best Practices

Store the GH_TOKEN only on your backend
Set strict scopes (no write, delete, or admin)
Use environment variables, not hardcoded strings
Add rate limiting / IP restrictions if possible

💡 Bonus: Cache the Release Info

To reduce GitHub API calls, you can cache the latest release metadata in memory or Redis and refresh it every X minutes.

✅ Summary

Step	What You Do
Create GH token	With `repo` access only
Setup proxy server	Download and stream release via backend
Use Electron `generic`	Point to your server instead of GitHub
Hide token	Never expose token to frontend/app

By proxying downloads through a secure server, you protect your GitHub credentials while still delivering updates seamlessly to your users.

NishikantaRay

We Let an AI Break Our Analytics Platform — Here's Every Bug It Found

Executive Summary

Part 1: The Application — InsightTrack

All 17 Pages Under Test

Part 2: Why Passmark

The Maintenance Problem With Traditional E2E Tests

What Passmark Does Differently

How the AI Pipeline Works

Part 3: How We Built the Test Suite

Repository Structure

playwright.config.ts — The Configuration That Drives Everything

.env Configuration

The Auth Helper — The Pattern That Makes Every Dashboard Test Fast

Mixing Raw Playwright With AI Steps

Part 4: All 52 Tests — What Each One Checks

tests/auth/login.spec.ts — 5 Tests

tests/auth/register.spec.ts — 4 Tests

tests/public/landing.spec.ts — 3 Tests

tests/dashboard/dashboard.spec.ts — 6 Tests

tests/dashboard/analytics-sections.spec.ts — 9 Tests

tests/dashboard/realtime.spec.ts — 4 Tests

tests/dashboard/pages.spec.ts — 3 Tests

tests/dashboard/funnels.spec.ts — 3 Tests

tests/dashboard/settings.spec.ts — 4 Tests

Step 2: Create Translation Files

English Translation

French Translation

Step 3: JavaScript Translation Engine

Step 4: Language Switching

Step 5: Saving Language Preference

Auto Load Language on Page Start

Step 6: Translating Attributes

Performance Considerations

Lazy loading languages

Caching translations

Preloading common languages

Advantages of the data-i18n Approach

Simple implementation

Clean HTML

Lightweight

Easy to maintain

Flexible

Limitations

No pluralization rules

No date or number formatting

No nested translations

When to Use a Full i18n Library

Example Use Cases

Conclusion

Tauri vs Electron: The Complete Developer’s Guide (2026)

What is Tauri?

Core Idea

Key Characteristics

What is Electron?

Core Idea

Key Characteristics

The Fundamental Architectural Difference

What This Means in Practice

Developer Experience: How Apps Are Structured

Tauri Structure

Electron Structure

IPC: Talking Between Frontend and Backend

Tauri Example

Electron Example

Performance: Real-World Differences

Bundle Size

Memory Usage

Startup Speed

Processing Speed

Security Model

Tauri: Capability-Based Security

Electron: Process Isolation

Ecosystem & Maturity

When Should You Choose Tauri?

When Should You Choose Electron?

Migration: Electron → Tauri

Final Verdict

Production-Grade Prompting with the Anthropic API

Concepts, Parameters, Streaming, Caching, and a Real Enterprise Example

`playwright.config.ts` — The Configuration That Drives Everything

`.env` Configuration

`tests/auth/login.spec.ts` — 5 Tests

`tests/auth/register.spec.ts` — 4 Tests

`tests/public/landing.spec.ts` — 3 Tests

`tests/dashboard/dashboard.spec.ts` — 6 Tests

`tests/dashboard/analytics-sections.spec.ts` — 9 Tests

`tests/dashboard/realtime.spec.ts` — 4 Tests

`tests/dashboard/pages.spec.ts` — 3 Tests

`tests/dashboard/funnels.spec.ts` — 3 Tests

`tests/dashboard/settings.spec.ts` — 4 Tests

Advantages of the `data-i18n` Approach

8. Prompt Caching and `cache_control`

9. `cache_control: { type: "ephemeral" }`