Configuration

The nept.json file is the source of truth for your project's configuration. It must be located in the root of your project.

Schema

{
  "name": "string",
  "version": 2,
  "public": boolean,
  "cleanUrls": boolean,
  "trailingSlash": boolean,
  "rewrites": [ ... ],
  "redirects": [ ... ],
  "headers": [ ... ],
  "build": { ... },
  "images": { ... }
}

Top-Level Options

name (Required)

Type: string Limit: 100 characters

The unique name of your project. This determines your default subdomain (e.g., name.nept.cloud).

cleanUrls

Type: boolean Default: true

When enabled, .html extensions are automatically removed from URLs.

• /about.html -> /about

trailingSlash

Type: boolean Default: false

• false: Redirects paths with trailing slashes to their non-trailing counterpart (/about/ -> /about).
• true: Redirects paths without trailing slashes to the trailing version (/about -> /about/).

Build Options

The build object controls how your application is compiled.

"build": {
  "cmd": "npm run build",
  "env": {
    "NODE_VERSION": "18.x"
  },
  "ignore": "git diff --quiet HEAD^ HEAD ./",
  "timeout": 300
}

• cmd: The command to build your project.
• env: Build-time environment variables.
• ignore: A command that, if it returns a 0 exit code, cancels the build (useful for monorepos).
• timeout: Build timeout in seconds (default: 300).

Routing

rewrites

Rewrites allow you to map an incoming request path to a different destination path without changing the URL in the user's browser.

"rewrites": [
  { "source": "/old-path", "destination": "/new-path" },
  { "source": "/api/:path*", "destination": "https://external-api.com/:path*" }
]

redirects

Redirects allow you to forward an incoming request to a different destination path with a status code (usually 301 or 307).

"redirects": [
  { "source": "/blog/post-1", "destination": "/blog/new-post", "permanent": true }
]

Images

Nept has a built-in Image Optimization API. Configuration allows you to restrict which domains can be optimized.

"images": {
  "domains": ["example.com", "assets.other.com"],
  "sizes": [640, 750, 828, 1080, 1200],
  "formats": ["image/avif", "image/webp"]
}

Headers

Custom HTTP headers to apply to responses.

"headers": [
  {
    "source": "/(.*)",
    "headers": [
      { "key": "X-Frame-Options", "value": "DENY" },
      { "key": "X-Content-Type-Options", "value": "nosniff" }
    ]
  }
]