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 syntaxstrict: true– Ensures type safety throughoutlib: ["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
QueryClientwith sensible defaults - The
'use client'directive tells Next.js this is a Client Component useStateensures 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 endpointInMemoryCache– Caches queries for optimal performancetypePolicies– 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:
QueryProviderwraps everything for data fetchingApolloProviderprovides 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-rendersuseEffect– 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.localto version control - Add
.env.localto 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:
- Check that all dependencies installed correctly
- Ensure the ArcGIS CSS is loading
- Check the browser console for specific errors
- 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
- Next.js 15: nextjs.org/docs
- React 19: react.dev
- TanStack Query: tanstack.com/query
- Apollo Client: apollographql.com/docs/react
- ArcGIS SDK: developers.arcgis.com/javascript
Sample Code & Examples
Community & Support
- ArcGIS Community: community.esri.com
- Next.js Discord: nextjs.org/discord
- GitHub Discussions: Great for asking questions about any of these technologies
Tips for Success
- Start Simple – Get the basic map working before adding complexity
- Use TypeScript – The types will guide you and catch errors early
- Read the Docs – Each technology has excellent documentation
- Experiment – Try changing coordinates, basemaps, zoom levels
- Use DevTools – React DevTools, Network tab, Console are your friends
- 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!
Comments
Sign in with GitHub to comment or react. Threads live in GitHub Discussions, so you can also reply from GitHub.