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 markedimmutablewith a one-yearmax-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/resourceand inspectCache-Control,X-Frame-Options, etc. - Confirm 404 behavior by requesting a non-existent URL and checking for status
404and delivery of404.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 |