description: Guidelines and best practices for building Netlify projects & sites, including serverless functions, edge functions, functions, storage, and real-world examples
Add this skill
npx mdskills install PatrickJS/cursor-netlify-officialComprehensive Netlify development rules with detailed function types, config patterns, and API context.
// Developers can override the content as needed, but it should all be placed in this section.
ANY RULES IN THE ProviderContextOverrides SECTION CAN OVERRULE SPECIFIC RULES IN ProviderContext
.netlify folder is not for user code. It should be added to the .gitignore list@netlify/functions and never @netlify/functions@VERSION)netlify dev to start dev server unless another dev command is requested by the userBelow are the available fields/functions from the context argument to serverless and edge functions.
{
account: {
id: string, // Unique ID of the Netlify team account associated with the site and function.
},
cookies: {
get: (name: string) => string | undefined, // Reads a cookie from the incoming request.
set: (options: { name: string; value: string; path?: string; domain?: string; secure?: boolean; httpOnly?: boolean; expires?: Date }) => void, // Sets a cookie on the outgoing response following the CookieStore.set web standard.
delete: (nameOrOptions: string | { name: string; path?: string; domain?: string }) => void, // Deletes a cookie on the outgoing response, following the CookieStore.delete web standard.
},
deploy: {
context: string, // The deploy context (e.g., production, deploy-preview).
id: string, // Unique ID of the deploy the function belongs to.
published: boolean, // Indicates whether the function belongs to the currently published deploy.
},
geo: {
city: string, // City name of the client location.
country: {
code: string, // ISO 3166 country code.
name: string, // Full country name.
},
latitude: number, // Latitude coordinate of the client location.
longitude: number, // Longitude coordinate of the client location.
subdivision: {
code: string, // ISO 3166 subdivision code (e.g., state or province).
name: string, // Subdivision name.
},
timezone: string, // Timezone of the location.
postalCode: string, // Postal code of the location in its regional format.
ip: string, // Client IP address.
},
params: Record, // Object containing route parameters from the function path configuration.
requestId: string, // Unique Netlify request ID.
server: {
region: string, // The region code where the deployment is running (e.g., us-east-1).
},
site: {
id: string, // Unique ID for the Netlify site.
name: string, // The site's Netlify subdomain name.
url: string, // The main address of the site, which could be a Netlify subdomain or a custom domain.
},
}
Netlify global objectNetlify object is available in global scope.It has the following fields/functions:
{
context: object | null, // The Netlify-specific context object - same as function's second arg. Available only within function handlers or child scopes; otherwise, it returns null.
env: {
delete: (name: string) => void, // Deletes an environment variable within the context of the invocation.
get: (name: string) => string | undefined, // Retrieves the string value of an environment variable; returns undefined if not defined.
has: (name: string) => boolean, // Checks if an environment variable exists; returns true if it does, otherwise false.
set: (name: string, value: string) => void, // Sets an environment variable within the invocation context.
toObject: () => Record, // Returns an object containing all environment variables and their values.
},
};
npm install @netlify/functionsNetlify object that is also accessible.
Netlify.env.* for interacting with environment variables in code.YOUR_BASE_DIRECTORY/netlify/functions or a subdirectory.
netlify.toml:
[functions]
directory = "my_functions"
netlify.toml settings override UI settings.index.mts or match the subdirectory name.
netlify/functions/hello.mtsnetlify/functions/hello/index.mtsnetlify/functions/hello/hello.mts.mts enables modern ES module syntax- ```typescript
import type { Context, Config } from "@netlify/functions";
export default async (req: Request, context: Context) => {
// user code
return new Response("Hello, world!")
}
export const config: Config = {
// use this path instead of /.netlify/functions/{fnName}
path: "/hello-world"
};
```
- ```javascript
export default async (req, context) => {
// user code
return new Response("Hello, world!")
}
export const config = {
// use this path instead of /.netlify/functions/{fnName}
path: "/hello-world"
};
```
config object. This is the structure the config can have:/.netlify/functions/{function_name} path by default.{
path: string | string[], // Defines the URL path(s) that trigger the function. Can be a single string or an array of paths.
excludedPath?: string | string[], // Optional. Defines paths that should be excluded from triggering the function.
preferStatic?: boolean, // Optional. If true, prevents the function from overriding existing static assets on the CDN.
}
import { Context } from "@netlify/functions";
export default async (req: Request, context: Context) => {
await someLongRunningTask();
console.log("Done");
};
export default async (req, context) => {
await someLongRunningTask();
console.log("Done");
};
next_run property. It represents the timestamp of the next scheduled invocation, as a string in the ISO-8601 format.netlify.toml. ONLY do this for consistency or if explicitly asked to keep all schedules in one place.
[functions."test-scheduled-function"]
schedule = "@hourly"
netlify functions:invoke command to trigger the scheduled function.
example:
netlify functions:invoke myfunction
import type { Config } from "@netlify/functions"
export default async (req: Request) => {
const { next_run } = await req.json()
console.log("Received event! Next invocation at:", next_run)
}
export const config: Config = {
schedule: "@hourly"
}
export default async (req) => {
const { next_run } = await req.json()
console.log("Received event! Next invocation at:", next_run)
}
export const config = {
schedule: "@hourly"
}
ALWAYS use the latest format of an edge function structure.
DO NOT add CORS headers (such as Access-Control-Allow-Origin) unless explicitly asked for them.
if using typescript, ensure types are installed from npm install @netlify/edge-functions
DO NOT put global logic outside of the exported function unless it is wrapped in a function definition
ONLY use vanilla javascript if there are other ".js" files in the functions directory.
ALWAYS use typescript if other functions are typescript or if there are no existing functions.
The first argument is a web platform Request object that represents the incoming HTTP request
The second argument is a custom Netlify context object.
Edge functions have a global Netlify object that is also accessible.
Netlify.env.* for interacting with environment variables in code.Place function files in YOUR_BASE_DIRECTORY/netlify/edge-functions or a subdirectory.
netlify.toml:
[build]
edge_functions = "my-custom-directory"
Edge functions use Deno as runtime and should attempt to use built-in methods where possible. See the list of available web APIs to know which built-ins to use.
node: prefix (e.g., import { randomBytes } from "node:crypto").import React from "https://esm.sh/react" or an import map).npm install and import by package name (e.g., import _ from "lodash").deno.json).import_map.json):
{
"imports": {
"html-rewriter": "https://ghuc.cc/worker-tools/html-rewriter/index.ts"
}
}
netlify.toml:
[functions]
deno_import_map = "./path/to/your/import_map.json"
import { HTMLRewriter } from "html-rewriter";
- ```typescript
import type { Context, Config } from "@netlify/edge-functions";
export default async (req: Request, context: Context) => {
// user code
return new Response("Hello, world!")
}
export const config: Config = {
path: "/hello-world"
};
```
- ```javascript
export default async (req, context) => {
// user code
return new Response("Hello, world!")
}
export const config = {
path: "/hello-world"
};
```
{
...ALL OTHER Context fields/methods,
next: (options?: { sendConditionalRequest?: boolean }) => Promise, // Invokes the next item in the request chain, optionally using conditional requests.
nextRequest: (request: Request, options?: { sendConditionalRequest?: boolean }) => Promise, // Same as next(), but requires an explicit Request object.
}
config object. This is the structure the config can have:{
path?: string | string[], // URLPattern expression defining paths where the edge function should run. Must start with '/'.
excludedPath?: string | string[], // Optional. Defines paths to exclude from execution. Must start with '/'.
pattern?: RegExp | RegExp[], // Alternative to `path`. Uses regex for path matching.
excludedPattern?: RegExp | RegExp[], // Optional. Defines regex patterns to exclude certain routes.
method?: string | string[], // Optional. Specifies HTTP methods that should trigger the function (e.g., "GET", ["POST", "PUT"]).
onError?: "continue" | "fail" | "fallback", // Optional. Controls how the function handles errors.
cache?: 'manual', // Optional. Enables response caching if set to 'manual'.
} = {
path: "", // Default value; should be set per function.
};
ONLY Use netlify.toml for precise function order control instead of inline declarations.
DO NOT use netlify.toml if there is not edge function ordering requirements.
When controlling order, it's important to include all edge functions for order control.
Declare Edge Functions in netlify.toml:
Edge Function Properties:
function: Name of the edge function.path: URL pattern to trigger the function (must start with /).excludedPath: Excludes specific routes from path (supports string or array).pattern: Regex-based path matching.excludedPattern: Excludes specific regex patterns (single or array).cache: Enables response caching (cached functions run after non-cached ones) set to 'manual' to opt in.Netlify.toml config examples
[[edge_functions]]
path = "/admin"
function = "auth"
[[edge_functions]]
path = "/admin"
function = "injector"
cache = "manual"
[[edge_functions]]
path = "/blog/*"
function = "auth"
[[edge_functions]]
path = "/blog/*"
function = "rewriter"
[[edge_functions]]
pattern = "/products/(.*)"
excludedPattern = "/products/things/(.*)"
function = "highlight"
[[edge_functions]]
path = "/*"
excludedPath = "/img/*"
function = "common"
- **Execution Order for Edge Functions**:
1. **Configuration-based** edge functions (`netlify.toml`) run first.
2. **Framework-generated** edge functions execute before user-defined functions.
3. **Non-cached** edge functions execute before cached functions.
4. **Inline-declared** edge functions override duplicate `netlify.toml` functions.
5. **Multiple inline edge functions** run alphabetically by filename.
- **Caveats & Special Cases**:
- If an edge function returns a response, redirects for that path DO NOT occur.
- Edge functions DO NOT execute for rewritten static routing targets.
- `fetch()` or `URL()` triggers a **new request chain**, re-running matching functions.
- Use `context.next()` to continue processing instead of re-triggering functions.
- Function failure behavior depends on its **error handling configuration**.
#### Edge functions limitations
- 20 MB (compressed) code size limit
- 512 MB per deployment memory limit
- 50ms per request CPU execution time (excludes waiting time)
- 40 seconds Response header timeout
- **Not compatible with these Netlify features**:
- Netlify's split testing feature
- Custom Headers (including basic authentication) from _headers or netlify.toml config
- Netlify prerendering feature on paths served by edge functions
- Be aware that multiple framework adapters may generate conflicting edge functions
- **Restrictions**:
- Can only rewrite requests to same-site URLs (use `fetch()` for external content)
- Cached edge functions override existing static files
- No local caching; HTTP cache headers are ignored in local testing
- Not included in Netlify’s HIPAA-compliant hosting offering
## Netlify Blobs
- Prefer using Netlify Blobs over creating a new database unless a flat file is not appropriate data layer, if explicitly asking to use a tool, or the dev needs to created relational structures or search that's more appropriate for databases
- Blobs do not require configuration to use, everything is automatically provisions, and devs can simply start using them via any Netlify compute. The API will be the same across all compute types.
- ensure `@netlify/blobs` NPM module is installed
- Requirements and limits
- Requires Fetch API support (Node.js 18+ recommended) - a fetch function can be provided to the store
- Store names cannot exceed 64 bytes
- Object keys cannot exceed 600 bytes
- Maximum object size: 5GB
- Local development uses a sandboxed store
### Netlify Blobs API
```typescript
export interface BlobMetadata {
[key: string]: any;
}
export interface BlobData {
data: T | null;
etag: string;
metadata: BlobMetadata;
}
export interface ListResult {
blobs: { etag: string; key: string }[];
directories?: string[];
}
interface GetKeyOptions {
type?: 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text'
}
interface GetKeyAndMetadataOptions {
type?: 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text',
etag?: string;
}
// THESE ARE THE ONLY STORE METHODS. DO NOT MAKE UP NEW ONES
interface Store {
// Creates or overwrites a blob entry.
// example: await store.set('key-name', 'contents-of key');
// - NEVER add metadata unless instructed to.
set(key: string, value: ArrayBuffer | Blob | string, { metadata?: object }): Promise;
// Stores a JSON-serializable object.
// example: await store.setJSON('key-name', {version: 'a', someBoolean: true});
// - NEVER add metadata unless instructed to.
setJSON(key: string, value: any, { metadata?: object }): Promise;
// Retrieves a stored blob.
// example: await store.get('key-name');
// - NEVER add the second arg unless you need an explicit type 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text'.
// - Instead of using JSON.parse(blob), use store.get('key-name', {type: 'json'})
// - if the blob is missing, it will resolve the promise with a null value
get(key: string, getOpt?: GetKeyOptions): Promise;
// Retrieves a blob along with metadata
// example: await store.getWithMetadata('key-name');
// - NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against.
// - AVOID adding it unless it's reliably available but IF an etag is provided, it will only return the blob if the etag is different that what's stored.
// - if the blob is missing, it will resolve the promise with a null value
getWithMetadata(key: string, getOpts?: GetKeyAndMetadataOptions): Promise;
// Retrieves metadata of a blob WITHOUT downloading the data.
// example: await store.getMetadata('key-name');
// - NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against.
// - AVOID adding it unless it's reliably available but IF an etag is provided, it will only return the blob if the etag is different that what's stored.
// - if the blob is missing, it will resolve the promise with a null value
getMetadata(key: string, getOpts?: GetKeyAndMetadataOptions): Promise;
// Lists blobs in the store with optional hierarchical browsing.
// example:
// const { blobs } = await store.list()
// // blobs === [ { etag: 'etag1', key: 'some-key' }, { etag: 'etag2', key: 'another-key' } ]
//
// - NEVER add the options arg unless you need an explicit reduce the searched data.
// -- ONLY if you have to reduce searched data, use `prefix: 'some-prefix'` to pull blobs that start with that prefix value. Use `directories: true` to include the full directory path on the `key`
// - By default, the list() method retrieves all pages, meaning you'll always get the full list of results. This can be slow or memory intensive. To paginate, pass the `paginate: true` in the options to turn the response into an AsyncIterator that allows you to for-of loop through the blobs in the store.
// - if store path is empty, the blobs will resolve the promise with an empty array
list(options?: { directories?: boolean, paginate?: boolean. prefix?: string }): Promise | AsyncIterable
// Deletes a blob.
// example: await store.delete('key-name');
// - The return value is always resolves to `undefined`, regardless of whether or not there was an object to delete.
delete(key: string): Promise;
}
interface GetDeployStoreOptions extends Partial {
deployID?: string;
name?: string;
region?: Region;
}
// Returns a store instance for managing blobs. This is global scoped data across all deploys.
// example: const store = getStore('my-store');
// - ONLY add the options argument if the user needs strong consistency
export function getStore(name: string, options?: { consistency?: 'strong' | 'eventual' }): Store;
// Returns a deploy-specific store instance for managing blobs tied to a deploy.
// example: const store = getDeployStore('my-store');
// - ONLY add the options argument if the user needs strong consistency
declare const getDeployStore: (input?: GetDeployStoreOptions | string) => Store;
interface GetStoreOptions extends Partial {
deployID?: string;
name?: string;
}
// Lists all stores available on a site.
// example:
// const { stores } = await listStores();
// // [ "beauty", "construction" ]
// - By default, the listStores() method retrieves all pages, meaning you'll always get the full list of results. This can be slow or memory intensive. To paginate, pass the `paginate: true` in the options to turn the response into an AsyncIterator that allows you to for-of loop through the blobs in the store.
// - DO NOT pass options unless paginating.
declare function listStores(options?: {
paginate?: boolean;
}): Promise | AsyncIterable;
interface ListStoresResponse {
stores: string[];
next_cursor?: string;
}
With file-based uploads, write blobs to deploy-specific stores after the site build completes. Useful for frameworks and other tools integrating with Netlify as it does not require a build plugin.
Put files in .netlify/blobs/deploy/* for deploy specific
.netlify/
├─ blobs/
| ├─ deploy/
│ | ├─ beauty/
│ │ | └─ nails.jpg
To attach metadata to a blob via file upload flows, include a JSON file that prefixes the corresponding blob filename with $ and has a .json extension. For example:
├─ blobs/
| ├─ deploy/
│ | ├─ beauty/
│ │ | ├─ nails.jpg
│ │ | └─ $nails.jpg.json
consistency field to 'strong' on the store instantiation.Example:
const store = getStore({ name: "animals", consistency: "strong" });
await store.set("dog", "ðŸ¶");
const dog = await store.get("dog");
getDeployStore() is used to interact with deploy specific stores.getStore() is used for global scope. // basic writing to a deploy store
import { getDeployStore } from "@netlify/blobs";
const store = getDeployStore("construction");
// basic writing to a global store
import { getStore } from "@netlify/blobs";
const store = getStore("construction");
// using global store if in production, otherwise use deploy scope store
import { getStore, getDeployStore } from "@netlify/blobs";
function getBlobStore(...storeOptions){
if((Netlify.context?.deploy.context === 'production'){
return getStore(...storeOptions);
}
return getDeployStore(...storeOptions)
}
const store = getBlobStore("construction");
/.netlify/images route supported by their site without any additional enablement./.netlify/images.w (width) and h (height) in pixels.contain, cover, fill).top, bottom, left, right, center).avif, jpg, png, webp, gif, or blurhash.q, 1-100, default 75).
netlify.toml.
[images]
remote_images = ["https://externalexample.com/.*"]
/.netlify/images path, a redirect or rewrite can be used to have a different url._redirects or netlify.toml files. [[redirects]]
from = "/transform-my-images/*"
to = "/.netlify/images?url=/:splat&w=50&h=50"
status = 200
/transform-all/* /.netlify/images?url=/:splat&w=50&h=50 200
[[headers]]
for = "/source-images/*"
[headers.values]
Cache-Control = "public, max-age=604800, must-revalidate"
/source-images/* Cache-Control: public, max-age=604800, must-revalidate
Netlify Image CDN integrates with frameworks for automatic optimizations:
NgOptimizedImage component will use Image CDN automaticallyNETLIFY_IMAGE_CDN=true and use the Contentful, Drupal, or WordPress source plugins.remotePatterns in next.config.jsnuxt/image module will use Image CDN automaticallynetlify.toml overrides UI/CLI/API variables, and site-specific variables take precedence over shared ones.Variables can be created and managed using:
netlify.toml): Defines variables at the repository level. ONLY use this for environment variables where the site is not linked yet and the values are not sensitive.env:set for changes, env:unset to delete. env:import to import from a dotenv.env file. netlify env:set API_KEY "not-a-secret"
netlify env:set API_KEY "secret-value" --secret
netlify.toml Configuration # Production context: all deploys from the Production branch
# set in your site’s Branches settings in the UI will inherit
# these settings. You can define environment variables
# here but we recommend using the Netlify UI for sensitive
# values to keep them out of your source repository.
[context.production]
publish = "output/"
command = "make publish"
environment = { NODE_VERSION = "14.15.3" }
# Here is an example of how to define context-specific
# environment variables. Be mindful when using this
# option and avoid committing sensitive values to public
# source repositories.
[context.deploy-preview.environment]
NOT_PRIVATE_ITEM = "not so secret"
# Branch Deploy context: all deploys that are not from
# a pull/merge request or from the Production branch
# will inherit these settings.
[context.branch-deploy.environment]
NODE_ENV = "development"
# Dev context: environment variables set here
# are available for local development environments
# run using Netlify Dev. These values can be
# overwritten on branches that have a more specific
# branch context configured.
[context.dev.environment]
NODE_ENV = "development"
# Specific branch context: all deploys from
# this specific branch will inherit these settings.
[context.staging.environment] # “staging†is a branch name
NODE_ENV = "development"
.env File Handling.env files directly.env variables into Netlify using the UI or CLI (netlify env:import .env)..env files via UI or CLI (env:list)..env Variables# list the production deploy context values in .env format
netlify env:list --plain --context production
# list the production deploy context values in .env format
# and pipe results into a .env file
netlify env:list --plain --context production > .env
PROJECT_FOLDER/.netlify/state.json file exists and it has a populated siteId value.netlify init to allow the user to set up the site with Netlify. If the user deploys manually, it will set up the site to use Netlify automatically. If the user decides to set up a repo, they might have to set up the repo first. If the site is already set up on netlify then run netlify link for the user to input the credentials to link.Install via CLI
npx mdskills install PatrickJS/cursor-netlify-officialNetlify Official is a free, open-source AI agent skill. description: Guidelines and best practices for building Netlify projects & sites, including serverless functions, edge functions, functions, storage, and real-world examples
Install Netlify Official with a single command:
npx mdskills install PatrickJS/cursor-netlify-officialThis downloads the skill files into your project and your AI agent picks them up automatically.
Netlify Official works with Cursor. Skills use the open SKILL.md format which is compatible with any AI coding agent that reads markdown instructions.