netlify-functions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Netlify Functions

Reach for the modern default-handler API (`.mts` TypeScript). Export a default async handler taking a web `Request` and a Netlify `Context`, returning a web `Response`. Avoid the legacy AWS Lambda handler shape unless writing Go or migrating old code (see Legacy at the end).

## File locations

- Default directory: `netlify/functions/` (relative to base directory). Keep it **outside** your publish directory or source files ship as static assets.
- A function is one file or a subdirectory whose entry file is named `index` or matches the subdirectory name. All of these create a function `hello`:
  - `netlify/functions/hello.mts`
  - `netlify/functions/hello/hello.mts`
  - `netlify/functions/hello/index.mts`
- Use `.mts` (TS) / `.mjs` (JS) for ES modules. `.cts`/`.cjs` force CommonJS; `.ts`/`.js` follow the nearest `package.json` `"type"`.

⚠️ **Same-name JS and TS files: the JS one wins.** If the functions directory has e.g. `items.js` and `items.ts`, the JavaScript function is deployed and the TypeScript file is silently ignored — edits to the `.ts` have no effect. Keep one file per function name; delete or rename the stale `.js` when moving a function to TypeScript.

## Minimal function

No `config` export. Serves at `/.netlify/functions/hello`.

```ts title="netlify/functions/hello.mts"
import type { Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  return new Response("Hello, world!")
}
```

Install types: `npm install @netlify/functions` (required for TS types; optional for JS).

Read env vars and secrets with `Netlify.env.get()`:

```ts
const apiKey = Netlify.env.get("STRIPE_SECRET_KEY")
```

Never hardcode secrets. For the variable to exist at runtime its scope must include **Functions**. Variables set in `netlify.toml` are NOT available to functions. Values are frozen per deploy — change them and redeploy to apply.

**Response headers are set in code** on the returned `Response`. `[[headers]]` in `netlify.toml`, `_headers`, and redirect header rules apply ONLY to static CDN responses, not function responses. Do not add CORS headers unless explicitly requested.

## Custom path routing

Set `config.path` to route to custom URLs. When set, the function serves ONLY at that path — not at `/.netlify/functions/<name>`.

```ts title="netlify/functions/travel.mts"
import type { Config, Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  const { city, country } = context.params
  return new Response(`You're visiting ${city} in ${country}!`)
}

export const config: Config = {
  path: "/travel-guide/:city/:country",
}
```

- Multiple paths: `path: ["/cats", "/dogs"]`.
- Patterns: `path` supports [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API) syntax — `path: ["/sale/*", "/item/:sku"]`. Named groups land on `context.params`. For the query string use `req.url`.
- `excludedPath`: carve exceptions, e.g. `excludedPath: ["/product/*.css"]` with `path: "/product/*"`.
- `preferStatic: true`: let a real static file at the URL win.
- `method`: restrict methods, e.g. `method: ["GET", "POST"]`.

## Fetchable module shape (alternative)

Equivalent to the bare handler; carries `config` inline and lets you add event handlers.

```ts
import type { NetlifyFunction } from "@netlify/functions"

export default {
  fetch: (req, context) => new Response("Hello, world!"),
  config: { path: "/hello" },
} satisfies NetlifyFunction
```

## Context object

Second handler argument (or `getContext()` from `@netlify/functions` when out of handler scope — throws outside a request; wrap in try/catch).

- `context.params` — named path params.
- `context.geo` — `city`, `country.code/name`, `latitude`, `longitude`, `subdivision`, `timezone`, `postalCode`.
- `context.ip` — client IP string.
- `context.cookies` — `get(name)` / `set(options)` / `delete(name|options)`. Cross-subdomain cookies need a custom domain (`netlify.app` is on the Public Suffix List).
- `context.site` — `id`, `name`, `url`. `context.deploy` — `context`, `id`, `published`, `skewProtectionToken`. `context.account.id`. `context.server.region`. `context.requestId`.
- `context.user` — the Netlify user who logged in to a **private** or **team-login-protected** project: `id`, `email` (may be `undefined`), `expiresAt` (`Date`). See below.
- `context.waitUntil(promise)` — run work after the response is sent (analytics, logs) without blocking. Billing/log duration counts until the promise settles. Available for functions deployed on/after 2025-03-20.

⚠️ `context.geo`/`context.ip` are **mocked** under `netlify dev` — test with `netlify dev --geo=mock --country=DE`.

### Who is calling: `context.user`

⚠️ `context.user` is often `undefined`: public projects, basic password protection, local `netlify dev`, and functions deployed before October 5, 2026 (redeploy to enable). Always handle it; key records on `id` (`email` may be `undefined`).

```ts title="netlify/functions/whoami.mts"
import type { Config, Context } from "@netlify/functions"

export default async (req: Request, context: Context) => {
  if (!context.user) {
    // Public project, basic password protection, local CLI, or pre-2026-10-05 deploy.
    return Response.json({ user: null }, { status: 401 })
  }
  return Response.json({
    id: context.user.id,
    email: context.user.email ?? null,
    expiresAt: context.user.expiresAt.toISOString(),
  })
}

export const config: Config = { path: "/whoami" }
```

## Config object

Export `const config` (or the `config` property of a Fetchable module):

- `path` / `excludedPath` — `string | string[]`, must start with `/`.
- `method` — one method or array.
- `preferStatic` — `boolean`.
- `background` — `boolean` (see Background).

From netlify/context-and-tools, MIT.

More from netlify/context-and-tools