Next.js SDK

@netloc8/nextjs — Full Next.js integration with SSR proxy, server-side getGeo(), React hooks, and geo-based redirects.

Installation

Bash

bun add @netloc8/nextjs

@netloc8/nextjs re-exports everything from @netloc8/react and @netloc8/core — install only this package.

Operating Modes

The Next.js SDK supports two modes of operation:

Direct Mode (Recommended)

Browser calls the NetLoc8 API directly using a publishable key. Faster performance, simpler setup, and no server configuration. Best for most applications.

Proxy Mode

API calls go through your Next.js server using a secret key. Keeps your API key hidden, enables SSR, and avoids CORS. Set up a route handler with createProxy().

Quick Start — Direct Mode

app/layout.jsx

import { NetLoc8Provider } from '@netloc8/nextjs';

export default function RootLayout({ children }) {
    return (
        <html>
            <body>
                <NetLoc8Provider apiKey="pk_live_YOUR_KEY">
                    {children}
                </NetLoc8Provider>
            </body>
        </html>
    );
}

app/page.jsx

'use client';
import { useGeo } from '@netloc8/nextjs';

export default function Page() {
    const { geo, isLoading } = useGeo();
    if (isLoading) return <p>Loading…</p>;

    return <p>Hello from {geo?.location?.city}!</p>;
}

Quick Start — SSR Proxy Mode

Set up a Next.js API route that proxies requests to NetLoc8 using your secret key:

1. Set environment variable

.env.local

NETLOC8_API_KEY=sk_live_YOUR_SECRET_KEY

2. Create the proxy route

app/api/geo/[...path]/route.js

import { createProxy } from '@netloc8/nextjs/proxy';

export const { GET } = createProxy();

Proxy auto-discovery

When using createProxy() with the default path (/api/geo), the Provider detects it automatically. No apiBase configuration needed.

3. Set up the Provider

app/layout.jsx

import { NetLoc8Provider } from '@netloc8/nextjs';

export default function RootLayout({ children }) {
    return (
        <html>
            <body>
                {/* No apiKey needed — proxy uses the server-side env var */}
                <NetLoc8Provider>
                    {children}
                </NetLoc8Provider>
            </body>
        </html>
    );
}

getGeo() — Server-Side

Fetch geolocation data on the server in Server Components, Route Handlers, or getServerSideProps.

app/page.jsx (Server Component)

import { getGeo } from '@netloc8/nextjs/server';

export default async function Page() {
    const geo = await getGeo();

    return (
        <div>
            <h1>Welcome!</h1>
            <p>You are in {geo.location?.city}, {geo.location?.country?.name}</p>
            <p>Timezone: {geo.location?.timezone}</p>
        </div>
    );
}

getGeo() reads the caller's IP from the request headers and calls the NetLoc8 API using the NETLOC8_API_KEY environment variable.

Geo-Based Redirects

Use withGeoRedirect() to redirect users to localized paths based on their geolocation:

proxy.js

import { createProxy, withGeoRedirect } from '@netloc8/nextjs/proxy';

export default createProxy({
    handler: withGeoRedirect({
        defaultLocale: 'en',
        localeMap: {
            'GB': 'en',
            'DE': 'de',
            'FR': 'fr',
        },
        excludePaths: ['/api', '/_next'],
    }),
});

Caching

Geo-based redirects happen at the edge. Make sure your CDN or caching layer varies on the geo data (or disables caching for pages with geo redirects) to avoid serving cached redirects to the wrong users.

Environment Variables

Variable	Description
`NETLOC8_API_KEY`	Your secret API key (server-side only)
`NEXT_PUBLIC_NETLOC8_API_KEY`	Your publishable key (for direct mode)