Deployment on Netlify (Build, Redirects, and Headers) Feature Documentation

Overview

The Deployment on Netlify feature centralizes the site’s build, routing, and HTTP header configuration in a single netlify.toml file. When code is pushed to the repository, Netlify’s CI/CD pipeline runs the npm run build command to assemble all HTML, CSS, JavaScript, and assets into a dist/ directory. This directory is then published to Netlify’s global CDN, delivering highly performant static content.

At the edge, custom redirect rules ensure clean URLs and handle 404 fallbacks, while security headers (e.g., clickjacking and XSS protections) and caching directives optimize both safety and load times. This configuration eliminates the need for a separate backend, enabling a lean, SEO-friendly, and secure multi-page marketing site.

Architecture Overview

flowchart TB
    Developer[Developer pushes to GitHub] --> NetlifyCI[Netlify CI/CD]
    NetlifyCI --> BuildStep["npm run build"]
    BuildStep --> Dist[dist/ directory]
    Dist --> Publish[Netlify Publish to CDN]
    Publish --> Edge[Edge Network]
    Edge --> Redirects[Apply Redirect Rules]
    Edge --> Headers[Inject Security & Caching Headers]
    Edge --> Browser[End User's Browser]

Component Structure

1. Build Configuration

netlify.toml

  • publish directory: dist
  • build command: npm run build
  • production environment variables:
    • NODE_VERSION = "20"

2. Redirect Rules

netlify.toml

From Pattern To Target Status Code Description
/* /index.html 200 Clean-URL support (SPA fallback)
/* /404.html 404 Global 404 fallback for unmatched routes

3. Security & Performance Headers

netlify.toml

3.1 Site-wide Security Headers

Header Value Purpose
X-Frame-Options DENY Prevents clickjacking by disallowing framing of pages
X-Content-Type-Options nosniff Stops browsers from MIME-sniffing
X-XSS-Protection 1; mode=block Enables built-in browser XSS filters to block detected attacks
Referrer-Policy strict-origin-when-cross-origin Limits referrer information for cross-site requests to just the origin

3.2 Asset Caching Headers

Path Pattern Header Value Considerations
/images/* Cache-Control public, max-age=31536000, immutable Ideal for versioned image assets that never change
/assets/* Cache-Control public, max-age=31536000, immutable Suitable for hashed CSS/JS; if assets are unversioned, use a shorter max-age to avoid stale content

Guidance: When serving assets without filename hashing (e.g., main.css), reduce max-age (for example, to 86400 seconds) or employ cache-busting query parameters so browsers fetch updated files promptly.

4. Environment Variables

netlify.toml

Variable Value Description
NODE_VERSION "20" Node.js version for the production build

Feature Flows

Deployment Pipeline Flow

sequenceDiagram
    participant D as Developer
    participant GH as GitHub
    participant CI as Netlify CI/CD
    participant BS as Build Step
    participant DF as dist/ Folder
    participant ND as Netlify Deploy
    participant E as Edge Network
    participant U as User Browser

    D->>GH: Push to main branch
    GH->>CI: Trigger build
    CI->>BS: Run npm run build
    BS->>DF: Generate dist/ artifacts
    DF->>ND: Publish to CDN
    ND->>E: Distribute across edge nodes
    U->>E: Request page or asset
    E->>E: Apply Redirects & Headers
    E-->>U: Serve response

Caching Strategy

  • Immutable Caching: Assets under /images/* and /assets/* are marked immutable with a one-year max-age, allowing browsers to cache them aggressively without revalidation.
  • Versioned vs. Unversioned Assets: For unversioned files, shorten caching durations or append query strings (e.g., ?v=2) when content updates to prevent clients from using stale resources.

Testing Considerations

  • Verify headers with curl -I https://<site>/path/to/resource and inspect Cache-Control, X-Frame-Options, etc.
  • Confirm 404 behavior by requesting a non-existent URL and checking for status 404 and delivery of 404.html.
  • Use browser DevTools Network panel to ensure header values and caching policies are applied correctly.

Key Files Reference

File Responsibility
netlify.toml Configures Netlify build, environment, redirects, and HTTP headers