With ZEIT Now, you can deploy Serverless Functions, which are pieces of code written with backend languages that take an HTTP request and provide a response.

You can use Serverless Functions to handle user authentication, form submission, database queries, custom slack commands, and more.

Creating Serverless Functions

To create a Serverless Function, create a file in an api directory from your project root with the appropriate language extension. For example, to create a TypeScript function, you can create a file called get-user.ts like below.

import { NowRequest, NowResponse } from '@now/node'

export default (req: NowRequest, res: NowResponse) => {
  res.json({ name: 'John', email: 'john@example.com' })
}

A TypeScript Serverless Function that returns a JSON response.

When a user visits /api/get-user, they will receive the JSON from above. Note that you don't have to explicitly set up any routing rules for this to work. By default, filesystem routing is leveraged.

Deploying Serverless Functions

To deploy Serverless Functions without any additional configuration, you can put files with extensions matching supported languages and exported functions in the api directory at your project's root.

Note: If you are using Next.js, use the /pages/api directory instead.
Read more about API functionality with Next.js.

Then, using Now CLI, run the following command to deploy from your terminal:

now

Deploying a project with Now CLI in one command.

An Example Node.js Serverless Function

To deploy a serverless Node.js API, provide a main export function like the following, in a .js file within the api directory:

module.exports = (req, res) => {
  res.json({
    body: req.body,
    query: req.query,
    cookies: req.cookies
  })
}

An example Node.js Serverless Function using Express.js-like helper methods from the Request and Response objects.

The above example echoes the body, path query, and cookies, passed with the request object, as a JSON object using helper methods provided through the Request and Response.

Then, all you need to do, to have a live API, is deploy with Now CLI from your terminal:

now

One-command deployment with Now CLI.

The resulting deployment will contain your Node.js Serverless Function and will provide you with a URL like the following, with your API ready to go: https://node-echo-api.now-examples.now.sh/api/?name=zeit

More Examples and Supported Languages

For all supported languages, see the Supported Languages for Serverless Functions documentation.

More examples of applications you can deploy paired with Serverless Functions can be found in the ZEIT Now examples repository on GitHub.

You can use any of the Now examples by using the following command from Now CLI in your terminal, then choosing an application to start with:

now init

Initializing a project with Now CLI.

Prevent Endpoint Listing

By default, all files inside of the /api directory will be made available as Serverless Functions.

If this behavior is not desired, for example you want a utilities folder inside of the /api directory, you can prefix files or folders with either _ or . to prevent them from being created as Serverless Functions.

Therefore, if you keep your utility functions inside of /api/_utils, none of them will be created as Serverless Functions. This is because the parent folder is prefixed with _.

If you kept your utility functions inside of /api/utils, one called date.js and the other _time.js, only date.js would be created as a Serverless Function.

Path Segments

Deploying Serverless Functions with ZEIT Now gives you the ability to use path segments through file names instead of a complex routes file.

Creating a file using any of the supported languages in the api directory and wrapping the filename in square brackets, such as [name].js will provide you with a file that takes a path segment and gives it to the function when requested with a value.

For example, creating a name directory (within /api) with a [name].js file will allow you to receive the path segment entered when accessing /api/name/your-name.

The following Node.js example code could then use the path segment in its functionality when requested:

module.exports = (req, res) => {
  const {
    query: { name }
  } = req

  res.send(`Hello ${name}!`)
}

An example of a Node.js Serverless Function that takes a name path segment and returns a string using it.

The resulting deployment can be found here: https://path-segment-with-node.now-examples.now.sh/api/name/world

Note: Any supported language can utilize path segments.

Local Development

ZEIT Now provides an additional command with Now CLI to help you develop Serverless Functions locally by replicating the production environment on Now with your localhost.

If you have an api directory like the above examples on this page, you can run the following command to start a local development environment that supports your serverless API and allows you to develop locally, just make sure to install your project's dependencies first with npm install:

now dev

Starting a local development environment using Now CLI, for Serverless Functions.

Note: The now dev command is still in beta. If you have any feedback, please let us know.

If you have a statically generated frontend that supports its own development environment, such as Next.js, we recommend creating a dev script within a package.json file at the root of your project that now dev can use and extend:

{
  ...
  "scripts": {
    "dev": "next --port $PORT"
  }
}

Defining a custom dev script for Next.js in a package.json file.

Note: The above script example uses --port $PORT in the dev command. This uses the framework's – in this case Next.js – port argument to pass the port from now dev so that it can properly fetch the running framework.

Using Environment Variables Locally

During local development with now dev, you may wish to provide your application with environment variables. You can find instructions on how to do this in the environment variables and secrets section.

Advanced Usage

For an advanced configuration and structure, you can create a now.json file to use Runtimes and other customizations.

We do, however, recommend using the api directory to keep things simple for your project.

Related

For more information on what to do next, we recommend the following articles: