Getting Started with Web Maps: Next.js 15, React 19, and ArcGIS TypeScript SDK 4.32 – Part 1

October 29, 2025
•
Rabra Hierpa
#arcgis#arcgisjssdk#react
Web mapping essentials part 1 - setting up the environment

A Beginner-Friendly Guide to Modern Web Mapping Development

Welcome to the first post in our comprehensive series on building modern web mapping applications! Whether you’re a seasoned developer new to GIS, or a GIS professional looking to level up your web development skills, this guide will walk you through setting up a powerful, production-ready tech stack for web mapping.

What We’re Building

In this tutorial, we’ll create a solid foundation for web mapping applications using:

  • Next.js 15 – The latest React framework with improved performance and developer experience
  • React 19 – The newest version with enhanced features and optimizations
  • ArcGIS Maps SDK for JavaScript 4.32 – Esri’s powerful mapping SDK with TypeScript support
  • TailwindCSS – For beautiful, responsive styling
  • TanStack Query (React Query) v5 – For efficient data fetching and state management
  • Apollo Client – For GraphQL API integration

This combination gives you the best of modern web development and powerful GIS capabilities, all with full TypeScript support for type safety and excellent developer experience.

Why This Stack?

Before we dive in, let’s understand why this combination is powerful:

  • Next.js 15 brings React 19 support, improved caching, and Turbopack for faster builds
  • React 19 provides the latest features including improved hooks and better TypeScript integration
  • ArcGIS SDK 4.32 offers comprehensive 2D/3D mapping, spatial analysis, and web components
  • TailwindCSS enables rapid UI development without leaving your markup
  • TanStack Query simplifies server state management with automatic caching and background updates
  • Apollo Client provides robust GraphQL integration with intelligent caching

Prerequisites

Before starting, make sure you have:

  • Node.js 20.9 or later – Download here
  • Basic knowledge of JavaScript/TypeScript – Don’t worry, we’ll explain as we go
  • A code editor – We recommend VS Code
  • Terminal/Command line – Basic familiarity helps
  • Enthusiasm for maps! 🗺️

Step 1: Create a New Next.js 15 Project

Let’s start by creating our Next.js project. Open your terminal and run:

npx create-next-app@latest my-mapping-app

You’ll see several prompts. Here’s what to choose:

What is your project named? my-mapping-app
Would you like to use TypeScript? Yes ✅
Would you like to use ESLint? Yes ✅
Would you like to use Tailwind CSS? Yes ✅
Would you like your code inside a `src/` directory? Yes ✅
Would you like to use App Router? Yes ✅
Would you like to use Turbopack for `next dev`? Yes ✅
Would you like to customize the import alias? No

Why these choices?

  • TypeScript – Catches errors before runtime and provides excellent autocomplete
  • ESLint – Keeps our code clean and consistent
  • Tailwind CSS – Already configured, saving us setup time
  • src/ directory – Better project organization
  • App Router – Next.js’s modern routing system with React Server Components
  • Turbopack – Faster development builds

Once complete, navigate into your project:

cd my-mapping-app

Step 2: Install Required Dependencies

Now let’s install all the packages we need. Run these commands:

# Install TanStack Query (React Query v5)
npm install @tanstack/react-query

# Install Apollo Client for GraphQL
npm install @apollo/client graphql

# Install ArcGIS Maps SDK for JavaScript
npm install @arcgis/core

# Install the ArcGIS web components (optional, but recommended)
npm install @arcgis/map-components

What each package does:

  • @tanstack/react-query – Manages server state, caching, and data fetching
  • @apollo/client + graphql – Handles GraphQL queries and mutations
  • @arcgis/core – The core ArcGIS mapping SDK with ES modules
  • @arcgis/map-components – Pre-built web components for common mapping UI

Step 3: Configure TypeScript for ArcGIS

The ArcGIS SDK includes TypeScript definitions out of the box! However, let’s ensure our TypeScript configuration is optimal. Open tsconfig.json and verify these settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "preserve",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "allowJs": true,
    "noEmit": true,
    "incremental": true,
    "paths": {
      "@/*": ["./src/*"]
    },
    "plugins": [
      {
        "name": "next"
      }
    ]
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Key settings for ArcGIS:

  • esModuleInterop: true – Enables proper import syntax
  • strict: true – Ensures type safety throughout
  • lib: ["ES2020", "DOM"] – Provides necessary type definitions

Step 4: Set Up TanStack Query Provider

Create a new file: src/providers/query-provider.tsx

'use client'

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactNode, useState } from 'react'

export function QueryProvider({ children }: { children: ReactNode }) {
  // Create a client - we use useState to ensure it's created only once
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            // Data is considered fresh for 60 seconds
            staleTime: 60 * 1000,
            // Keep data in cache for 5 minutes
            gcTime: 5 * 60 * 1000,
            // Retry failed requests once
            retry: 1,
            // Don't refetch on window focus by default
            refetchOnWindowFocus: false,
          },
        },
      })
  )

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

What’s happening here:

  • We create a QueryClient with sensible defaults
  • The 'use client' directive tells Next.js this is a Client Component
  • useState ensures the client is created once and persists across renders
  • The provider wraps our app to give all components access to React Query

Step 5: Set Up Apollo Client

Create: src/lib/apollo-client.ts

import { ApolloClient, InMemoryCache, HttpLink } from '@apollo/client'

// Create the HTTP link
const httpLink = new HttpLink({
  uri: process.env.NEXT_PUBLIC_GRAPHQL_ENDPOINT || 'https://your-graphql-api.com/graphql',
  // You can add headers here if needed
  // headers: {
  //   authorization: `Bearer ${token}`,
  // },
})

// Create the Apollo Client
export const apolloClient = new ApolloClient({
  link: httpLink,
  cache: new InMemoryCache({
    // Configure cache policies here
    typePolicies: {
      Query: {
        fields: {
          // Example: merge paginated results
          // locations: {
          //   keyArgs: false,
          //   merge(existing = [], incoming) {
          //     return [...existing, ...incoming]
          //   },
          // },
        },
      },
    },
  }),
  // Enable DevTools in development
  connectToDevTools: process.env.NODE_ENV === 'development',
})

Now create the provider: src/providers/apollo-provider.tsx

'use client'

import { ApolloProvider as BaseApolloProvider } from '@apollo/client'
import { ReactNode } from 'react'
import { apolloClient } from '@/lib/apollo-client'

export function ApolloProvider({ children }: { children: ReactNode }) {
  return (
    <BaseApolloProvider client={apolloClient}>
      {children}
    </BaseApolloProvider>
  )
}

Understanding Apollo Client:

  • HttpLink – Connects to your GraphQL endpoint
  • InMemoryCache – Caches queries for optimal performance
  • typePolicies – Defines how different types should be cached
  • We keep the GraphQL endpoint in an environment variable for flexibility

Step 6: Add ArcGIS CSS

Create: src/app/globals.css (or update if it exists)

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Import ArcGIS SDK CSS - using the CDN for optimal loading */
@import url("https://js.arcgis.com/4.32/@arcgis/core/assets/esri/themes/light/main.css");

:root {
  --background: #ffffff;
  --foreground: #171717;
}

@media (prefers-color-scheme: dark) {
  :root {
    --background: #0a0a0a;
    --foreground: #ededed;
  }
}

body {
  color: var(--foreground);
  background: var(--background);
  font-family: Arial, Helvetica, sans-serif;
}

/* Ensure the map container fills its parent */
.map-container {
  width: 100%;
  height: 100%;
}

CSS Strategy:

  • We import ArcGIS CSS from the CDN for best performance
  • TailwindCSS provides utility classes for layout and styling
  • Custom CSS variables for theme support

Step 7: Configure Next.js for ArcGIS

Update next.config.ts:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  webpack: (config) => {
    // ArcGIS SDK uses Web Workers - ensure they work in Next.js
    config.module.rules.push({
      test: /.worker.(js|ts)$/,
      use: { loader: "worker-loader" },
    });

    return config;
  },
  // Optimize for ArcGIS SDK
  transpilePackages: ['@arcgis/core'],
};

export default nextConfig;

Why these changes:

  • transpilePackages – Ensures ArcGIS modules are properly processed by Next.js
  • Worker loader configuration – ArcGIS uses web workers for performance

Step 8: Create the Root Layout with Providers

Update src/app/layout.tsx:

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import { QueryProvider } from "@/providers/query-provider";
import { ApolloProvider } from "@/providers/apollo-provider";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Modern Web Mapping App",
  description: "Built with Next.js 15, React 19, and ArcGIS SDK",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <QueryProvider>
          <ApolloProvider>
            {children}
          </ApolloProvider>
        </QueryProvider>
      </body>
    </html>
  );
}

Provider Order Matters:

  • QueryProvider wraps everything for data fetching
  • ApolloProvider provides GraphQL access
  • Providers are composed, each adding functionality

Step 9: Create Your First Map Component

Create: src/components/map/BasicMap.tsx

'use client'

import { useEffect, useRef } from 'react'
import MapView from '@arcgis/core/views/MapView'
import Map from '@arcgis/core/Map'
import type { MapViewProperties } from '@arcgis/core/views/MapView'

interface BasicMapProps {
  center?: [number, number] // [longitude, latitude]
  zoom?: number
  basemap?: string
  className?: string
}

export function BasicMap({
  center = [-118.805, 34.027], // Default to Southern California
  zoom = 13,
  basemap = 'topo-vector',
  className = '',
}: BasicMapProps) {
  // useRef maintains the reference to the map container and view
  const mapDiv = useRef<HTMLDivElement>(null)
  const mapView = useRef<MapView | null>(null)

  useEffect(() => {
    if (!mapDiv.current) return

    // Initialize the map
    const map = new Map({
      basemap: basemap as __esri.BasemapStyle,
    })

    // Create the MapView
    const view = new MapView({
      container: mapDiv.current,
      map: map,
      center: center,
      zoom: zoom,
      // Optional: Customize the UI
      ui: {
        components: ['zoom', 'compass', 'attribution'],
      },
    } as MapViewProperties)

    mapView.current = view

    // Wait for the view to be ready
    view.when(() => {
      console.log('Map view is ready!')
    }).catch((error) => {
      console.error('Error initializing map:', error)
    })

    // Cleanup function - important for React!
    return () => {
      if (mapView.current) {
        mapView.current.destroy()
        mapView.current = null
      }
    }
  }, [center, zoom, basemap]) // Re-initialize if these props change

  return (
    <div 
      ref={mapDiv} 
      className={`map-container ${className}`}
      style={{ width: '100%', height: '100%' }}
    />
  )
}

Understanding the Map Component:

  • useRef – Maintains references without causing re-renders
  • useEffect – Handles map initialization and cleanup
  • Cleanup function – Essential to prevent memory leaks
  • TypeScript types – Provide autocomplete and type safety
  • Props – Make the component reusable and configurable

Step 10: Create the Home Page

Update src/app/page.tsx:

import { BasicMap } from '@/components/map/BasicMap'

export default function Home() {
  return (
    <div className="flex flex-col h-screen">
      {/* Header */}
      <header className="bg-blue-600 text-white p-4 shadow-md">
        <div className="container mx-auto">
          <h1 className="text-2xl font-bold">
            Modern Web Mapping Application
          </h1>
          <p className="text-sm text-blue-100">
            Built with Next.js 15, React 19, and ArcGIS SDK 4.32
          </p>
        </div>
      </header>

      {/* Main Content - Map fills remaining space */}
      <main className="flex-1 relative">
        <BasicMap 
          center={[-118.805, 34.027]} 
          zoom={13}
          basemap="streets-navigation-vector"
          className="absolute inset-0"
        />
      </main>

      {/* Footer */}
      <footer className="bg-gray-800 text-white p-3 text-center text-sm">
        <p>Powered by ArcGIS Maps SDK for JavaScript | © {new Date().getFullYear()}</p>
      </footer>
    </div>
  )
}

Layout Breakdown:

  • flex flex-col h-screen – Creates a full-height flexbox layout
  • Header with fixed height
  • Main content (flex-1) – Takes remaining space
  • Map uses absolute positioning to fill the main area
  • TailwindCSS classes for responsive, beautiful design

Step 11: Add Environment Variables

Create .env.local in your project root:

# GraphQL Endpoint (if you have one)
NEXT_PUBLIC_GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql

# ArcGIS API Key (optional, for some features)
# Get one free at https://developers.arcgis.com/
NEXT_PUBLIC_ARCGIS_API_KEY=your-api-key-here

Environment Variables:

  • NEXT_PUBLIC_ prefix makes variables available in the browser
  • Never commit .env.local to version control
  • Add .env.local to your .gitignore

Step 12: Run Your Application

Start the development server:

npm run dev

Open your browser to http://localhost:3000 and you should see your map! 🎉

If you see errors:

  1. Check that all dependencies installed correctly
  2. Ensure the ArcGIS CSS is loading
  3. Check the browser console for specific errors
  4. Verify your Node.js version is 20.9+

Project Structure Overview

Your project should now look like this:

my-mapping-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx          # Root layout with providers
│   │   ├── page.tsx             # Home page with map
│   │   └── globals.css          # Global styles + ArcGIS CSS
│   ├── components/
│   │   └── map/
│   │       └── BasicMap.tsx     # Reusable map component
│   ├── lib/
│   │   └── apollo-client.ts     # Apollo Client configuration
│   └── providers/
│       ├── query-provider.tsx   # TanStack Query provider
│       └── apollo-provider.tsx  # Apollo provider
├── public/                       # Static assets
├── .env.local                    # Environment variables (don't commit!)
├── next.config.ts               # Next.js configuration
├── tsconfig.json                # TypeScript configuration
└── package.json                 # Dependencies

Understanding the Tech Stack

Next.js 15 Features We’re Using

  • App Router – File-system based routing with React Server Components
  • Server & Client Components – Optimal performance with selective client-side interactivity
  • Turbopack – Fast development builds (up to 76.7% faster!)
  • React 19 Support – Built-in support for the latest React features

TanStack Query Benefits

  • Automatic Caching – Reduce unnecessary API calls
  • Background Refetching – Keep data fresh automatically
  • Loading States – Built-in loading, error, and success states
  • Optimistic Updates – Update UI instantly, sync with server later

Apollo Client Advantages

  • Intelligent Caching – Normalized cache for optimal performance
  • Type Safety – Full TypeScript support with type generation
  • DevTools – Excellent browser extension for debugging
  • Flexible – Works with any GraphQL API

ArcGIS SDK 4.32 Highlights

  • 2D and 3D Maps – Seamless switching between views
  • TypeScript Support – Full type definitions included
  • Web Components – Pre-built UI components
  • Powerful Analysis – Spatial analysis, routing, geocoding
  • Multiple Data Sources – Feature layers, map services, and more

Common Issues and Solutions

Issue: Map doesn’t display

Solution:

  • Check that the map container has a defined height
  • Verify the ArcGIS CSS is loading
  • Check browser console for errors

Issue: TypeScript errors with ArcGIS imports

Solution:

// Use type imports for types
import type MapView from '@arcgis/core/views/MapView'
// Use regular imports for classes
import MapView from '@arcgis/core/views/MapView'

Issue: “Module not found” errors

Solution:

  • Ensure all packages are installed: npm install
  • Clear Next.js cache: rm -rf .next
  • Restart the dev server

Next Steps and Coming Attractions

Congratulations! You’ve set up a modern, production-ready foundation for web mapping applications. But we’re just getting started!

In This Series, We’ll Explore:

Part 2: Working with Feature Layers

  • Loading data from ArcGIS services
  • Custom popup templates
  • Filtering and querying features
  • Integrating with React Query for feature data

Part 3: Graphics Layer Magic

  • Drawing on the map
  • User interaction and events
  • Integrating with forms
  • Real-time updates

Part 4: Basemap Switching

  • Building a basemap gallery
  • Custom basemaps
  • Styled vector basemaps
  • Saving user preferences

Part 5: Advanced Visualization

  • Smart mapping and renderers
  • Clustering large datasets
  • Heatmaps and aggregation
  • Time-aware layers

Part 6: Spatial Analysis

  • Client-side geometry operations
  • Network analysis and routing
  • Elevation analysis
  • Buffer and overlay operations

Part 7: Integration Patterns

  • Connecting GraphQL APIs with map features
  • Real-time data with React Query
  • State management between map and UI
  • Authentication and secured services

Part 8: Production Deployment

  • Performance optimization
  • Code splitting and lazy loading
  • Hosting on Vercel
  • Environment-specific configurations

Resources and Documentation

Official Documentation

Sample Code & Examples

Community & Support

Tips for Success

  1. Start Simple – Get the basic map working before adding complexity
  2. Use TypeScript – The types will guide you and catch errors early
  3. Read the Docs – Each technology has excellent documentation
  4. Experiment – Try changing coordinates, basemaps, zoom levels
  5. Use DevTools – React DevTools, Network tab, Console are your friends
  6. Ask for Help – The GIS and React communities are friendly and helpful

Conclusion

You’ve now built a solid foundation for modern web mapping applications! You have:

✅ A Next.js 15 application with React 19
✅ TailwindCSS for beautiful, responsive styling
✅ TanStack Query for efficient data management
✅ Apollo Client ready for GraphQL APIs
✅ ArcGIS SDK 4.32 with full TypeScript support
✅ A working map display with modern React patterns

This stack is production-ready and scales from simple demos to complex enterprise applications. The patterns we’ve established here will serve as the foundation for everything we build in future tutorials.

In the next post, we’ll dive into Feature Layers – learning how to display, query, and interact with spatial data from ArcGIS services.

Stay Connected

Want to be notified when the next tutorial drops? Follow along and share your mapping creations!

Happy Mapping! 🗺️


This tutorial was written for developers and GIS enthusiasts who want to build modern web mapping applications. All technologies mentioned are actively maintained and production-ready as of October 2024.

Questions or feedback? Feel free to reach out or leave a comment below!


R

Rabra Hierpa

Software Engineer, GIS Developer, and FOSS enthusiast sharing insights on web development, GIS technologies, and open-source tools.