netlify-development

# Netlify Development Best Practices ## Overview This skill provides comprehensive guidelines for building and deploying projects on Netlify, covering serverless functions, edge functions, background functions, scheduled functions, Netlify Blobs, Image CDN, and deployment configuration. ## Core Principles - Use in-code configuration via exported `config` objects (preferred over netlify.toml) - Never add version numbers to imported Netlify packages (use `@netlify/functions`, never `@netlify/functions@1.2.3`) - Only add CORS headers when explicitly required - Leverage appropriate function types for different use cases - Use Netlify Blobs for state and data storage - The `.netlify` folder is generated tooling output, not user code — keep it in `.gitignore` - Never put serverless or edge functions inside the publish/public directory - Don't change the default functions or edge-functions directory unless explicitly asked to ## Function Types Overview | Type | Use Case | Timeout | Path Convention | |------|----------|---------|-----------------| | Serverless | Standard API endpoints | 10s (26s Pro) | `/.netlify/functions/name` | | Edge | Request/response modification | 50ms CPU | Custom paths | | Background | Long-running async tasks | 15 minutes | `-background` suffix | | Scheduled | Cron-based tasks | 30s | Configured schedule | Function and edge-function source directories default to `netlify/functions` and `netlify/edge-functions`, but can be overridden in `netlify.toml`: ```toml [functions] directory = "my_functions" [build] edge_functions = "my-edge-functions" ``` `netlify.toml` settings override UI build-settings configuration. ## Serverless Functions ### Basic Structure ```typescript // netlify/functions/hello.mts import type { Context } from '@netlify/functions'; export default async (request: Request, context: Context) => { try { // Validate request if (request.method !== 'POST') { return new Response('Method Not Allowed', { status: 405 }); } const body = await request.json(); // Business logic const result = await processData(body); return Response.json(result); } catch (error) { console.error('Function error:', error); return Response.json({ error: 'Internal Server Error' }, { status: 500 }); } }; export const config = { path: '/api/hello', }; ``` ### Configuration Options ```typescript export const config = { // Custom path (instead of /.netlify/functions/name) path: '/api/users', // HTTP methods (optional, allows all by default) method: ['GET', 'POST'], // Rate limiting rateLimit: { windowSize: 60, windowLimit: 100, }, }; ``` ### Path Conventions - Default path: `/.netlify/functions/{function_name}` - Custom paths via config completely replace the default - Use custom paths for cleaner API URLs ### The Context Argument Both serverless and edge functions receive a `context` object as their second argument: ```typescript { account: { id: string }; // Netlify team account ID cookies: { get: (name: string) => string | undefined; set: (options: { name: string; value: string; path?: string; domain?: string; secure?: boolean; httpOnly?: boolean; expires?: Date }) => void; delete: (nameOrOptions: string | { name: string; path?: string; domain?: string }) => void; }; deploy: { context: string; id: string; published: boolean }; geo: { city: string; country: { code: string; name: string }; latitude: number; longitude: number; subdivision: { code: string; name: string }; timezone: string; postalCode: string; ip: string; }; params: Record<string, string>; // route params from the path config requestId: string; server: { region: string }; site: { id: string; name: string; url: string }; } ``` ### The `Netlify` Global Object Available in global scope on all serverless and edge functions — prefer `Netlify.env.*` over `process.env` for reading/writing environment variables at runtime: ```typescript { context: object | null; // same as the function's second arg; null outside a handler env: { get: (name: string) => string | undefined; has: (name: string) => boolean; set: (name: string, value: string) => void; delete: (name: string) => void; toObject: () => Record<string, string>; }; } ``` ## Edge Functions ### Use Cases - Modify requests before they reach the origin - Modify responses before returning to users - Geolocation-based personalization - A/B testing - Authentication at the edge ### Implementation ```typescript // netlify/edge-functions/geo-redirect.ts import type { Context } from '@netlify/edge-functions'; export default async (request: Request, context: Context) => { const country = context.geo.country?.code || 'US'; // Redirect based on country if (country === 'DE') { return Response.redirect(new URL('/de', request.url)); } // Continue to origin return context.next(); }; export const config = { path: '/*', excludedPath: ['/api/*', '/_next/*'], }; ``` ### Response Modification ```typescript export default async (request: Request, context: Context) => { // Get response from origin const response = await context.next(); // Modify headers response.headers.set('X-Custom-Header', 'value'); // Transform HTML const html = await response.text(); const modifiedHtml = html.replace('</body>', '<script>...</script></body>'); return new Response(modifiedHtml, { status: response.status, headers: response.headers, }); }; ``` ### Runtime and Module Support Edge functions run on Deno, not Node.js, and can pull in code from several ecosystems: - Node.js built-ins: `import { randomBytes } from 'node:crypto'` - Deno modules: URL imports, e.g. `import React from 'https://esm.sh/react'` - npm packages (beta): install via `npm install` and import by name — packages with native binaries (e.g., Prisma) or dynamic requires may not work - Import maps let you reference third-party modules by short name instead of full URL; declare the map file path via `[functions] deno_import_map = "./import_map.json"` in `netlify.toml` Available Web APIs are more limited than Node.js: `fetch`/`Request`/`Response`/`URL`, `TextEncoder`/`TextDecoder` (and stream variants), Web Crypto (`randomUUID`, `getRandomValues`, `SubtleCrypto`), `WebSocket`, `setTimeout`/`setInterval`, the Streams API, and `URLPattern`. ### Extra Config Options Beyond `path` and `excludedPath`, edge function config supports: ```typescript { pattern?: RegExp | RegExp[]; // regex alternative to `path` excludedPattern?: RegExp | RegExp[]; method?: string | string[]; onError?: 'continue' | 'fail' | 'fallback'; cache?: 'manual'; // opt in to edge response caching } ``` ### Ordering Multiple Edge Functions When several edge functions can match the same path, declare them in `netlify.toml` for explicit top-to-bottom ordering (cached functions always run last regardless of position): ```toml [[edge_functions]] path = "/admin" function = "auth" [[edge_functions]] path = "/admin" function = "injector" cache = "manual" ``` Execution order: config-based functions run before framework-generated ones, which run before user-defined inline functions; non-cached functions run before cached ones; multiple inline functions run alphabetically by filename. Use `context.next()` to continue the chain rather than re-triggering functions with `fetch()`/`URL()` (which starts a new request chain). ### Limits and Incompatibilities - 20 MB compressed code size, 512 MB memory per deployment, 50ms CPU time per request, 40s response-header timeout - Not compatible with split testing, `_headers`/`netlify.toml` custom headers, or prerendering on paths an edge function serves - Can only rewrite requests to same-site URLs — use `fetch()` for external content - Not included in Netlify's HIPAA-compliant hosting offering ## Background Functions ### Key Characteristics - 15-minute timeout (wall clock time) - Immediately return 202 status code - Return values are ignored - Must have `-background` suffix ### Implementation ```typescript // netlify/functions/process-video-background.mts import type { Context } from '@netlify/functions'; import { getStore } from '@netlify/blobs'; export default async (request: Request, context: Context) => { const { videoId } = await request.json(); // Long-running processing const result = await processVideo(videoId); // Store result for later retrieval const store = getStore('processed-videos'); await store.setJSON(videoId, result); // Return value is ignored return new Response('Processing complete'); }; export const config = { path: '/api/process-video', }; ``` ### Retrieving Background Results ```typescript // netlify/functions/get-video-status.mts import { getStore } from '@netlify/blobs'; export default async (request: Request, context: Context) => { const url = new URL(request.url); const videoId = url.searchParams.get('id'); const store = getStore('processed-videos'); const result = await store.get(videoId, { type: 'json' }); if (!result) { return Response.json({ status: 'processing' }); } return Response.json({ status: 'complete', data: result }); }; ``` ## Scheduled Functions ### Key Characteristics - CRON expressions are evaluated in UTC, with a 1-minute minimum interval - 30-second execution limit; the function does not return a response body (the return value is ignored) - The request body is a JSON-encoded object with a `next_run` field — the ISO-8601 timestamp of the next scheduled invocation - Scheduled functions only run on published deploys — they do **not** run on deploy previews or branch deploys - Test locally by running `netlify dev` alongside `netlify functions:invoke <name>` - Schedules can also live in `netlify.toml` for consistency with other config, but in-code `config.schedule` is preferred: ```toml [functions."daily-cleanup"] schedule = "@daily" ``` ### Configuration ```typescript // netlify/functions/daily-cleanup.mts import type { Context } from '@netlify/functions'; export default async (request: Request, context: Context) => { console.log('Running daily cleanup...'); // Cleanup logic await cleanupOldRecords(); return new Response('Cleanup complete'); }; export const config = { schedule: '@daily', // or '0 0 * * *' for midnight UTC }; ``` ### Schedule Patterns ```typescript // Common patterns export const config = { schedule: '@hourly', // Every hour schedule: '@daily', // Every day at midnight schedule: '@weekly', // Every week schedule: '*/15 * * * *', // Every 15 minutes schedule: '0 9 * * 1-5', // 9 AM on weekdays }; ``` ## Netlify Blobs Prefer Blobs over standing up a new database unless the data needs relational structure or search — Blobs require no provisioning and share the same API across all compute types. Limits: store names ≤64 bytes, object keys ≤600 bytes, max object size 5GB. ### Consistency and Storage Scopes - By default, stores are **eventually consistent** — fast reads, with writes propagating within about 60 seconds. Pass `{ consistency: 'strong' }` to `getStore` for immediate read-after-write visibility at the cost of slower reads. - There's no built-in concurrency control — the last write wins. Add your own locking if concurrent writers must not clobber each other. - Deploy-specific stores (`getDeployStore`) sync with a deploy and are removed when that deploy is deleted; global stores (`getStore`) persist across all branches and are never auto-cleaned. Build plugins and file-based uploads must write to deploy-specific stores. - When writing to a global store, guard against non-production data leaking in by branching on `context.deploy.context`: ```typescript function getBlobStore(...args: Parameters<typeof getStore>) { return context.deploy.context === 'production' ? getStore(...args) : getDeployStore(...args); } ``` ### Basic Usage ```typescript import { getStore } from '@netlify/blobs'; // Get a store const store = getStore('my-store'); // Store data await store.set('key', 'string value'); await store.setJSON('json-key', { foo: 'bar' }); // Retrieve data const value = await store.get('key'); const jsonValue = await store.get('json-key', { type: 'json' }); // Delete data await store.delete('key'); // List keys const { blobs } = await store.list(); ``` ### Binary Data ```typescript import { getStore } from '@netlify/blobs'; const store = getStore('files'); // Store binary data const arrayBuffer = await file.arrayBuffer(); await store.set('uploads/file.pdf', arrayBuffer, { metadata: { contentType: 'application/pdf' },