I Built a Type-Safe JSON-LD Generator for Next.js to Automate SEO

Mehmet — Mon, 22 Dec 2025 00:14:48 +0000

The Problem

When building hemenhesap.com - a Turkish financial calculator platform with 100+ calculator pages - I needed structured data for every page. Existing solutions were either:

Too verbose: next-seo requires tons of boilerplate for simple schemas.
Not type-safe: It's extremely easy to make syntax mistakes in complex JSON-LD objects.
Missing schemas: Hard to find lightweight builders for SoftwareApplication (Calculator) or HowTo schemas.

The Solution

I built nextjs-jsonld-schema - a lightweight, type-safe JSON-LD builder specifically designed for Next.js (App & Pages Router).

Features

🎯 Full TypeScript support: Autocomplete and type checking for all schema fields.
🚀 Framework Ready: Works perfectly with Next.js App Router and Metadata API.
📊 Google-Compliant: Generates structured data that passes Google's Rich Results Test.
🪶 Zero Dependencies: No extra bloat for your project.

Quick Example

import { buildCalculatorSchema, SchemaScript } from 'nextjs-jsonld-schema';

const schema = buildCalculatorSchema({
  siteUrl: "https://hemenhesap.com",
  url: "/hesap/kredi-hesaplama",
  title: "Loan Calculator",
  description: "Calculate your monthly payments instantly.",
  howtoSteps: [
    { title: "Enter amount", description: "Input your total loan amount." },
    { title: "Calculate", description: "Click the button to see the results." },
  ],
  faq: [
    { question: "Is it free?", answer: "Yes, all tools are 100% free!" },
  ],
});

// Just drop this into your component
<SchemaScript schema={schema} />

Supported Schema Types

Builder	Schema Type
`buildWebsiteSchema()`	WebSite + Organization
`buildCalculatorSchema()`	SoftwareApplication + HowTo + FAQ
`buildBlogPostSchema()`	BlogPosting + Article
`buildFAQSchema()`	FAQPage
`buildBreadcrumbSchema()`	BreadcrumbList

Results

After implementing this on hemenhesap.com:

✅ Rich snippets appearing in Google Search
✅ FAQ dropdowns increasing CTR in search results
✅ HowTo steps showing up in mobile SERPs

Try It

npm install nextjs-jsonld-schema

📦 NPM: https://www.npmjs.com/package/nextjs-jsonld-schema

🐙 GitHub: https://github.com/Aghefendi/nextjs-jsonld-schema

Feedback and contributions welcome!

Built with ❤️ for the Next.js community

Next.js 14 ile Finansal Hesaplama Motoru Geliştirmek: Hemen Hesap Mimarisi

Mehmet — Thu, 11 Dec 2025 22:34:47 +0000

Neden Yeni Bir Hesaplama Motoru?👋

inansal okuryazarlık, karmaşık vergi mevzuatları ve sürekli değişen oranlar arasında kaybolabiliyor. Hemen Hesap, Türkiye’deki güncel vergi, maaş ve finansal hesaplamaları herkes için erişilebilir ve anlaşılır kılmak amacıyla başlattığım bir proje.
Amacım sadece "bir form doldur, sonucu gör" uygulaması yapmak değil; SOLID prensiplerine uyan, test edilebilir ve SEO odaklı modern bir hesaplama motoru inşa etmekti.
Bu yazıda, HemenHesap.com'un mimarisinden algoritmalarına, SEO stratejisinden test süreçlerine kadar mutfaktaki teknik detayları paylaşacağım.
1. Teknoloji Yığını ve Mimari 🏗️
Projenin temelinde performans, tip güvenliği ve ölçeklenebilirlik yatıyor.

1.1. Core Stack

Next.js 14 (App Router): Projenin omurgası. SSR (Server-Side Rendering) ve SSG (Static Site Generation) yetenekleri sayesinde hem SEO dostu hem de şimşek hızında sayfalar oluşturduk.
TypeScript: Finansal hesaplamalarda number ile string karışıklığına yer yok. Tamamı tip güvenli (Type-safe) bir yapı kurduk.
React 18: Server ve Client component ayrımı ile hidrasyon (hydration) maliyetlerini minimize ettik.

1.2. UI/UX
Tailwind CSS 3.4: Hızlı prototipleme ve tutarlı tasarım sistemi.

Lucide React: Hafif ikon seti.

Atomic Design: InputGroup, SelectGroup, ResultCard gibi yeniden kullanılabilir, izole bileşenler.

1.3. Klasör Yapısı
Proje, modülerliği korumak adına özellik tabanlı bir yapıya sahip:

src/
├── app/ # Next.js App Router (Sayfalar)
├── components/ # UI Bileşenleri (Button, Input vb.)
│ └── calculators/ # Hesaplama mantığını içeren bileşenler
├── lib/ # Algoritmalar ve Helper fonksiyonlar
├── types/ # TypeScript interface tanımları
data/ # Oranlar, vergi dilimleri (JSON)

2. Hesaplama Algoritmaları ve İş Kuralları

Bu projenin kalbi src/lib/engines altında atıyor. Her hesaplama aracı (KDV, Maaş, MTV) kendi izole motoruna sahip.

2.1. JavaScript ve Matematiksel Doğruluk

Bildiğiniz gibi JavaScript'te 0.1 + 0.2 !== 0.3 sorunu vardır. Finansal işlemlerde kuruş hatası kabul edilemez. Bu yüzden özel bir Akıllı Yuvarlama (smartRound) mekanizması geliştirdik.

// Basitleştirilmiş örnek export const smartRound = (num: number, decimals: number = 2): number => { const factor = Math.pow(10, decimals); return Math.round((num + Number.EPSILON) * factor) / factor; };

2.2. Hesaplama Motorları

KDV Hesaplama: Dahil/Hariç dönüşümleri.
Gelir Vergisi: 2025 kümülatif matrah takibi.
Maaş Hesaplama: Brüt/Net döngüsü ve SGK tavan kontrolü.
Kıdem Tazminatı: Tavan ücret ve giydirilmiş ücret analizi.

Tüm bu motorlar, verilerini veritabanı yerine performans için Statik JSON dosyalarından (data/) çeker. Bu sayede vergi oranları değiştiğinde sadece JSON'ı güncellemek yeterlidir.
3. SEO Stratejisi: Google Bizi Nasıl Görüyor?

Finansal araçlarda rekabet yüksek. Teknik SEO ile fark yarattık.

{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "KDV Hesaplama Aracı",
"applicationCategory": "FinanceApplication",
"operatingSystem": "Web Browser"
}

Ayrıca BreadcrumbList ve Bloglar için BlogPosting şemaları dinamik olarak üretiliyor.

3.2. Teknik Detaylar

Dinamik Metadata: Her hesaplama sayfası için özel title ve description.
Sitemap: sitemap.ts ile her build işleminde otomatik güncellenen harita.
İç Linkleme: Hesaplayıcılar ve blog yazıları arasında anlamsal bağlar.

4. Test ve Kalite Güvencesi (QA)

Vitest: Jest'e göre daha hızlı olduğu için tercih ettik.
Kapsam: Hesaplama fonksiyonlarının %100'ü birim testlerden (Unit Test) geçiyor. Şu an 51 farklı senaryo her commit öncesi test ediliyor.
ErrorBoundary: React tarafında olası bir çökmede (örn: API hatası) kullanıcının beyaz ekran görmesini engelleyip, anlamlı bir hata mesajı gösteriyoruz.

5. Performans

Statik Önbellekleme (SSG): Hesaplama sayfalarının iskeleti build anında oluşturulur.
Lazy Loading: Kullanıcı "Maaş Hesaplama" sayfasındaysa, "MTV Hesaplama" kodları tarayıcıya indirilmez (Code Splitting).
Bundle Size: bundle-analyzer ile paket boyutunu sürekli optimize ediyoruz.

6. Sonuç ve Yol Haritası

Hemen Hesap, modern web teknolojilerinin finansal araçlara nasıl entegre edilebileceğinin canlı bir örneği oldu.

Gelecek Planları:

📄 Hesaplama sonuçlarının PDF olarak indirilmesi.
🌍 Çoklu dil desteği (Döviz çevirici için).
🔌 Public API (Diğer geliştiricilerin kullanması için).

Bu teknik yolculukta edindiğim tecrübeleri paylaşmaya devam edeceğim. Projeyi incelemek isterseniz:hemenhesap.com

Kodla kalın, hatasız hesaplayın! 👨‍💻

Forem: Mehmet