# Netlify
> [Applies to: **/*] This guide provides opinionated, actionable best practices for building, deploying, and maintaining high-performance, secure, and scalable Jamstack applications on Netlify. It focuses on modern workflows, code quality, and leveraging Netlify's edge-first architecture.
- Skill: `tryboy869/netlify` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add tryboy869/netlify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tryboy869/netlify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Tryboy869 (https://skillmd.com/u/tryboy869)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tryboy869/netlify
---
# netlify Best Practices
Netlify is the definitive platform for the Jamstack. Our workflow prioritizes pre-built, edge-first deployments, ensuring maximum performance, security, and developer experience. These guidelines enforce a consistent, high-quality approach to building for the modern web on Netlify.
## 1. Code Organization and Build Configuration
Always centralize your build logic and deployment settings in `netlify.toml`. This ensures consistency and reproducibility across environments and team members.
### ✅ GOOD: Standardized `netlify.toml`
```toml
# netlify.toml
[build]
command = "npm run build" # Your project's build command
publish = "dist" # Directory containing your built static assets
functions = "netlify/functions" # Directory for Netlify Edge/Serverless Functions
# Essential redirects for SPAs or SEO
[[redirects]]
from = "/old-path"
to = "/new-path"
status = 301
[[redirects]]
from = "/*"
to = "/index.html"
status = 200 # For Single Page Applications (SPAs)
# Security headers for all responses
[[headers]]
for = "/*"
[headers.values]
X-Frame-Options = "DENY"
X-XSS-Protection = "1; mode=block"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "no-referrer-when-downgrade"
Content-Security-Policy = "default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self';"
Strict-Transport-Security = "max-age=63072000; includeSubDomains; preload"
```
### ❌ BAD: Relying on UI settings or missing critical configurations
```toml
# netlify.toml (incomplete)
[build]
command = "npm run build"
publish = "build"
# Missing redirects, functions path, and crucial security headers.
# This leads to inconsistent deployments, SEO issues, and security vulnerabilities.
```
## 2. Environment Variables and Secrets Management
Never hardcode sensitive information. Use Netlify's encrypted environment variables for all secrets. Differentiate between build-time and runtime variables.
### ✅ GOOD: Secure Environment Variables
```javascript
// netlify/functions/api.js
import fetch from 'node-fetch';
export async function handler(event, context) {
const API_KEY = process.env.MY_EXTERNAL_API_KEY; // Fetched securely at runtime
if (!API_KEY) {
return { statusCode: 500, body: 'API Key not configured.' };
}
// ... use API_KEY
}
```
```bash
# In Netlify UI or netlify.toml (for build-time only, generally prefer UI for secrets)
# netlify.toml
[build.environment]
# Only for variables needed during the build process, e.g., for a static site generator
GATSBY_API_URL = "https://api.example.com/public"
```
### ❌ BAD: Hardcoding secrets or exposing them in client-side bundles
```javascript
// src/components/MyComponent.js
const API_KEY = "sk_YOUR_SECRET_KEY_HERE"; // NEVER DO THIS!
// This key will be bundled with your client-side code and exposed.
```
## 3. Performance Optimization
Leverage Netlify's edge network and build process for maximum speed.
### ✅ GOOD: Image Optimization with Build Plugins
Use Netlify Build Plugins for automated image optimization.
```toml
# netlify.toml
[[plugins]]
package = "@netlify/plugin-nextjs" # Example for Next.js, includes image optimization
# Or a dedicated image optimization plugin:
# package = "@netlify/plugin-image-optim"
```
### ❌ BAD: Serving unoptimized, large images
```html
```
## 4. Edge Functions for Dynamic Logic
Move lightweight server-side logic to the edge with Netlify Edge Functions for faster response times and reduced latency.
### ✅ GOOD: Edge Function for A/B Testing or Geo-targeting
```typescript
// netlify/edge-functions/geo-redirect.ts
import type { Context } from "https://edge.netlify.com/";
export default async (request: Request, context: Context) => {
const country = context.geo?.country?.name || "Unknown";
if (country === "Germany") {
return Response.redirect(new URL("/de", request.url));
}
// Continue to the original page
return context.next();
};
```
### ❌ BAD: Relying on traditional serverless functions for every request
```javascript
// netlify/functions/slow-geo-check.js (traditional serverless function)
exports.handler = async (event, context) => {
// This will incur higher latency than an Edge Function for simple routing logic.
const ip = event.headers['x-forwarded-for'];
// ... complex IP-to-geo lookup (slow)
return { statusCode: 200, body: `Hello from ${country}` };
};
```
## 5. Testing and CI/CD Hygiene
Integrate automated testing and quality checks into your Netlify build pipeline.
### ✅ GOOD: Automated Linting, Type Checking, and E2E Tests
Ensure your `package.json` scripts support these, and Netlify's build command triggers them.
```json
// package.json
{
"scripts": {
"build": "npm run lint && npm run typecheck && next build",
"lint": "eslint . --ext .js,.jsx,.ts,.tsx",
"typecheck": "tsc --noEmit",
"test:e2e": "cypress run"
}
}
```
```toml
# netlify.toml
[build]
command = "npm run build" # This will run lint and typecheck before the actual build
publish = "out"
[context.deploy-preview]
command = "npm run build && npm run test:e2e" # Run E2E tests on deploy previews
```
### ❌ BAD: Skipping quality checks in CI
```toml
# netlify.toml
[build]
command = "next build" # No linting, type checking, or tests before deployment.
publish = "out"
# This allows broken code to reach deploy previews or even production.
```
## 6. Accessibility
Accessibility is a non-negotiable part of modern web development. Integrate tools to enforce it.
### ✅ GOOD: Automated Accessibility Checks
Use tools like Lighthouse CI or Pa11y in your build process.
```json
// package.json
{
"scripts": {
"build": "next build",
"audit:a11y": "lighthouse ci --config=./.lighthouseci.json"
}
}
```
```toml
# netlify.toml
[build]
command = "npm run build"
publish = "out"
[context.production]
command = "npm run build && npm run audit:a11y" # Run a11y audit on production builds
```
### ❌ BAD: Ignoring accessibility until manual review
```html
```
## 7. Decoupled Architecture and API-First Development
Embrace the Jamstack philosophy: frontend decoupled from backend. Interact with services via APIs.
### ✅ GOOD: Consuming external APIs
```javascript
// src/utils/dataService.js
export async function fetchProducts() {
const response = await fetch('/.netlify/functions/getProducts'); // Call a Netlify Function acting as an API gateway
if (!response.ok) {
throw new Error('Failed to fetch products');
}
return response.json();
}
```
### ❌ BAD: Tightly coupled frontend and backend
```javascript
// src/server.js (monolithic approach)
// This file would not run on Netlify's static hosting.
// Attempting to deploy a traditional server-side app directly to Netlify will fail.
const express = require('express');
const app = express();
// ... server-side logic
```