Skip to main content

Deploy Next.js 16 to Azure App Service (Linux) with pnpm: 2026 Guide

Rawson Wade, , 11 min read
Deploy Next.js 16 to Azure App Service (Linux) with pnpm: 2026 Guide

Next.js 16 brings further improvements to performance, developer experience, and deployment flexibility on top of the Next.js 15 baseline. When combined with pnpm's efficient dependency management and Azure App Service's Linux hosting, you have a powerful stack for building and deploying modern web applications. However, deploying Next.js to Azure App Service isn't the most intuitive developer experience when you go with the default options, particularly with pnpm.

In this three-part guide, you'll learn how to:

  • Set up a new Next.js 16 (or 13/14/15) project using pnpm
  • Configure Next.js for standalone output mode (essential for Azure App Service)
  • Implement pnpm package hoisting for Azure App Service compatibility
  • Build and validate your application for deployment to Azure Web App on Linux
  • Optimise your project structure for production

This is Part 1 of a three-part series on deploying Next.js 16 to Azure App Service. In Part 2 we cover Azure DevOps CI/CD pipelines with pnpm caching, and in Part 3 we walk through the Azure infrastructure configuration and monitoring.

Why pnpm for Next.js 16 on Azure App Service?

Before diving into the setup, it's worth understanding why PNPM is an excellent choice for Next.js applications.

PNPM's Key Advantages:

  1. Disk Space Efficiency: PNPM uses a content-addressable store, meaning packages are stored once globally and hard-linked into projects. This can reduce disk usage by up to 50% compared to npm.

  2. Faster Installations: By leveraging hard links and an efficient dependency resolution algorithm, PNPM typically installs dependencies faster than npm or Yarn.

  3. Strict Dependency Resolution: PNPM creates a non-flat node_modules structure by default, preventing phantom dependencies (packages you didn't explicitly install but can somehow import).

  4. Better Monorepo Support: If you're building multiple Next.js applications or have a monorepo structure, PNPM's workspace features are a real nice-to-have.

Azure-Specific Benefits:

  • Smaller build artifacts when combined with Next.js standalone mode
  • Faster CI/CD pipeline builds due to efficient caching
  • Reduced memory footprint during build processes

That said, PNPM's strict dependency isolation can require additional configuration for Azure App Service, which we'll address in this guide. Also note that this guide will be useful for other package managers.

Creating a New Next.js 16 Project with PNPM

With PNPM installed, let's create a new Next.js 16 project. The process is similar to using npx, but we'll use PNPM's equivalent command.

Create your Next.js 16 application:

pnpm create next-app@latest my-nextjs-azure-app

You'll be prompted with several configuration options. Here are the recommended settings for an Azure deployment:

Why these choices?

  • TypeScript: Provides type safety and better developer experience. Highly recommended for production applications.
  • ESLint: Helps catch common errors and enforces code quality standards.
  • Tailwind CSS: Efficient styling solution that doesn't impact runtime bundle size.
  • src/ directory: Better project organisation, separating application code from configuration files.
  • App Router: Next.js 13+ recommended routing system with better performance and features.
  • Turbopack: Faster development builds (though this only affects local development, not Azure deployment).
cd my-nextjs-azure-app

Project Structure Overview:

After creation, your project structure should look like this:

my-nextjs-azure-app/
├── public/                          # Static assets (images, fonts, etc.)
├── src/
│   └── app/                        # App Router directory
│       ├── favicon.ico
│       ├── globals.css
│       ├── layout.tsx              # Root layout component
│       └── page.tsx                # Home page component
├── .eslintrc.json                  # ESLint configuration
├── .gitignore
├── next.config.ts                  # Next.js configuration
├── package.json                    # Project dependencies and scripts
├── pnpm-lock.yaml                  # PNPM lock file (like package-lock.json)
├── postcss.config.mjs              # PostCSS configuration for Tailwind
├── tailwind.config.ts              # Tailwind CSS configuration
└── tsconfig.json                   # TypeScript configuration

Important files for Azure deployment:

  • next.config.ts: Where we'll configure standalone output mode
  • package.json: Contains build scripts and dependencies
  • pnpm-lock.yaml: Ensures deterministic builds in CI/CD pipelines

Verify the installation works:

pnpm dev

Open your browser to http://localhost:3000/. You should see the default Next.js welcome page. Press Ctrl+C to stop the development server.

Configuring Next.js for Standalone Output Mode

This is the most critical configuration for Azure App Service deployment. By default, a Next.js build includes the entire node_modules directory, which must otherwise be installed manually on the deployed server, resulting in large deployment artifacts or slow deployments (which can take hours on the lowest Linux Azure App Service).

Standalone output mode creates a minimal, self-contained build that includes only the necessary dependencies.

What is Standalone Output Mode?

Standalone output mode is a Next.js feature that:

  • Traces all dependencies required for production
  • Copies only the necessary files to .next/standalone
  • Dramatically reduces deployment size (often by 80% or more)
  • Includes a minimal server.js file to run the application
  • Excludes development dependencies and unused packages

Why is it essential for Azure?

Azure App Service has specific characteristics that make standalone mode beneficial:

  • Faster deployment times with smaller artifacts
  • Reduced storage costs in Azure DevOps artifact storage
  • Lower memory footprint during application startup
  • Better cold start performance on App Service plans with auto-scaling

Configuring standalone output:

Open next.config.ts (or next.config.js if you chose JavaScript) and modify it as follows:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: 'standalone',
};
 
export default nextConfig;

Understanding the standalone build output:

When you build with output: 'standalone', Next.js creates this structure:

.next/
├── standalone/                     # Minimal production build
│   ├── .next/                     # Next.js build artifacts
│   ├── node_modules/              # Only production dependencies
│   ├── public/                    # Static files (copied automatically)
│   ├── package.json
│   └── server.js                  # Entry point for running the app
├── static/                        # Static assets with cache headers
└── ...                            # Other build artifacts

Important considerations:

  1. Static files location: The public folder and .next/static files are automatically copied into the standalone output. However, you'll need to ensure these are properly deployed to Azure (covered in Part 2).

  2. Server.js entry point: The generated server.js file is what you'll run on Azure App Service. It's a minimal Node.js server that serves your Next.js application.

  3. Environment variables: Standalone mode respects environment variables. You can set these in Azure App Service configuration (covered in Part 3).

Additional next.config.ts optimisations for Azure:

While we're configuring Next.js, let's add some production-ready settings:

import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  output: 'standalone',
 
  // Disable x-powered-by header for security
  poweredByHeader: false,
 
  // Compression is handled by Azure, disable Next.js compression
  compress: false,
 
  // Enable React strict mode for better error catching in development
  reactStrictMode: true,
 
  // Optimise images
  images: {
    formats: ['image/avif', 'image/webp'],
    // If using Azure CDN or Blob Storage for images:
    // remotePatterns: [
    //   {
    //     protocol: 'https',
    //     hostname: 'yourstorage.blob.core.windows.net',
    //   },
    // ],
  },
 
  // Set security headers (also covered in Part 3)
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'X-DNS-Prefetch-Control',
            value: 'on',
          },
          {
            key: 'X-Frame-Options',
            value: 'SAMEORIGIN',
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'Referrer-Policy',
            value: 'origin-when-cross-origin',
          },
        ],
      },
    ];
  },
};
 
export default nextConfig;

Note on compression: Azure App Service handles Gzip/Brotli compression at the IIS/Nginx level, so it's more efficient to disable Next.js compression to avoid double-compression overhead.

Configuring PNPM Package Hoisting for Azure Compatibility

By default, PNPM uses a content-addressable storage system that creates a nested node_modules structure. This prevents phantom dependencies but can cause issues with some Node.js applications expecting a flat structure. Azure App Service and certain Node.js runtime behaviours can be affected by this strict isolation. In Addition, Windows 11 move and copy operations copy the symlinks directly not the destination files making it hard to build your final artifact.

Understanding the issue:

When Next.js builds in standalone mode, it traces dependencies and copies them to .next/standalone/node_modules. However, with PNPM's default strict mode, some dependencies might not resolve correctly at runtime on Azure if they expect to access peer dependencies or transitive dependencies.

The solution: Package hoisting

We'll configure PNPM to "hoist" packages, making them more accessible in the dependency tree. This ensures compatibility with Azure App Service while maintaining most of PNPM's benefits. It's worth noting that you can also set this up to only happen on your CI/CD pipeline so that you can maximise PNPM performance on your development machine.

Creating the .npmrc configuration file:

In your project root (alongside package.json), create a file named .npmrc:

touch .npmrc

Add the following content to .npmrc:

# Automatically installs peer dependencies without prompting.
auto-install-peers=true
 
# Dependency linking strategy. "hoisted" flattens the dependency tree.
node-linker=hoisted

Testing your hoisting configuration:

After creating .npmrc, reinstall dependencies to apply the configuration:

# Remove existing node_modules and lock file
rm -rf node_modules pnpm-lock.yaml
 
# Reinstall with new configuration
pnpm install

Examine the node_modules structure:

ls -la node_modules/

With node-linker=hoisted, you should see all packages at the root level, similar to npm's flat structure.

Troubleshooting hoisting issues:

If you encounter runtime errors after deployment to Azure (covered in Part 3), try these steps:

  1. Switch to shamefully-hoist: Modify .npmrc to use shamefully-hoist=true instead
  2. Reinstall dependencies: Always run pnpm install after changing .npmrc
  3. Install transitive dependencies: Some dependencies may need to be explicitly installed
  4. Clear build cache: Delete .next folder and rebuild
  5. Check Azure logs: Use App Service logs to identify missing dependencies (Part 3)

Common issues and solutions:

IssueSymptomSolution
Module not found errorsCannot find module 'X' in Azure logsEnable shamefully-hoist=true
Peer dependency warningsBuild warnings about missing peersSet strict-peer-dependencies=false
Different behaviour dev vs prodWorks locally, fails on AzureEnsure .npmrc is committed to Git
Phantom dependenciesCan import packages not in package.jsonReduce hoisting (security concern)

Security consideration:

While hoisting improves compatibility, it does reduce PNPM's strict dependency isolation. In production environments with stringent security requirements, consider:

  • Regularly auditing dependencies with pnpm audit
  • Using pnpm-lock.yaml to ensure reproducible builds
  • Implementing dependency scanning in your CI/CD pipeline (covered in Part 2)

Building Your Next.js Application for Azure

With configuration complete, let's build the application and understand what gets generated.

Run the production build:

pnpm build

You should see output similar to:

Understanding the build output:

  1. Route table: Shows all pages and their bundle sizes

    • ○ indicates static pages (generated at build time)
    • λ (if you see it) indicates server-side rendered pages
    • First Load JS is the total JavaScript needed for that page
  2. .next directory: Contains all build artifacts

    • .next/standalone/: The deployable application (what goes to Azure)
    • .next/static/: Static assets with content hashing
    • .next/server/: Server-side rendering chunks

Examining the standalone output:

Navigate to the standalone directory:

cd .next/standalone
ls -la

You should see:

.next/                 # Build artifacts
node_modules/          # Only production dependencies
public/                # Static files (if any)
package.json           # Minimal package.json
server.js              # Entry point

The server.js file:

This is the entry point for your Next.js application on Azure. Let's look at what it does.

The generated server.js typically contains:

// Minimal Next.js server that:
// 1. Starts the HTTP server
// 2. Serves static files
// 3. Handles SSR and API routes
// 4. Manages Next.js middleware
 
process.env.NODE_ENV = 'production'
process.chdir(__dirname)
 
const NextServer = require('next/dist/server/next-server').default
const http = require('http')
const path = require('path')
 
// Read configuration
const nextConfig = {...}
 
// Start server
startServer({
  dir,
  isDev: false,
  config: nextConfig,
  hostname,
  port: currentPort,
  allowRetry: false,
  keepAliveTimeout,
}).catch((err) => {
  console.error(err);
  process.exit(1);
});

Understanding package.json in standalone:

cat package.json

The standalone package.json is minimal:

{
  "dependencies": {
    "next": "16.0.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  }
}

Testing the standalone build locally:

This is crucial before deploying to Azure. Let's ensure the standalone build works correctly:

# From the .next/standalone directory
node server.js

Open your browser to http://localhost:3000/. The application may look a little funky when compared to the development version. But that is ok! We need to do a little more work to get the deployment bundles which we will do in part 2.

Common build errors and solutions:

ErrorCauseSolution
Error: Cannot find moduleMissing dependency in standaloneCheck package.json includes all runtime deps
Port already in usePort 3000 occupiedChange PORT env var: PORT=3001 node server.js
Module parse failedESM/CJS compatibilityCheck Next.js version supports your dependencies

Build size optimisation:

Check the size of your standalone build:

# From project root
du -sh .next/standalone

A typical Next.js 16 starter should be around 80-120 MB. If significantly larger:

  1. Audit dependencies: Use pnpm why <package> to understand why packages are included
  2. Remove unused packages: Clean up package.json
  3. Check for large assets: Ensure images/videos aren't bundled unnecessarily
  4. Analyse bundle: Use @next/bundle-analyzer

Setting up bundle analyzer (optional):

pnpm add -D @next/bundle-analyzer

Update next.config.ts:

import type { NextConfig } from "next";
import bundleAnalyzer from '@next/bundle-analyzer';
 
const withBundleAnalyzer = bundleAnalyzer({
  enabled: process.env.ANALYZE === 'true',
});
 
const nextConfig: NextConfig = {
  output: 'standalone',
  // ... other config
};
 
export default withBundleAnalyzer(nextConfig);

Analyse your bundle:

ANALYZE=true pnpm build

This opens a visual breakdown of your bundle in the browser, helping identify optimisation opportunities.

Project Structure Best Practices for Azure Deployment

Let's organise the project for optimal maintainability and Azure deployment.

my-nextjs-azure-app/
├── .azure/                         # Azure-specific configurations (Part 2)
│   └── pipelines/
│       └── azure-pipelines.yml
├── .github/                        # OR, GitHub configurations
│   └── workflows/
├── public/                         # Static assets
│   ├── images/
│   ├── fonts/
│   └── favicon.ico
├── src/
│   ├── app/                        # Next.js App Router
│   │   ├── api/                   # API routes
│   │   ├── (auth)/                # Route groups
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── components/                 # Reusable React components
│   │   ├── ui/                    # UI primitives
│   │   └── layout/                # Layout components
│   ├── lib/                        # Utility functions and shared code
│   │   ├── utils.ts
│   │   └── constants.ts
│   ├── types/                      # TypeScript type definitions
│   └── styles/                     # Global styles
├── .env.local                      # Local environment variables
├── .env.example                    # Example environment variables template
├── .env.production                 # Production env vars (not committed)
├── .eslintrc.json
├── .gitignore
├── .npmrc                          # PNPM configuration
├── next.config.ts
├── package.json
├── pnpm-lock.yaml
├── postcss.config.mjs
├── README.md
├── tailwind.config.ts
└── tsconfig.json

Environment variable management:

Create .env.local for development (never commit this):

# .env.local - DO NOT COMMIT
NODE_ENV=development
NEXT_PUBLIC_API_URL=http://localhost:4000
DATABASE_URL=postgresql://localhost:5432/mydb
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

Important:

Add .env.local to .gitignore:

# .gitignore additions
.env.local
.env.production
.env*.local

Understanding Next.js environment variables:

Next.js has specific rules for environment variables:

  1. NEXT_PUBLIC_ variables:

    • Exposed to the browser
    • Embedded at build time
    • Use for API endpoints, public configuration
    • Example: NEXT_PUBLIC_API_URL
  2. Server-only variables:

    • Only available in server components and API routes
    • Never exposed to the browser
    • Use for secrets, database URLs, API keys
    • Example: DATABASE_URL

Azure-specific environment variables (Part 3):

Azure App Service provides built-in variables you can use:

// src/lib/azure-config.ts
export const azureConfig = {
  // Azure provides these automatically
  websiteSiteName: process.env.WEBSITE_SITE_NAME,
  websiteHostname: process.env.WEBSITE_HOSTNAME,
  websiteInstanceId: process.env.WEBSITE_INSTANCE_ID,
 
  // Your custom variables (set in Azure Portal)
  apiUrl: process.env.NEXT_PUBLIC_API_URL,
  databaseUrl: process.env.DATABASE_URL,
};

Your Azure Hosted NextJs 16 Deployment is almost complete

Setting up Next.js 16 with PNPM for Azure App Service deployment requires specific configuration considerations that differ from the default Vercel-optimised setup. By implementing standalone output mode and configuring PNPM's package hoisting, you've created a foundation for efficient, reliable Azure deployments.

The key takeaways from this guide:

  1. Standalone mode is essential for Azure App Service deployments, dramatically reducing size and complexity
  2. PNPM's hoisting configuration ensures compatibility with Node.js runtime expectations on Azure
  3. Proper project structure and environment variable management set you up for success in production
  4. Validation before deployment catches issues early in the development cycle

With these configurations in place, your Next.js application is ready for automated deployment via Azure DevOps pipelines. The standalone build we've created will deploy efficiently, start quickly, and run reliably on Azure App Service.

In the next article, we'll automate the entire standalone build process using Azure DevOps, implementing CI/CD best practices for continuous delivery to Azure.

Did you find this guide helpful?

Share it with your team, and stay tuned for Part 2 where we dive into Azure DevOps CI/CD pipeline configuration!

In Part 2, we'll cover:

  • Creating an Azure App Service
  • Setting up Azure DevOps organisation and project
  • Configuring service connections to Azure
  • Writing the complete Azure Pipelines YAML configuration
  • Building and deploying automatically on every commit
  • Managing environment-specific configurations
  • Handling secrets with Azure Key Vault
  • Pipeline optimisation and caching strategies

Additional Resources

Official Documentation:

Useful Tools:

Community:

Rawson Wade

Written by

Rawson Wade

Labs Lead, Modern 42

Rawson leads Modern 42's Labs team with deep expertise in Microsoft Entra ID and Azure identity platforms. He has delivered countless IAM and PAM implementations for Australian government and large enterprises.

Let’s talk about your identity challenges

No pitch decks. No pressure. Just a straightforward conversation about where you are, where you need to be, and how we can help you get there.

  • Understand your current identity posture
  • Identify quick wins and critical gaps
  • Get actionable recommendations, no strings attached

Free 30 min discussion

No commitment required

Book a time that works for you. We’ll come prepared with initial observations about your industry and common identity challenges.

We use cookies

We use cookies and similar technologies to help personalise content, measure the performance of our site, and provide a better experience. By clicking Accept, you consent to the use of all cookies.
Learn more.