Creating and Deploying a Netlify Function with Node.js

Quick answer: add a handler file and push

To get a working Netlify Function, create a JavaScript file under netlify/functions/ that exports a handler, commit it, and push. Netlify automatically bundles the code and makes it available at /.netlify/functions/ on each deploy.

Worked example

Assume you have a Netlify‑linked site and the Netlify CLI installed.

1. Create the functions folder (if it doesn’t exist):

   # run in the root of your repo
   mkdir -p netlify/functions

   Permission needed: write access to the repository.
2. Add a simple handler (netlify/functions/hello.js):

   // netlify/functions/hello.js
   exports.handler = async (event, context) => {
     return {
       statusCode: 200,
       body: JSON.stringify({ message: 'Hello from Netlify Functions' })
     };
   };

   Key point: the exported handler receives event, context, and (if using callbacks) a callback argument.
3. Commit and push:

   git add netlify/functions/hello.js
   git commit -m "Add hello function"
   git push origin main

   Risk: pushing large node_modules can exceed the 250 MB function bundle limit and cause a deploy failure.
4. Verify locally before pushing (optional but recommended):

   # run in the repo root
   netlify dev
   # then open http://localhost:8888/.netlify/functions/hello

   You should see the JSON response. If the command fails, ensure you have linked the site with netlify link and that the CLI version is ≥ 2.0.
5. After push, check the live endpoint:

   curl https://YOUR_SITE.netlify.app/.netlify/functions/hello
   # Expected output: {"message":"Hello from Netlify Functions"}

   Replace YOUR_SITE with your actual subdomain or custom domain.

Limits and common mistakes

• Execution time: 10 seconds for regular functions (26 seconds for background functions). Long‑running loops or synchronous blocking code will cause a timeout.
• Payload size: request and response bodies are limited to 1 MB each. Sending larger data will be truncated or rejected with a 413 error.
• Concurrency: free tier allows up to 100 simultaneous invocations; higher tiers increase this limit. Exceeding concurrency results in 429 responses.
• Bundle size: the zipped function (including dependencies) must stay under 250 MB. Large native modules that aren’t compatible with the Amazon Linux execution image will fail at runtime.
• Environment variables: variables set in the Netlify UI are only available during deployed builds. To test them locally, run netlify dev after defining them in the UI or a .env file (the CLI automatically picks them up).
• Forgotten export: if the file does not export a handler property, Netlify logs “Function hello.js missing handler” and returns a 502 error.

By following the steps above and checking the limits, you can reliably add serverless endpoints to a Netlify site without managing infrastructure.