ImageTools Hub

Free, privacy-friendly image utilities built with Next.js (App Router), TypeScript, and Tailwind CSS. All processing runs locally in the browser with the Canvas API — no images are ever uploaded to a server.

Tools

Tool	URL
Image Compressor	/tools/image-compressor
Image Resizer	/tools/image-resizer
Image Converter	/tools/image-converter
Image Cropper	/tools/image-cropper
Favicon Generator	/tools/favicon-generator
Image to Base64	/tools/image-to-base64

Getting started

npm install
cp env.example .env.local   # then edit values
npm run dev                 # http://localhost:3000

Note: .npmrc points at registry.npmmirror.com because registry.npmjs.org was unreachable/extremely slow from this network. Delete that file to use the default registry.

Scripts

Command	Purpose
npm run dev	Start the dev server
npm run build	Production build
npm start	Serve the production build
npm run lint	ESLint
npm run typecheck	tsc --noEmit
npm test	Unit tests (Vitest) for the image-processing library
npm run test:e2e	Playwright end-to-end tests (desktop/tablet/mobile)

E2E tests need browsers once: npx playwright install chromium, and a production build first (npm run build).

Environment variables

See env.example. In production (e.g. Vercel project settings → Environment Variables):

Variable	Required	Purpose
NEXT_PUBLIC_SITE_URL	Yes	Canonical origin for metadata, sitemap, robots
NEXT_PUBLIC_CONTACT_EMAIL	Yes	Shown on contact page / privacy policy
NEXT_PUBLIC_ADSENSE_CLIENT	After approval	ca-pub-* publisher ID — gates ALL ad code
NEXT_PUBLIC_ADSENSE_SLOT_*	After approval	Ad unit slot IDs per placement

No ad code is emitted unless NEXT_PUBLIC_ADSENSE_CLIENT is a real ca-pub- ID, so the site ships "ads off" by default.

AdSense setup checklist (manual, after approval)

1. Apply for AdSense with the production domain; wait for approval. Approval is not guaranteed — see "Known limitations" below.
2. Set NEXT_PUBLIC_ADSENSE_CLIENT to your ca-pub-* ID and redeploy — this activates the loader script and generates /ads.txt with the matching publisher ID automatically.
3. Create ad units → copy slot IDs into NEXT_PUBLIC_ADSENSE_SLOT_* env vars; redeploy. (Or enable "Auto ads" in the AdSense dashboard and skip slot IDs entirely.)
4. Configure consent messaging (AdSense → Privacy & messaging) if serving EEA/UK traffic.

Deploying to Vercel

1. Push this repo to GitHub.
2. Import the project in Vercel (framework preset: Next.js — detected automatically).
3. Set NEXT_PUBLIC_SITE_URL to the production domain and NEXT_PUBLIC_CONTACT_EMAIL.
4. Deploy. Verify https://<domain>/sitemap.xml and /robots.txt, then submit the domain in Google Search Console.

Any static-friendly Next.js host works the same way: npm run build, then serve with npm start behind your usual proxy/process manager.

Rollback

• Vercel: Deployments → pick the previous production deployment → "Promote to Production" (instant, no rebuild needed).
• Self-hosted: keep the previous release's .next directory (or the previous git tag) and restart npm start from it.
• Git: git revert the offending commits and redeploy — the site is fully static apart from /ads.txt, so there is no database or state to roll back.

SEO checklist

• Unique <title> and meta description per page
• Self-referencing canonical URLs from NEXT_PUBLIC_SITE_URL
• sitemap.xml with all indexable routes
• robots.txt pointing at the sitemap
• Open Graph + Twitter card metadata, generated OG image
• JSON-LD (WebSite, WebApplication, FAQPage schemas)
• Favicon (/icon.svg) and web manifest
• Branded 404 page; unknown tool slugs return real 404s
• Internal links between related tools
• Unique intro + FAQ copy on every tool page
• Set NEXT_PUBLIC_SITE_URL to the final production domain
• Submit sitemap in Google Search Console
• AdSense application (after domain is live)

Project structure

src/
  app/                 # routes: /, /tools/[slug], legal pages, sitemap,
                       # robots, manifest, icon, opengraph-image, ads.txt
  components/          # header, footer, cards, ad slot, shared tool page
  components/tools/    # per-tool client components + shared UI
                       # (dropzone, previews, result card, form controls)
  lib/image/           # image pipeline: magic-byte sniffing, decode,
                       # resize/crop math, canvas encode, ICO & ZIP writers
  lib/tools.ts         # tool registry: slugs, copy, FAQs, related links
e2e/                   # Playwright specs + a tiny PNG fixture encoder

How processing works

• Uploads are validated by magic bytes (never by filename) and by an actual decode via createImageBitmap — corrupted files and fake extensions are rejected before any processing.
• Raster work uses Canvas 2D: drawImage for resize/crop, toBlob for encoding. PNG/WebP outputs keep alpha; JPEG flattens transparency onto a background color with a warning shown first.
• The favicon ICO is a hand-rolled container (PNG entries at 16/32/48 px); the "download all" ZIP uses the STORE method — both written by small, unit-tested encoders in src/lib/image/.
• Limits: 40 MB per file, ~80 MP decoded, canvas side ≤ 16384 px, and the Base64 tool caps input at 8 MB (text output grows ~33%).
• Object URLs and decoded bitmaps are released when images are replaced or components unmount.

Known limitations

• Output formats are PNG, JPEG, WebP — the three formats every browser can encode natively. No AVIF/GIF/TIFF output.
• Animated GIFs decode to their first frame (no animation support).
• SVG inputs are rasterized at their intrinsic size (or the browser's default when the SVG has none).
• AVIF/HEIC decoding depends on the browser — Chrome/Firefox handle AVIF; HEIC generally needs Safari.
• PNG "compression" is a lossless re-encode that often can't beat an already-optimized file — the compressor reports the true result and suggests WebP/JPEG instead.
• Large images can still be slow on low-memory devices; the limits above keep the browser from exhausting memory but encode time varies.
• AdSense approval is not guaranteed — ads are fully implemented but dormant until a real ca-pub-* ID is configured.

Unfinished / future work

• Background remover — planned. Two candidate approaches, both keeping processing client-side: an in-browser ML model (e.g. @imgly/background-removal, ~40MB one-time download, handles complex backgrounds) or a dependency-free edge flood-fill for solid backgrounds.
• Additional tools on the same scaffolding (e.g. EXIF viewer, palette extractor, image-to-ASCII) — the registry + shared components make new tools cheap to add.
• Client-side EXIF stripping toggle (canvas already drops metadata by default).
• Premium features (batch processing, presets) can layer on later; none are implemented now.