snapcrawl-netlify-ssr

SnapCrawl Netlify SSR

HTML prerendering for Netlify projects powered by SnapCrawl.

This package provides simple helpers for:

• Next.js (App/Pages Router) via a one-line middleware
• Static SPAs and Express apps on Netlify via an Edge Function + tiny netlify.toml config

Why SnapCrawl?

Search and social crawlers often struggle with client-side apps (React, Vue, Angular, etc.). SnapCrawl renders your pages server-side and returns fully-formed HTML to bots — improving SEO, social previews, and crawl reliability.

This package makes SnapCrawl plug-and-play on Netlify's Edge Runtime (Deno).

Your API Secret

🔑 Get your API secret

• Create an account (or sign in): snapcrawl.io
• Go to your Dashboard → Secret keys
• Copy your Secret Key

Installation

npm install snapcrawl-netlify-ssr
# or
yarn add snapcrawl-netlify-ssr

Set your secret in Netlify → Site settings → Environment variables:

• SNAPCRAWL_SECRET = your-secret-value

Usage

1) Netlify – Next.js (Middleware)

Create or edit middleware.{js,ts} at the project root:

// middleware.js
import { withSnapCrawl } from "snapcrawl-netlify-ssr/next";

// Optional: your existing logic
function otherMiddleware() {
  // ...
}

export default withSnapCrawl({ secret: process.env.SNAPCRAWL_SECRET })(
  otherMiddleware
);

• Lazy next/server import keeps non-Next projects safe.
• SnapCrawl only handles crawler traffic and HTML routes (skips assets).
• If SnapCrawl is unreachable or returns success:false, the middleware falls back to your normal app.
• On Netlify, Next.js middleware is automatically compiled into an Edge Function.

2) Netlify – Other Frameworks (Static SPA & Express)

Add an Edge Function and attach it in netlify.toml.

netlify.toml

[build]
  # ...

[[edge_functions]]
  path = "/*"
  function = "snapcrawl"

netlify/edge-functions/snapcrawl.js

import { createEdgeHandler } from "snapcrawl-netlify-ssr";

const handler = createEdgeHandler({
  secret: Deno.env.get("SNAPCRAWL_SECRET"),
});

export default (req, ctx) =>
  handler(req).then((res) => (res.status === 204 ? ctx.next() : res));

How it works

• Humans: served by Netlify CDN/app as usual (ctx.next() when SnapCrawl returns 204).
• Bots: prerendered HTML returned directly from SnapCrawl.
• If the API fails, the handler returns 204 so Netlify serves the normal app.

What It Does

• Detects popular bots via User-Agent (Next.js middleware also uses a heuristic)
• Detects desktop vs mobile crawlers to render appropriately
• Skips assets like .js, .css, images, fonts, etc.
• Calls SnapCrawl SSR API and serves HTML directly to the crawler
• Falls back gracefully on errors

API

withSnapCrawl({ secret })

Wraps (or acts as) your Next.js middleware default export.

• Params
  • secret (string, required): your SnapCrawl API secret.
• Returns: a Next.js middleware function.
• Behavior: Handles crawler requests for HTML routes; otherwise calls NextResponse.next() or your existing middleware.

createEdgeHandler({ secret })

Edge Function handler for SPA/Express projects on Netlify.

• Params
  • secret (string, required): your SnapCrawl API secret.
• Returns: an Edge handler that responds with prerendered HTML for bots, or 204 to let Netlify serve your app.