Incremental Builds — Building Only Changed Pages for Faster SSG

// scripts/incremental-build.js — Manual incremental build
const fs = require('fs');
const path = require('path');
const crypto = require('crypto');

const STATE_FILE = './.build-state.json';

// Load previous build state
function loadState() {
    if (fs.existsSync(STATE_FILE)) {
        return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
    }
    return { files: {}, buildTime: 0 };
}

// Save current build state
function saveState(state) {
    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
}

// Compute file hash
function fileHash(filePath) {
    const content = fs.readFileSync(filePath);
    return crypto.createHash('md5').update(content).digest('hex');
}

// Find changed files
function findChangedFiles(contentDir) {
    const previousState = loadState();
    const changedFiles = [];
    const newState = { files: {}, buildTime: Date.now() };

    function scan(dir) {
        const entries = fs.readdirSync(dir, { withFileTypes: true });
        for (const entry of entries) {
            const fullPath = path.join(dir, entry.name);

            if (entry.isDirectory() && entry.name !== 'node_modules') {
                scan(fullPath);
            } else if (entry.isFile() && entry.name.endsWith('.md')) {
                const hash = fileHash(fullPath);
                newState.files[fullPath] = hash;

                if (previousState.files[fullPath] !== hash) {
                    changedFiles.push(fullPath);
                }
            }
        }
    }

    scan(contentDir);
    saveState(newState);

    return changedFiles;
}

// Rebuild only changed pages
async function incrementalBuild() {
    const start = Date.now();
    console.log('Checking for changed content...');

    const changedFiles = findChangedFiles('./content');
    console.log(`Found ${changedFiles.length} changed files`);

    if (changedFiles.length === 0) {
        console.log('No changes detected. Skipping build.');
        return;
    }

    // Rebuild only changed pages
    for (const file of changedFiles) {
        const slug = path.basename(file, '.md');
        console.log(`  Rebuilding: ${slug}`);
        // Render and write the page
        await renderPage(slug);
    }

    // Also rebuild listing pages (homepage, categories, tags)
    await rebuildListings();

    console.log(`Incremental build completed in ${Date.now() - start}ms`);
}

// gatsby-config.js — Gatsby Cloud incremental builds
module.exports = {
    flags: {
        DEV_SSR: false,
        FAST_DEV: true,
        PRESERVE_FILE_DOWNLOAD_CACHE: true,
        PRESERVE_WEBPACK_CACHE: true,
    },
    plugins: [
        {
            resolve: 'gatsby-source-contentful',
            options: {
                spaceId: process.env.CONTENTFUL_SPACE_ID,
                accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
                // Enable Contentful webhook-based incremental builds
                enableAdapter: true,
            },
        },
        {
            resolve: 'gatsby-plugin-incremental',
            options: {
                // Cache directory for incremental build data
                cacheDirectory: '.cache/incremental',
            },
        },
    ],
};

// Next.js uses ISR, not traditional incremental builds.
// But you can optimize with on-demand revalidation:

// pages/api/revalidate.js — On-demand revalidation
export default async function handler(req, res) {
    const { secret, paths } = req.body;

    if (secret !== process.env.REVALIDATION_TOKEN) {
        return res.status(401).json({ message: 'Invalid token' });
    }

    // Only revalidate specific paths
    const results = await Promise.allSettled(
        paths.map(path => res.revalidate(path))
    );

    const succeeded = results.filter(r => r.status === 'fulfilled').length;
    const failed = results.filter(r => r.status === 'rejected').length;

    console.log(`Revalidated: ${succeeded} succeeded, ${failed} failed`);

    return res.json({
        revalidated: true,
        succeeded,
        failed,
        errors: results
            .filter(r => r.status === 'rejected')
            .map(r => r.reason.message),
    });
}

// Trigger revalidation from CMS webhook
// POST /api/revalidate
// Body: { secret: "xxx", paths: ["/blog/new-post", "/blog"] }

// .eleventy.js — Incremental builds in Eleventy 2.0+
module.exports = function (eleventyConfig) {
    // Enable incremental builds
    eleventyConfig.setIncrementalBuilds(true);

    // Watch additional files
    eleventyConfig.addWatchTarget('./src/_data/');
    eleventyConfig.addWatchTarget('./src/assets/');

    // Passthrough copy
    eleventyConfig.addPassthroughCopy('src/css');
    eleventyConfig.addPassthroughCopy('src/images');

    return {
        dir: {
            input: 'src',
            output: '_site',
            includes: '_includes',
            layouts: '_layouts',
        },
        incremental: true,
    };
};

// Run with:
// npx @11ty/eleventy --incremental
// Or for development:
// npx @11ty/eleventy --serve --incremental