GSoC 2026’da Node.js’nin Temel Araçlarına Katkı Sağlamak

Google Summer of Code (GSoC) 2026 programının ortalarına gelindiğinde, birçok geliştirici gibi ben de zamanın ne kadar hızlı geçtiğine şaşkınlıkla bakıyordum. Özellikle Abstract Syntax Tree (AST) analizcileri, meta veri çıkarma ve mimari kararlar üzerinde çalışırken, saatlerin nasıl akıp gittiğini daha iyi anladım.

Bu dönemde, Webpack dokümantasyonunu yeniden tasarlama projesinin bir parçası olarak blog sistemini inşa etmek gibi görünüşte basit bir görevi üstlendim. İlk bakışta, sadece bir sayfa oluşturulması, birkaç Markdown dosyasının düzenlenmesi ve bunların derlenmesi gerekiyordu. Ancak büyük ölçekli açık kaynak ekosistemlerinde hiçbir şey gerçekten "basit" değildir. İlk engeli, mimari bir karar almadan hemen önce karşımıza çıktı: meta veri aktarımı.

Meta Verilerin Dönüşümü: Egoizmden Ekosisteme Geçiş

Blog sisteminin temelinde meta veriler bulunur: yazar isimleri, yayın tarihleri ve kategoriler. Node.js’nin çekirdek dokümantasyon motoru olan nodejs/doc-kit üzerinde çalışırken, meta verilerin halihazırda HTML yorum satırlarıyla tanımlandığını gördüm. Oysa modern endüstrinin standartları YAML Frontmatter adı verilen bir yapıyı benimsemiş durumda:

authors: moshams272
date: 2026-07-15
category: teknik

Bu noktada iki yol vardı: ya webpack-doc-kit içinde hızlı bir şekilde YAML çözümleyici ekleyip işi bitirecektim, ya da ekosistemin tamamını düşünerek kökten bir çözüm üretecektim.

Karar: Kendi projem için geçici çözümler yerine, evrensel bir standart oluşturmaya odaklandım. Bunun için, YAML bloklarını AST oluşumundan önce eski formata dönüştüren hafif bir ön-AST yer değiştirme stratejisi geliştirdim:

const QUERIES = {
  standardYamlFrontmatter: /^---\r?\n([\s\S]*?)\r?\n---/,
};

content.replace(
  QUERIES.standardYamlFrontmatter,
  (_, yaml) => `<!-- YAML
${yaml}
-->
`
);

Bu yaklaşım, mevcut Node.js dokümantasyonlarının %100 geriye dönük uyumluluğunu korurken, webpack-doc-kit ve gelecekteki kullanıcılar için modern YAML desteklerini etkinleştirdi. Sonuç olarak, doc-kit PR #700 ile bu iyileştirme ana depoya dahil edildi.

Statik Kaynakların Yönetimi: Güvenlik ve Performans Dengesi

Blog sisteminin olmazsa olmazlarından biri de resimler ve kapak görselleridir. Ancak nodejs/doc-kit Statik Site Üretimi (SSG) modeline geçiş yaptığı için yerel Markdown dosyalarındaki resimler otomatik olarak kopyalanmıyordu. Kolay yol, webpack-doc-kit içinde basit bir komut dosyası yazmaktı. Fakat ekosistem odaklı düşünerek, doğrudan nodejs/doc-kit içinde çözüm aramaya karar verdim.

Bu karar, geliştiriciler arasında derin bir tartışma başlattı: Statik kaynakların otomatik olarak kopyalanması mı gerekiyor, yoksa kullanıcıların elle belirlediği klasörler mi tercih edilmeli? Güvenlik, performans ve Astro gibi araçlardaki yaygın uygulamalar göz önünde bulunduruldu.

Sonuçta, Web Üretici’ye pathsToCopy adlı yeni bir yapılandırması eklendi. Bu özellik, hem dizeleri hem de nesne haritalarını destekleyecek şekilde tasarlandı. Ayrıca dosya kopyalama işlemlerinde oluşabilecek hatalara karşı da koruma sağlandı:

import { cp } from 'node:fs/promises';
import { join, basename } from 'node:path';
import logger from '../../../logger/index.mjs';

/**
 * `pathsToCopy` içinde tanımlanan statik dizin/dosyaları çıktı dizinine kopyalar.
 * @param {import('../types').Configuration} config
 */
export async function copyStaticAssets(config) {
  if (Array.isArray(config.pathsToCopy)) {
    for (const item of config.pathsToCopy) {
      if (!item) continue;

      const copyTasks = typeof item === 'string'
        ? [{ src: item, dest: join(config.output, basename(item)) }]
        : Object.entries(item).map(([src, dest]) => ({
            src,
            dest: join(config.output, dest.replace(/^[/\\]+/, '')),
          }));

      for (const { src, dest } of copyTasks) {
        try {
          await cp(src, dest, { recursive: true, force: true });
        } catch (err) {
          if (err.code !== 'ENOENT') {
            logger.error(
              `[web-generator] ${src} konumundan ${dest} konumuna kopyalama başarısız: ${err.message}`
            );
          }
        }
      }
    }
  }
}

Bu iyileştirme, doc-kit issue #748 ve ardından gelen PR #753 ile ana depoya dahil edildi.

Webpack Blog’unun Tamamlanması: Lego Parçalarından Bir Sistem

Node.js’nin çekirdek araçlarına yapılan bu iyileştirmeler sayesinde, Webpack blog sistemini inşa etmek artık bir Lego setini bir araya getirmek kadar basit hale geldi. Öncelikle, blog gönderilerini sıralayan ve site.json dosyasını üreten bir veri hattı oluşturuldu. Ardından, hem fareyle üzerine gelindiğinde etkileşimli olan hem de GitHub avatarlarını içeren özel BlogCard bileşeni tasarlandı. Son olarak, tüm bu bileşenler Webpack’in küresel kenar çubuğu ve gezinme çubuğuyla sorunsuz bir şekilde entegre edildi.

Tüm bu gelişmeler, mentörlerimin rehberliğinde gerçekleştirildi ve sonuç olarak webpack-doc-kit PR #139 ile ana depoya dahil edildi. Aşağıda, blog sisteminin veri hattını oluşturmak için kullanılan temel fonksiyonlardan biri yer alıyor:

import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import matter from 'gray-matter';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
const POSTS_DIR = join(ROOT, 'pages', 'blog', 'posts');
const OUTPUT = join(ROOT, 'generated', 'blog.json');

const toAuthors = data => {
  const value = data.authors ?? data.author;
  if (Array.isArray(value)) return value.map(String);
  if (value == null) return [];
  return [String(value)];
};

const titleFromBody = body =>
  body.match(/^#\s+(.+)$/m)?.[1].trim() ?? null;

const readPosts = async () => {
  const entries = await readdir(POSTS_DIR);
  const files = entries.filter(name => name.endsWith('.md'));

  const posts = await Promise.all(
    files.map(async file => {
      const slug = file.replace(/\.md$/, '');
      const { data, content } = matter(
        await readFile(join(POSTS_DIR, file), 'utf8')
      );

      return {
        slug,
        title: titleFromBody(content) ?? slug,
        authors: toAuthors(data),
        date: new Date(data.date).toISOString(),
        category: data.category ?? null,
        image: data.image ?? null,
        ...(data.description && { description: data.description }),
      };
    })
  );

  return posts.sort((a, b) => new Date(b.date) - new Date(a.date));
};

Sonuç olarak, bu süreç yalnızca Webpack dokümantasyonunu zenginleştirmekle kalmadı, aynı zamanda Node.js ekosisteminin gelecekteki projeler için daha modern ve verimli araçlara sahip olmasını da sağladı. Geliştiricilerin karşılaştıkları her zorluk, aslında topluluğa daha iyi çözümler sunmanın bir fırsatıydı. GSoC’in ikinci yarısında da benzer keşifler yapmaya devam edeceğiz.