netlify-functions

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".

Minimal function

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

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():

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>.

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",
}