ArcGIS Proxy

A minimal read-only ArcGIS MapServer proxy for Next.js App Router.

Installing

npm install @rerdev/arcgis-proxy

Usage

Browser code calls your same-origin API route. The MapServer URL and credentials stay on the server.

fetch("/api/arcgis/2?f=json");

fetch("/api/arcgis/2/query", {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    f: "json",
    where: "OBJECTID = 1",
    outFields: "OBJECTID",
    returnGeometry: "false",
  }),
});

With the ArcGIS Maps SDK for JavaScript, point the layer at the same route:

import Map from "@arcgis/core/Map.js";
import MapImageLayer from "@arcgis/core/layers/MapImageLayer.js";

const map = new Map({
  layers: [
    new MapImageLayer({
      url: "/api/arcgis",
    }),
  ],
});

The proxy supports GET and POST read operations. ArcGIS mutation operations are rejected.

Quick start

Create app/api/arcgis/[[...path]]/route.ts:

import {
  createArcGISProxy,
  toNextJsHandler,
} from "@rerdev/arcgis-proxy";

const proxy = createArcGISProxy({
  mapServerUrl: process.env.ARCGIS_MAP_SERVER_URL!,
  bearerToken: process.env.ARCGIS_BEARER_TOKEN!,
});

export const { POST, GET } = toNextJsHandler(proxy);

For static bearer authentication, set both values in .env.local:

ARCGIS_MAP_SERVER_URL=https://gis.example.com/rest/services/Cadastre/MapServer
ARCGIS_BEARER_TOKEN=replace-with-a-server-token

Or let the proxy acquire and reuse an ArcGIS OAuth2 token:

const proxy = createArcGISProxy({
  mapServerUrl: process.env.ARCGIS_MAP_SERVER_URL!,
  oauth2: {
    tokenUrl: process.env.ARCGIS_TOKEN_URL!,
    clientId: process.env.ARCGIS_CLIENT_ID!,
    clientSecret: process.env.ARCGIS_CLIENT_SECRET!,
  },
});

export const { POST, GET } = toNextJsHandler(proxy);

ARCGIS_MAP_SERVER_URL=https://gis.example.com/rest/services/Cadastre/MapServer
ARCGIS_TOKEN_URL=https://gis.example.com/oauth2/token
ARCGIS_CLIENT_ID=replace-with-client-id
ARCGIS_CLIENT_SECRET=replace-with-client-secret

For an ArcGIS Server generateToken endpoint, use username/password authentication:

const proxy = createArcGISProxy({
  mapServerUrl: process.env.ARCGIS_MAP_SERVER_URL!,
  arcgisToken: {
    tokenUrl: process.env.ARCGIS_TOKEN_URL!,
    username: process.env.ARCGIS_USERNAME!,
    password: process.env.ARCGIS_PASSWORD!,
    referer: process.env.ARCGIS_REFERER!,
  },
});

export const { POST, GET } = toNextJsHandler(proxy);

ARCGIS_MAP_SERVER_URL=https://gis.example.com/rest/services/Cadastre/MapServer
ARCGIS_TOKEN_URL=https://gis.example.com/arcgis/tokens/generateToken
ARCGIS_USERNAME=replace-with-username
ARCGIS_PASSWORD=replace-with-password
ARCGIS_REFERER=https://app.example.com

Never prefix these values with NEXT_PUBLIC_.

Configuration

| Option | Description | | --- | --- | | mapServerUrl | Absolute ArcGIS URL ending in /MapServer. HTTPS is required except on localhost. | | bearerToken | Server-only static bearer token. | | oauth2.tokenUrl | Server-only ArcGIS OAuth2 token endpoint. HTTPS is required except on localhost. | | oauth2.clientId | Server-only OAuth2 client ID. | | oauth2.clientSecret | Server-only OAuth2 client secret. | | arcgisToken.tokenUrl | Server-only ArcGIS Server generateToken endpoint. HTTPS is required except on localhost. | | arcgisToken.username | Server-only ArcGIS Server username. | | arcgisToken.password | Server-only ArcGIS Server password. | | arcgisToken.referer | HTTPS application URL bound to the generated token and forwarded to the MapServer. Localhost may use HTTP. |

Configure exactly one of bearerToken, oauth2, or arcgisToken.

OAuth2 uses the client_credentials grant. ArcGIS Server authentication posts username, password, client=referer, referer, and f=json to the configured token endpoint.

Acquired tokens are cached in memory per proxy instance and reused until shortly before expiry. Concurrent requests share one token request, failed token requests are not cached, and a MapServer 401 invalidates the token for the next request.

Create the proxy once at route-module scope as shown above. The cache is intentionally process-local: it does not use the Next.js Data Cache or share tokens between server processes or serverless instances.

The MapServer URL cannot contain credentials, a query string, or a fragment. Token and referer URLs cannot contain credentials or fragments.