When you trigger a deploy, ZEIT Now builds your project. For many frontend frameworks, ZEIT Now automatically configures the build settings, but you can also customize them. You can also use environment variables to avoid hardcoding values.

Customizing Build Settings

To customize the build settings for your project, choose a project from the dashboard:

Selecting the project from the ZEIT Dashboard.

Then, select the Settings tab:

Selecting the Settings tab from the Project Overview page.

You can then edit the build settings from the Build & Development Settings and Root Directory sections.

Build & Development Settings

ZEIT Now tries to automatically detect the frontend framework you’re using for your project and configure the project settings for you. If you’d like to override the settings or specify a different framework, you can do so from the Build & Development Settings section.

Framework Preset

The Framework Preset setting.

ZEIT Now detects the following frontend frameworks automatically and chooses the best default settings for you.

If no framework is detected, "Other" will be selected for you.

You can always choose a different framework preset or "Other" if you’d like.

Build Command

The Build Command setting.

If ZEIT Now detects a framework, the Build Command will automatically be configured. Depending on a framework, the Build Command can refer to the project’s configuration file.

For example, if you choose Next.js, here’s what happens by default:

  • If package.json contains the build command in scripts, this command will be used to build the project.
  • If not, next build will be the Build Command.

If you’d like to override the Build Command, you can turn on the Override toggle and specify the command.

Note: If you update this setting, it will be applied starting with your next deployment.

If build is not required: Some projects do not require building. An example of this would be a website with basic HTML/CSS/JS/assets that can be deployed directly without building (For example, you might just have a single index.html file).

In such cases, you should:

  • Specify "Other" as the framework preset, and
  • Override the Build Command and leave it empty. This will make ZEIT Now to skip the build step.

Output Directory

The Output Directory setting.

After building a project, most frameworks will output the result in a directory. Contents in this output directory will be the only things that will be statically served by ZEIT Now.

If ZEIT Now detects a framework, the output directory will automatically be configured.

Note: If you update this setting, it will be applied starting with your next deployment.

In some cases, your project might not require building, and you might just want to serve the files in the root directory. If so, try the following:

  • Choose "Other" as the framework preset. If you do so, by default, the output directory will be set as public if it exists, or . (current directory) otherwise.
  • Therefore, as long as your project doesn’t have the public directory, it will serve the files in the root directory.
  • Alternatively, you can turn on the Override toggle and leave the field empty (in which case, the build step will be skipped).

Development Command

The Development Command setting.

Note: This setting is relevant only if you’re using now dev locally to develop your project. You should be using now dev only if you need to use a ZEIT Now platform feature like Serverless Functions. In other cases, you should use the development command your framework provides (such as next dev for Next.js).

The Development Command setting allows you to customize the behavior of now dev. If ZEIT Now detects a framework, the development command will automatically be configured.

If you’d like to use a custom command for now dev, you can turn on the Override toggle. Please note the following:

  • If you specify a custom command, your command must pass the $PORT variable (which contains the port number) to your framework. For example, for Next.js, you should use: next dev --port $PORT.
  • If the development command is not specified, now dev will fail. If you selected "Other" as the framework preset, the development command will be empty by default.
  • You must create a deployment and have your local project be linked to the project on ZEIT Now (using now). Otherwise, now dev won’t work correctly.

Root Directory

The Root Directory setting.

In some projects, the top-level directory of the repository may not be the root directory of the app you’d like to build. For example, your repository might have a frontend directory, which contains a stand-alone Next.js app.

In cases like this, you can specify the project root directory. If you do so, please note the following:

  • If you specify a root directory, then your app won’t be able to access files outside of that directory. You also cannot use .. to move up a level.
  • This setting also applies to Now CLI. Instead of running now <directory-name> to deploy, specify <directory-name> here so you can just run now.
Note: If you update this setting, it will be applied starting with your next deployment.

Using Environment Variables and Secrets

When building your project, it may be necessary to use environment variables.

Adding environment variables requires two steps, defining the environment variable, then making it available to your projects' build step.

Note: This section covers how to make environment variables available at Build Time, if you would like to make them available during Run Time, please see the Serverless Functions documentation.

Adding Secrets

To define an environment variable, you should use Now Secrets. By using Now Secrets, the data will be encrypted and stored securely, no longer directly accessible by anyone, and only exposed to deployments as environment variables.

Adding Now Secrets can be done with Now CLI, providing three options to work with them.

Note: When adding Now Secrets with Now CLI, the secret name is automatically lowercased before being stored.

To define a Now Secret, use the following command:

now secrets add <secret-name> <secret-value>

Defining a Now Secret using Now CLI.

To remove a Now Secret, use the following command:

now secrets rm <secret-name>

Removing a Now Secret using Now CLI.

To rename a Now Secret, use the following command:

now secrets rename <secret-name> <new-name>

Renaming a Now Secret using Now CLI.

Providing Environment Variables

To provide your project with environment variables during the Build Step, you should create a now.json file like the one below:

{
  "build": {
    "env": {
      "VARIABLE_NAME": "@secret-name"
    }
  }
}

An example now.json file that provides an application's build step with a defined environment variable.

When providing environment variables to your application, the value should always be prefixed with @, followed by the name of the Now Secret or environment variable name if using a .env.build file during local development.

To use the environment variable from inside the application you would need to reference it using the correct syntax for the language being used. For example, using Node.js, the syntax would be:

process.env.VARIABLE_NAME

Accessing a defined environment variable from within a Node.js application.

Now, whenever the process.env.VARIABLE_NAME key is used, it will provide the application's build step with the value declared by the referenced Now Secret.

During Local Development

When using now dev to develop your application locally if you require the use of Serverless Functions, Now Secrets are not available. This is a security measure, to prevent accidental use of production secrets during development.

To use environment variables during local development, create a .env.build file at the root of your project directory, for example:

VARIABLE_NAME=variable_value

An example .env.build file that provides the Build Step with a defined environment variable.

Warning: Usage of a .env.build file is only possible during local development and will not be made available when deploying for security reasons.

Updating Environment Variables

Environment variables are made available to the build step, meaning that they do not update in the application unless it is redeployed.

If you change the value of a Now Secret or environment variable and want your application to be aware of this, you should create a new deployment.

Reserved Variables

The ZEIT Now platform reserves the usage of some environment variable names by default. You can find a list of these names in the limits documentation.

Ignored Files and Folders

By default, ZEIT Now ignores certain files and folders for security and performance reasons, preventing them from being uploaded during the deployment process.

.hg
.git
.gitmodules
.svn
.cache
.next
.now
.npmignore
.dockerignore
.gitignore
.*.swp
.DS_Store
.wafpicke-*
.lock-wscript
.env
.env.*
.venv
npm-debug.log
config.gypi
node_modules
__pycache__/
venv/
CVS

A complete list of files and folders ignored by ZEIT Now during the deployment process.

Note: You do not need to add any of the above files and folders to your .nowignore file.

Technical Details

Maximum Build Duration

A build can last for a maximum of 30 minutes. If the build exceeds this time, the deployment will error.

Caching

Each build step will cache files used to build the project, or files used in subsequent deployments, such as node_modules, yarn.lock, package-lock.json, which are cached by default.

The caching mechanism for builds ensures that the next deployment will happen quicker by skipping downloading files that have already been used in a previous deployment.

The maximum stored cache for builds is 3GB.

If a deployment fails, a cache may still be established for successfully built files, but failed builds will not be cached.

Private npm Modules for Static Builds

To install private npm modules, define NPM_TOKEN as a build environment variable in a now.json file.

Alternatively, define NPM_RC as a build environment variable with the contents of ~/.npmrc.

Prevent Installing Development Dependencies

In some rare cases, you may wish to skip installing devDependencies defined in your package.json file and only install dependencies.

This can be achieved by assigning NPM_ONLY_PRODUCTION=1 as a build environment variable.

This is equivalent to npm install --only=production or yarn install --production.

Prevent Cache Usage

If you need to ignore the cache for a deployment, you can do so by using the -f flag for Now CLI. This prevents the cache from being used in the deployment and ensures a fresh install for all dependencies.

Framework Versioning

Some frameworks do not use package.json to select a specific version to install during build time.

By including a build.env configuration property in a now.json file at your project's root, you can define your framework's version with one of the following keys:

Framework
Build Env Key
Hugo
HUGO_VERSION
Zola
ZOLA_VERSION

For example, defining the Hugo version in a now.json file would look like the following snippet:

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.61.0"
    }
  }
}

An example of defining a version for Hugo with a now.json configuration.

Note: The value must match an existing GitHub Release with an attached asset. For example, Hugo 0.42.0 does not exist but Hugo 0.42 does exist.

Related

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