How to Set Up Netlify Functions on Netlify

Install the Netlify CLI globally on your machine using npm install -g netlify-cli. Create a new project directory and navigate into it with mkdir my-netlify-functions && cd my-netlify-functions. Initialize npm in your project root with npm init -y to create a package.json file with default values. This sets up the foundation for your serverless functions project.

Create the default functions directory at the project root using mkdir netlify/functions. Netlify automatically detects this directory during builds without requiring additional configuration. If you prefer a custom directory name (e.g., functions instead of netlify/functions), you'll need to configure it in netlify.toml later. The directory structure should look like:

my-netlify-functions/
├── netlify/
│   └── functions/
├── package.json
└── netlify.toml

Create a new file in the functions directory named hello.mjs (use .mjs for ES modules, which is the required syntax). Add the following handler code:

export default async (request, context) => {
  return new Response(`Hello, ${context?.identity?.context?.user?.email ?? 'world'}!`, {
    headers: { 'Content-Type': 'text/plain' }
  });
};

The handler function receives two arguments: request (a web platform Request object containing HTTP details) and context (Netlify metadata including user identity). Your function must export a default handler and return a Response object.

Create a netlify.toml file in your project root to customize your build and function settings. Add the following configuration:

[build]
  functions = "netlify/functions"
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/api/*"
  to = "/.netlify/functions/:splat"
  status = 200

The [build] section specifies your functions directory (change to functions if using a custom path), build command, and publish directory. The [[redirects]] section (optional) routes API requests to your functions. If using the default netlify/functions directory, this file is optional but recommended for clarity.

Run netlify dev (or ntl dev for short) in your project root to start the local development server. This command automatically detects your netlify.toml and package.json configuration. The server will start on http://localhost:8888 by default. Your functions will be accessible at http://localhost:8888/.netlify/functions/hello. Open this URL in your browser to test your function—it should return "Hello, world!" or your email if you're logged in.

Create a .env file in your project root to store sensitive configuration values like API keys. Add your variables in the format KEY=value, for example:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_secret

These variables are automatically loaded into process.env when you run netlify dev. Access them in your functions using process.env.SPOTIFY_CLIENT_ID. Add .env to your .gitignore file to prevent committing secrets to version control.

Log in to your Netlify dashboard at app.netlify.com and click "Add new site" > "Import an existing project". Select your Git provider (GitHub, GitLab, or Bitbucket) and authorize Netlify to access your repositories. Choose the repository containing your functions project. Netlify will automatically detect your netlify.toml configuration and build settings. Review the build command and publish directory, then click "Deploy site". Netlify will now automatically build and deploy your site whenever you push changes to your repository.

After connecting your Git repository, Netlify automatically builds and deploys your functions with every push to your main branch. Monitor the deployment progress in the Netlify dashboard under "Deploys". Once deployment completes, your functions are live at https://your-site-name.netlify.app/.netlify/functions/hello. Test your production function by visiting this URL in your browser or using curl:

curl https://your-site-name.netlify.app/.netlify/functions/hello

Check the deploy logs in the dashboard if your function doesn't work as expected.

Add more functions by creating additional files in your netlify/functions directory. Each file becomes a separate endpoint. For example, create netlify/functions/users.mjs to handle user data at /.netlify/functions/users. You can handle different HTTP methods (GET, POST, PUT, DELETE) within a single function by checking request.method:

export default async (request, context) => {
  if (request.method === 'GET') {
    return new Response('Get users');
  } else if (request.method === 'POST') {
    return new Response('Create user');
  }
};

Use the optional netlify.toml redirects to create cleaner API routes (e.g., /api/users instead of /.netlify/functions/users).

Netlify Functions can access files within their own folder or subdirectories. If you need to use a JSON data file, place it in your functions directory or a subdirectory. For example, store db.json in netlify/functions/data/db.json and import it in your function:

import db from './data/db.json' assert { type: 'json' };

export default async (request, context) => {
  return new Response(JSON.stringify(db), {
    headers: { 'Content-Type': 'application/json' }
  });
};

Functions cannot access files outside their folder (e.g., ../src/data.json will fail during deployment). For external APIs, use fetch within your function to call third-party services like Spotify or Firebase.