.cursorrules (deprecated)

1---
2description: Guidelines and best practices for building Netlify projects & sites, including serverless functions, edge functions, functions, storage, and real-world examples
3globs: **/*.{ts,tsx,js,jsx,toml}
4---
5 
6<ProviderContextOverrides>
7	// Developers can override the content as needed, but it should all be placed in this section.
8 
9 
10</ProviderContextOverrides>
11 
12ANY RULES IN THE ProviderContextOverrides SECTION CAN OVERRULE SPECIFIC RULES IN ProviderContext
13 
14<ProviderContext version="1.0" provider="netlify">
15  ## General
16 
17  - the `.netlify` folder is not for user code. It should be added to the .gitignore list
18  - avoid adding version numbers to imported code. (for example use `@netlify/functions` and never `@netlify/functions@VERSION`)
19  - *NEVER* add CORS headers (such as Access-Control-Allow-Origin) unless user EXPLICITLY asks for them.
20  - prefer using `netlify dev` to start dev server unless another dev command is requested by the user
21 
22  # Guidelines
23 
24  - There are 4 types of compute systems you can write code for:
25    - Serverless functions - usually used for transactional server/api requests.
26    - Edge functions - usually used for code that must modify requests before hitting the server or modifying responses before returning to users.
27    - Background functions - longer running functions for asynchronous work.
28    - Scheduled functions - schedule logic to run on a CRON-based interval.
29  - Netlify Blobs is a general object storage that can be used to accomplish state storage, data storage, etc.
30  - Netlify Image CDN enables on-demand image transformations without affecting build times or optimizing images upon upload. It optimizes images dynamically based on client capabilities and caches transformations for performance improvements. Use this when optimizing images dynamically. Don't use this when you need to modify an image during the development/build process.
31  - Environment variables are available for storing secrets, API keys, and other values that you want to control external to the code or are too sensitive to put in the code.
32 
33 
34  ## Netlify compute
35 
36  - NEVER put any type of serverless or edge function in the public or publish directory
37  - DO NOT change the default functions or edge functions directory unless explicitly asked to.
38  - ALWAYS verify the correct directory to place functions or edge functions into
39 
40  ### Context object for serverless functions and edge functions
41 
42  Below are the available fields/functions from the context argument to serverless and edge functions.
43 
44```
45  {
46    account: {
47      id: string, // Unique ID of the Netlify team account associated with the site and function.
48    },
49    cookies: {
50      get: (name: string) => string | undefined, // Reads a cookie from the incoming request.
51      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.
52      delete: (nameOrOptions: string | { name: string; path?: string; domain?: string }) => void, // Deletes a cookie on the outgoing response, following the CookieStore.delete web standard.
53    },
54    deploy: {
55      context: string, // The deploy context (e.g., production, deploy-preview).
56      id: string, // Unique ID of the deploy the function belongs to.
57      published: boolean, // Indicates whether the function belongs to the currently published deploy.
58    },
59    geo: {
60      city: string, // City name of the client location.
61      country: {
62        code: string, // ISO 3166 country code.
63        name: string, // Full country name.
64      },
65      latitude: number, // Latitude coordinate of the client location.
66      longitude: number, // Longitude coordinate of the client location.
67      subdivision: {
68        code: string, // ISO 3166 subdivision code (e.g., state or province).
69        name: string, // Subdivision name.
70      },
71      timezone: string, // Timezone of the location.
72      postalCode: string, // Postal code of the location in its regional format.
73      ip: string, // Client IP address.
74    },
75    params: Record<string, string>, // Object containing route parameters from the function path configuration.
76    requestId: string, // Unique Netlify request ID.
77    server: {
78      region: string, // The region code where the deployment is running (e.g., us-east-1).
79    },
80    site: {
81      id: string, // Unique ID for the Netlify site.
82      name: string, // The site's Netlify subdomain name.
83      url: string, // The main address of the site, which could be a Netlify subdomain or a custom domain.
84    },
85  }
86```
87 
88  ### the `Netlify` global object
89 
90  - the `Netlify` object is available in global scope.
91  - available on all serverless and edge function types
92 
93  It has the following fields/functions:
94 
95```
96  {
97    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.
98 
99    env: {
100      delete: (name: string) => void, // Deletes an environment variable within the context of the invocation.
101      get: (name: string) => string | undefined, // Retrieves the string value of an environment variable; returns undefined if not defined.
102      has: (name: string) => boolean, // Checks if an environment variable exists; returns true if it does, otherwise false.
103      set: (name: string, value: string) => void, // Sets an environment variable within the invocation context.
104      toObject: () => Record<string, string>, // Returns an object containing all environment variables and their values.
105    },
106  };
107```
108 
109  ### Serverless Functions (aka Functions, aka Synchronous functions)
110  - Serverless functions use Node.js and should attempt to use built-in methods where possible
111  - When adding new npm modules, ensure "node_modules" is in the .gitignore
112  - ALWAYS use the latest format of a function structure.
113  - if using typescript, ensure types are installed from `npm install @netlify/functions`
114  - DO NOT put global logic outside of the exported function unless it is wrapped in a function definition
115  - ONLY use vanilla javascript if there are other ".js" files in the functions directory.
116  - ALWAYS use typescript if other functions are typescript or if there are no existing functions.
117  - The first argument is a web platform Request object that represents the incoming HTTP request
118  - The second argument is a custom Netlify context object.
119  - Functions have a global `Netlify` object that is also accessible.
120    - ONLY use `Netlify.env.*` for interacting with environment variables in code.
121  - Place function files in `YOUR_BASE_DIRECTORY/netlify/functions` or a subdirectory.
122    - The serverless functions directory can be changed via:
123      - **Netlify UI**: *Site configuration > Build & deploy > Continuous deployment > Build settings*
124      - **`netlify.toml`**:
125```toml
126        [functions]
127          directory = "my_functions"
128```
129    - `netlify.toml` settings override UI settings.
130  - If using a subdirectory, name the entry file `index.mts` or match the subdirectory name.
131    - Example valid function paths:
132      - `netlify/functions/hello.mts`
133      - `netlify/functions/hello/index.mts`
134      - `netlify/functions/hello/hello.mts`
135  - Naming files with `.mts` enables modern ES module syntax
136 
137  #### Examples of the latest Serverless Function or Function structures
138    - ```typescript
139        import type { Context, Config } from "@netlify/functions";
140 
141        export default async (req: Request, context: Context) => {
142          // user code
143          return new Response("Hello, world!")
144        }
145 
146        export const config: Config = {
147          // use this path instead of /.netlify/functions/{fnName}
148          path: "/hello-world"
149        };
150```
151    - ```javascript
152        export default async (req, context) => {
153          // user code
154          return new Response("Hello, world!")
155        }
156 
157        export const config = {
158        // use this path instead of /.netlify/functions/{fnName}
159          path: "/hello-world"
160        };
161```
162  #### In-code function config and routing for serverless functions
163  - prefer to use in-code configuration via exporting a `config` object. This is the structure the config can have:
164  - prefer to provide a friendly path using the config object.
165  - ONLY serverless functions use `/.netlify/functions/{function_name}` path by default.
166  - If you set a specific path via this config or the netlify.toml, it will only be available at that new path.
167  - path and excluded path supports substring patterns or the URLPattern syntax from the web platform.
168 
169```
170  {
171    path: string | string[], // Defines the URL path(s) that trigger the function. Can be a single string or an array of paths.
172    excludedPath?: string | string[], // Optional. Defines paths that should be excluded from triggering the function.
173    preferStatic?: boolean, // Optional. If true, prevents the function from overriding existing static assets on the CDN.
174  }
175```
176 
177  ### Background Functions
178  - Use background functions when you need to run long-running logic, and that logic does not need to compute a response immediately.
179  - Any data that background functions need to serve to users should be calculated and stored in a place that a serverless function can read from later - such as Netlify Blobs or a preconfigured database.
180  - Background functions operate the same as standard Serverless functions and are syntactically the same with the following exceptions
181    - they have a 15-minute timeout measured by "wall clock" time
182    - they immediately return an empty response with a 202 status code. Return values from these functions are ignored.
183    - Background functions MUST have a "-background" suffix on the function file name or function directory (for example, netlify/functions/hello-background.mts or netlify/functions/hello-background/index.mts).
184 
185  #### Examples of the latest background function structures
186  - ```typescript
187      import { Context } from "@netlify/functions";
188 
189      export default async (req: Request, context: Context) => {
190        await someLongRunningTask();
191 
192        console.log("Done");
193      };
194```
195 
196  - ```javascript
197      export default async (req, context) => {
198        await someLongRunningTask();
199 
200        console.log("Done");
201      };
202```
203 
204  ### Scheduled Functions
205  - Use scheduled functions when the logic needs to run on an interval or can be defined via CRON timing.
206  - CRON expressions are executed against the UTC timezone
207  - our CRON syntax supports extensions defined the RFC except for the @reboot and @annually.
208  - The minimum interval is 1 minute
209  - Scheduled functions have a 30-second execution limit
210  - Scheduled functions do not return response bodies
211  - the request body is a JSON-encoded object containing a `next_run` property. It represents the timestamp of the next scheduled invocation, as a string in the ISO-8601 format.
212  - in addition to in-code config, schedules can be defined in the `netlify.toml`. ONLY do this for consistency or if explicitly asked to keep all schedules in one place.
213```toml
214      [functions."test-scheduled-function"]
215        schedule = "@hourly"
216```
217  - Scheduled functions ONLY run on published deploys. They don’t run on Deploy Previews or branch deploys.
218  - For local tests, the Netlify CLI to run the site in dev mode and the `netlify functions:invoke` [command](mdc:https:/cli.netlify.com/commands/functions/#functionsinvoke) to trigger the scheduled function.
219    example:
220```bash
221      netlify functions:invoke myfunction
222```
223 
224  #### Examples of the latest background function structures
225  - ```typescript
226      import type { Config } from "@netlify/functions"
227 
228      export default async (req: Request) => {
229          const { next_run } = await req.json()
230 
231          console.log("Received event! Next invocation at:", next_run)
232      }
233 
234      export const config: Config = {
235          schedule: "@hourly"
236      }
237 
238```
239 
240  - ```javascript
241      export default async (req) => {
242          const { next_run } = await req.json()
243 
244          console.log("Received event! Next invocation at:", next_run)
245      }
246 
247      export const config = {
248          schedule: "@hourly"
249      }
250 
251```
252 
253 
254 
255  ### Edge Functions
256  - ALWAYS use the latest format of an edge function structure.
257  - **DO NOT** add CORS headers (such as Access-Control-Allow-Origin) unless explicitly asked for them.
258  - if using typescript, ensure types are installed from `npm install @netlify/edge-functions`
259  - DO NOT put global logic outside of the exported function unless it is wrapped in a function definition
260  - ONLY use vanilla javascript if there are other ".js" files in the functions directory.
261  - ALWAYS use typescript if other functions are typescript or if there are no existing functions.
262  - The first argument is a web platform Request object that represents the incoming HTTP request
263  - The second argument is a custom Netlify context object.
264  - Edge functions have a global `Netlify` object that is also accessible.
265    - ONLY use `Netlify.env.*` for interacting with environment variables in code.
266  - Place function files in `YOUR_BASE_DIRECTORY/netlify/edge-functions` or a subdirectory.
267    - The serverless functions director can be changed via`netlify.toml`:
268```toml
269      [build]
270        edge_functions = "my-custom-directory"
271```
272 
273  - 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.
274    - **Module Support**:
275      - Supports **Node.js built-in modules**, **Deno modules**, and **npm packages** (beta).
276    - **Importing Modules**:
277      - **Node.js built-in modules**: Use `node:` prefix (e.g., `import { randomBytes } from "node:crypto"`).
278      - **Deno modules**: Use **URL imports** (e.g., `import React from "https://esm.sh/react"` or an **import map**).
279      - **npm packages (beta)**: Install via `npm install` and import by package name (e.g., `import _ from "lodash"`).
280      - Some npm packages with **native binaries** (e.g., Prisma) or **dynamic imports** (e.g., cowsay) may not work.
281    - You may use an **import map** to reference third-party modules with shorthand names instead of full URLs.
282    - **Import Map Usage**:
283      - Define mappings in a separate **import map file** (not in `deno.json`).
284      - The file can be placed anywhere in the project directory.
285    - **Example Import Map (`import_map.json`)**:
286```json
287      {
288        "imports": {
289          "html-rewriter": "https://ghuc.cc/worker-tools/html-rewriter/index.ts"
290        }
291      }
292```
293    - **Enabling Import Maps**:
294      - Declare the import map in `netlify.toml`:
295```toml
296        [functions]
297          deno_import_map = "./path/to/your/import_map.json"
298```
299    - **Usage in Code**:
300      - Modules can now be imported by name:
301```javascript
302        import { HTMLRewriter } from "html-rewriter";
303```
304  #### Examples of the latest Edge function structures
305    - ```typescript
306        import type { Context, Config } from "@netlify/edge-functions";
307 
308        export default async (req: Request, context: Context) => {
309          // user code
310          return new Response("Hello, world!")
311        }
312 
313        export const config: Config = {
314          path: "/hello-world"
315        };
316```
317    - ```javascript
318          export default async (req, context) => {
319            // user code
320            return new Response("Hello, world!")
321          }
322 
323          export const config = {
324            path: "/hello-world"
325          };
326```
327 
328  #### Extra properties on context argument for Edge Functions
329  - these are ONLY available in Edge Functions
330 
331```
332  {
333    ...ALL OTHER Context fields/methods,
334 
335    next: (options?: { sendConditionalRequest?: boolean }) => Promise<Response>, // Invokes the next item in the request chain, optionally using conditional requests.
336 
337    nextRequest: (request: Request, options?: { sendConditionalRequest?: boolean }) => Promise<Response>, // Same as next(), but requires an explicit Request object.
338  }
339 
340```
341 
342  #### Web APIs available in Edge Functions ONLY
343  - console.*
344  - atob
345  - btoa
346  - Fetch API
347    - fetch
348    - Request
349    - Response
350    - URL
351    - File
352    - Blob
353  - TextEncoder
354  - TextDecoder
355  - TextEncoderStream
356  - TextDecoderStream
357  - Performance
358  - Web Crypto API
359    - randomUUID()
360    - getRandomValues()
361    - SubtleCrypto
362  - WebSocket API
363  - Timers
364    - setTimeout
365    - clearTimeout
366    - setInterval
367  - Streams API
368    - ReadableStream
369    - WritableStream
370    - TransformStream
371  - URLPattern API
372 
373 
374  #### In-code function config and routing for Edge functions
375  - prefer to use in-code configuration via exporting a `config` object. This is the structure the config can have:
376  - prefer to provide a friendly path using the config object.
377  - Edge functions are configured with a path pattern and only paths matching those patterns will run the edge function
378  - path and excludedPath supports substring patterns or the URLPattern syntax from the web platform.
379  - unless explicitly asked to modify other properties, only set path, pattern, excludedPath when creating functions.
380 
381```
382  {
383    path?: string | string[], // URLPattern expression defining paths where the edge function should run. Must start with '/'.
384    excludedPath?: string | string[], // Optional. Defines paths to exclude from execution. Must start with '/'.
385    pattern?: RegExp | RegExp[], // Alternative to `path`. Uses regex for path matching.
386    excludedPattern?: RegExp | RegExp[], // Optional. Defines regex patterns to exclude certain routes.
387    method?: string | string[], // Optional. Specifies HTTP methods that should trigger the function (e.g., "GET", ["POST", "PUT"]).
388    onError?: "continue" | "fail" | "fallback", // Optional. Controls how the function handles errors.
389    cache?: 'manual', // Optional. Enables response caching if set to 'manual'.
390  } = {
391    path: "", // Default value; should be set per function.
392  };
393```
394 
395  #### Configuring Edge Functions in netlify.toml
396  - ONLY Use `netlify.toml` for precise function order control instead of inline declarations.
397  - DO NOT use `netlify.toml` if there is not edge function ordering requirements.
398  - When controlling order, it's important to include all edge functions for order control.
399 
400  - **Declare Edge Functions in `netlify.toml`**:
401    - Allows multiple edge functions on the same path with explicit execution order.
402    - Functions run **top-to-bottom**, except cached functions, which always run last.
403 
404  - **Edge Function Properties**:
405    - `function`: Name of the edge function.
406    - `path`: URL pattern to trigger the function (must start with `/`).
407    - `excludedPath`: Excludes specific routes from `path` (supports string or array).
408    - `pattern`: Regex-based path matching.
409    - `excludedPattern`: Excludes specific regex patterns (single or array).
410    - `cache`: Enables response caching (cached functions run after non-cached ones) set to 'manual' to opt in.
411 
412  - **Netlify.toml config examples**
413```toml
414    [[edge_functions]]
415      path = "/admin"
416      function = "auth"
417
418    [[edge_functions]]
419      path = "/admin"
420      function = "injector"
421      cache = "manual"
422
423    [[edge_functions]]
424      path = "/blog/*"
425      function = "auth"
426
427    [[edge_functions]]
428      path = "/blog/*"
429      function = "rewriter"
430
431    [[edge_functions]]
432      pattern = "/products/(.*)"
433      excludedPattern = "/products/things/(.*)"
434      function = "highlight"
435
436    [[edge_functions]]
437      path = "/*"
438      excludedPath = "/img/*"
439      function = "common"
440```
441  - **Execution Order for Edge Functions**:
442    1. **Configuration-based** edge functions (`netlify.toml`) run first.
443    2. **Framework-generated** edge functions execute before user-defined functions.
444    3. **Non-cached** edge functions execute before cached functions.
445    4. **Inline-declared** edge functions override duplicate `netlify.toml` functions.
446    5. **Multiple inline edge functions** run alphabetically by filename.
447 
448  - **Caveats & Special Cases**:
449    - If an edge function returns a response, redirects for that path DO NOT occur.
450    - Edge functions DO NOT execute for rewritten static routing targets.
451    - `fetch()` or `URL()` triggers a **new request chain**, re-running matching functions.
452    - Use `context.next()` to continue processing instead of re-triggering functions.
453    - Function failure behavior depends on its **error handling configuration**.
454 
455  #### Edge functions limitations
456  - 20 MB (compressed) code size limit
457  - 512 MB per deployment memory limit
458  - 50ms per request CPU execution time (excludes waiting time)
459  - 40 seconds Response header timeout
460  - **Not compatible with these Netlify features**:
461    - Netlify's split testing feature
462    - Custom Headers (including basic authentication) from _headers or netlify.toml config
463    - Netlify prerendering feature on paths served by edge functions
464  - Be aware that multiple framework adapters may generate conflicting edge functions
465  - **Restrictions**:
466    - Can only rewrite requests to same-site URLs (use `fetch()` for external content)
467    - Cached edge functions override existing static files
468    - No local caching; HTTP cache headers are ignored in local testing
469    - Not included in Netlify’s HIPAA-compliant hosting offering
470 
471 
472  ## Netlify Blobs
473 
474  - 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
475  - 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.
476  - ensure `@netlify/blobs` NPM module is installed
477  - Requirements and limits
478    - Requires Fetch API support (Node.js 18+ recommended) - a fetch function can be provided to the store
479    - Store names cannot exceed 64 bytes
480    - Object keys cannot exceed 600 bytes
481    - Maximum object size: 5GB
482    - Local development uses a sandboxed store
483 
484 
485  ### Netlify Blobs API
486 
487```typescript
488    export interface BlobMetadata {
489      [key: string]: any;
490    }
491 
492    export interface BlobData<T = string> {
493      data: T | null;
494      etag: string;
495      metadata: BlobMetadata;
496    }
497 
498    export interface ListResult {
499      blobs: { etag: string; key: string }[];
500      directories?: string[];
501    }
502 
503    interface GetKeyOptions {
504      type?: 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text'
505    }
506 
507    interface GetKeyAndMetadataOptions {
508      type?: 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text',
509      etag?: string;
510    }
511 
512    // THESE ARE THE ONLY STORE METHODS. DO NOT MAKE UP NEW ONES
513    interface Store {
514 
515      // Creates or overwrites a blob entry.
516      // example: await store.set('key-name', 'contents-of key');
517      // - NEVER add metadata unless instructed to.
518      set(key: string, value: ArrayBuffer | Blob | string, { metadata?: object }): Promise<void>;
519 
520      // Stores a JSON-serializable object.
521      // example: await store.setJSON('key-name', {version: 'a', someBoolean: true});
522      // - NEVER add metadata unless instructed to.
523      setJSON(key: string, value: any, { metadata?: object }): Promise<void>;
524 
525      // Retrieves a stored blob.
526      // example: await store.get('key-name');
527      // - NEVER add the second arg unless you need an explicit type 'arrayBuffer' | 'blob' | 'json' | 'stream' | 'text'.
528      // - Instead of using JSON.parse(blob), use store.get('key-name', {type: 'json'})
529      // - if the blob is missing, it will resolve the promise with a null value
530      get(key: string, getOpt?: GetKeyOptions): Promise<any | null>;
531 
532      // Retrieves a blob along with metadata
533      // example: await store.getWithMetadata('key-name');
534      // - NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against.
535      // - 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.
536      // - if the blob is missing, it will resolve the promise with a null value
537      getWithMetadata(key: string, getOpts?: GetKeyAndMetadataOptions): Promise<{ data: any, etag: string, metadata: object } | null>;
538 
539      // Retrieves metadata of a blob WITHOUT downloading the data.
540      // example: await store.getMetadata('key-name');
541      // - NEVER add the second getOpts arg unless you need an explicit type or have an etag to check against.
542      // - 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.
543      // - if the blob is missing, it will resolve the promise with a null value
544      getMetadata(key: string, getOpts?: GetKeyAndMetadataOptions): Promise<{ etag: string, metadata: object } | null>;
545 
546      // Lists blobs in the store with optional hierarchical browsing.
547      // example:
548      //      const { blobs } = await store.list()
549      //      // blobs === [ { etag: 'etag1', key: 'some-key' }, { etag: 'etag2', key: 'another-key' } ]
550      //
551      // - NEVER add the options arg unless you need an explicit reduce the searched data.
552      //    -- 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`
553      // - 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.
554      // - if store path is empty, the blobs will resolve the promise with an empty array
555      list(options?: { directories?: boolean, paginate?: boolean. prefix?: string }): Promise<{ blobs: BlobResult[], directories: string[] }> | AsyncIterable<{ blobs: BlobResult[], directories: string[] }>
556 
557      // Deletes a blob.
558      // example: await store.delete('key-name');
559      // - The return value is always resolves to `undefined`, regardless of whether or not there was an object to delete.
560      delete(key: string): Promise<void>;
561    }
562 
563    interface GetDeployStoreOptions extends Partial<ClientOptions> {
564      deployID?: string;
565      name?: string;
566      region?: Region;
567    }
568 
569    // Returns a store instance for managing blobs. This is global scoped data across all deploys.
570    // example: const store = getStore('my-store');
571    // - ONLY add the options argument if the user needs strong consistency
572    export function getStore(name: string, options?: { consistency?: 'strong' | 'eventual' }): Store;
573 
574    // Returns a deploy-specific store instance for managing blobs tied to a deploy.
575    // example: const store = getDeployStore('my-store');
576    // - ONLY add the options argument if the user needs strong consistency
577    declare const getDeployStore: (input?: GetDeployStoreOptions | string) => Store;
578    interface GetStoreOptions extends Partial<ClientOptions> {
579        deployID?: string;
580        name?: string;
581    }
582 
583    // Lists all stores available on a site.
584    // example:
585    //    const { stores } = await listStores();
586    //      // [ "beauty", "construction" ]
587    // - 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.
588    // - DO NOT pass options unless paginating.
589    declare function listStores(options?: {
590        paginate?: boolean;
591    }): Promise<ListStoresResponse> | AsyncIterable<ListStoresResponse>;
592 
593    interface ListStoresResponse {
594        stores: string[];
595        next_cursor?: string;
596    }
597 
598```
599 
600  ## File-Based Uploads
601  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.
602 
603  Put files in `.netlify/blobs/deploy/*` for deploy specific
604```
605  .netlify/
606  ├─ blobs/
607  |  ├─ deploy/
608  │  |  ├─ beauty/
609  │  │  |  └─ nails.jpg
610```
611  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:
612```
613  ├─ blobs/
614  |  ├─ deploy/
615  │  |  ├─ beauty/
616  │  │  |  ├─ nails.jpg
617  │  │  |  └─ $nails.jpg.json
618```
619 
620  ## Blob consistency models
621  - By default, blobs are "eventually consistent" - Fast reads, updates/deletions propagated within 60 seconds.
622  - To have strong consistency that ensures updates are immediately visible at the cost of slower reads. set the `consistency` field to `'strong'` on the store instantiation.
623  - There is no concurrency control built in, last write wins. Add object-locking mechanisms if you need concurrency guarantees.
624 
625  Example:
626```javascript
627  const store = getStore({ name: "animals", consistency: "strong" });
628  await store.set("dog", "🐶");
629  const dog = await store.get("dog");
630```
631 
632  ## Storage scopes
633  - blobs can be stored in a deploy-specific scope or at a global scope
634  - deploy-specific blobs sync with deploys and are removed with deploy deletions. `getDeployStore()` is used to interact with deploy specific stores.
635  - global scope blobs are not automatically cleaned up and are consistent across all branches. `getStore()` is used for global scope.
636  - Build plugins and file-based uploads must write to deploy-specific stores.
637  - ALWAYS When creating logic that saves to global scope, ensure that non-production data does not get stored in these global stores. This keeps production data isolated from test data. To do that, check for the environment and choose which store to use depending on the environment.
638 
639  #### Examples of blob usage
640 
641```javascript
642    // basic writing to a deploy store
643    import { getDeployStore } from "@netlify/blobs";
644    const store = getDeployStore("construction");
645```
646 
647```javascript
648    // basic writing to a global store
649    import { getStore } from "@netlify/blobs";
650    const store = getStore("construction");
651```
652 
653```javascript
654    // using global store if in production, otherwise use deploy scope store
655    import { getStore, getDeployStore } from "@netlify/blobs";
656 
657    function getBlobStore(...storeOptions){
658 
659      if((Netlify.context?.deploy.context === 'production'){
660        return getStore(...storeOptions);
661      }
662 
663      return getDeployStore(...storeOptions)
664    }
665 
666    const store = getBlobStore("construction");
667```
668 
669  ---
670 
671  ## Netlify Image CDN
672  - All Netlify sites have a `/.netlify/images` route supported by their site without any additional enablement.
673  - Transform images via query parameters in requests to `/.netlify/images`.
674  - NEVER introduce circular dependencies with urls redirecting to urls that redirect back to the same url in a loop
675  - when using the ?url={URL} parameter, ensure the url is a URI encoded component.
676  - Supported transformations:
677    - **source**: Required, specifies image URL (relative or remote).
678    - **size**: `w` (width) and `h` (height) in pixels.
679    - **fit**: Determines how the image is resized (`contain`, `cover`, `fill`).
680    - **position**: Cropping alignment (`top`, `bottom`, `left`, `right`, `center`).
681    - **format**: Convert to `avif`, `jpg`, `png`, `webp`, `gif`, or `blurhash`.
682    - **quality**: Controls lossy format quality (`q`, 1-100, default 75).
683 
684  ### Example transformations
685```html
686    <!-- get an image hosted on this site and change its size and format -->
687    <img src="/.netlify/images?url=/image.jpg&w=100&h=100&fit=cover&fm=webp&q=80" />
688 
689    <!-- get an image hosted externally and change its size and format -->
690    <img src="/.netlify/images?url=https://example.com/path/to/image&w=40&h=10&fm=jpg&q=80" />
691```
692 
693  ### Caching & deployment behavior
694  - Transformed images are cached at the edge.
695  - Source images are cached for future transformations.
696  - After a new deploy cached images are invalidated and so images can be reprocessed in case of changes
697  - Cache-busting via asset fingerprinting is recommended if you must finely control cache key.
698  - In order to use externally hosted (aka remote) images the domain pattern must be allowlisted in the Netlify `netlify.toml`.
699    - Allow remote sources using:
700```toml
701      [images]
702        remote_images = ["https://externalexample.com/.*"]
703```
704      - only absolute urls to external servers need to be in remote_images
705 
706  ### Redirects & Rewrites
707  - If you do not want to use the default `/.netlify/images` path, a redirect or rewrite can be used to have a different url.
708  - Define reusable transformation routes in `_redirects` or `netlify.toml` files.
709  - When doing so, the parameters can remain parameters to pass in or can be statically defined.
710  - Examples:
711    - netlify.toml to use /transform-my-images/{imagePath}
712```toml
713        [[redirects]]
714          from = "/transform-my-images/*"
715          to = "/.netlify/images?url=/:splat&w=50&h=50"
716          status = 200
717```
718    - _redirects to use /transform-all/{...imagePath}
719```
720        /transform-all/* /.netlify/images?url=/:splat&w=50&h=50 200
721```
722 
723  ### Custom headers
724  - Custom headers can ONLY be applied to images hosted on the same domain.
725  - ONLY do this when explicitly asked
726  - Examples:
727    - netlify.toml to use /transform-my-images/{imagePath}
728```toml
729        [[headers]]
730          for = "/source-images/*"
731          [headers.values]
732            Cache-Control = "public, max-age=604800, must-revalidate"
733```
734    - _headers to use /{...imagePath}
735```
736        /source-images/* Cache-Control: public, max-age=604800, must-revalidate
737```
738  ### Image CDN framework support
739  Netlify Image CDN integrates with frameworks for automatic optimizations:
740  - **Angular**: `NgOptimizedImage` component will use Image CDN automatically
741  - **Astro**: `<Image />` component will use Image CDN automatically
742  - **Gatsby**: set `NETLIFY_IMAGE_CDN=true` and use the Contentful, Drupal, or WordPress source plugins.
743  - **Next.js**: set `remotePatterns` in `next.config.js`
744  - **Nuxt**: `nuxt/image` module will use Image CDN automatically
745 
746  ---
747 
748  ## Environment Variables
749  - securely create, manage, and use environment variables across sites. These variables can be set via the UI, CLI, API, or configuration files.
750  - when setting environment variables, Netlify local environment and cloud environment will make these variables available.
751  - **Precedence**: `netlify.toml` overrides UI/CLI/API variables, and site-specific variables take precedence over shared ones.
752 
753  ### Creating Environment Variables
754  Variables can be created and managed using:
755  - **Netlify UI**: Suggest using if they don't want to provide the values directly to this agent. They can navigate to it via the path "Site configuration > Environment variables".
756  - **Netlify CLI**: Prefer using this if the agent can run commands. This requires the site to be linked.
757  - **Netlify Configuration (`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.
758 
759  ### Netlify CLI Command
760  - The site must be linked first before the CLI will add variables. See the rules for initializing and linking sites for how to do this.
761  - Use `env:set` for changes, `env:unset` to delete. `env:import` to import from a dotenv`.env` file.
762 
763  #### Example usage of env var CLI
764  - Basic setting an environment variable for the site
765```sh
766      netlify env:set API_KEY &quot;not-a-secret&quot;
767```
768  - Setting an environment variable that should be treated as a secret
769```sh
770        netlify env:set API_KEY &quot;secret-value&quot; --secret
771```
772 
773  ### Example `netlify.toml` Configuration
774  - Using the netlify.toml the configuration can be specific to certain branches/deploy contexts.
775  - examples
776```toml
777      # Production context: all deploys from the Production branch
778      # set in your site’s Branches settings in the UI will inherit
779      # these settings. You can define environment variables
780      # here but we recommend using the Netlify UI for sensitive
781      # values to keep them out of your source repository.
782      [context.production]
783        publish = "output/"
784        command = "make publish"
785        environment = { NODE_VERSION = "14.15.3" }
786 
787      # Here is an example of how to define context-specific
788      # environment variables. Be mindful when using this
789      # option and avoid committing sensitive values to public
790      # source repositories.
791      [context.deploy-preview.environment]
792        NOT_PRIVATE_ITEM = "not so secret"
793 
794      # Branch Deploy context: all deploys that are not from
795      # a pull/merge request or from the Production branch
796      # will inherit these settings.
797      [context.branch-deploy.environment]
798        NODE_ENV = "development"
799 
800      # Dev context: environment variables set here
801      # are available for local development environments
802      # run using Netlify Dev. These values can be
803      # overwritten on branches that have a more specific
804      # branch context configured.
805      [context.dev.environment]
806        NODE_ENV = "development"
807 
808      # Specific branch context: all deploys from
809      # this specific branch will inherit these settings.
810      [context.staging.environment] # “staging” is a branch name
811        NODE_ENV = "development"
812```
813 
814  ### `.env` File Handling
815  - Netlify builds do not read `.env` files directly
816  - Import `.env` variables into Netlify using the UI or CLI (`netlify env:import .env`).
817  - Export Netlify variables to `.env` files via UI or CLI (`env:list`).
818 
819  ### Export `.env` Variables
820```sh
821  # list the production deploy context values in .env format
822  netlify env:list --plain --context production
823 
824  # list the production deploy context values in .env format
825  # and pipe results into a .env file
826  netlify env:list --plain --context production &gt; .env
827```
828 
829  ---
830 
831  # Creating new sites
832 
833  - do not add redirects to netlify.toml or _redirects unless requested
834  - do not add custom headers to the netlify.toml or _headers unless requested
835 
836  # Initializing sites or linking them
837  - determine if a site is linked by checking if `PROJECT_FOLDER/.netlify/state.json` file exists and it has a populated `siteId` value.
838  - if the site is not linked, run `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.
839 
840</ProviderContext>
841