ship.json

An optional ship.json file in the root of your project configures how the platform serves your deployment. Most sites work perfectly without one — add it only when you need redirects, rewrites, headers, or URL formatting.

Clean URLs

Remove .html extensions from URLs. When enabled, /about.html is served at /about. Visiting /about.html redirects to /about.

{
  "cleanUrls": true
}

Trailing Slash

Control trailing slash behavior for all URLs.

{
  "trailingSlash": false
}

Redirects

Send visitors from one URL to another. The browser URL changes.

{
  "redirects": [
    { "source": "/pricing", "destination": "/plans", "permanent": true },
    { "source": "/blog/:slug", "destination": "/posts/:slug", "permanent": true }
  ]
}

Pattern syntax

Named parameters match a single path segment:

{ "source": "/blog/:slug", "destination": "/posts/:slug" }

Wildcards match everything after:

{ "source": "/docs/:path*", "destination": "/help/:path*" }

Rewrites

Serve content from a different path without changing the browser URL. Files on disk are checked first — rewrites only apply when no file matches.

{
  "rewrites": [
    { "source": "/feed", "destination": "/feed.xml" }
  ]
}

The same pattern syntax as redirects applies (:param, :path*).

SPA fallback

The platform automatically detects single-page apps and configures client-side routing fallbacks. Most SPAs work without any configuration. Use a manual rewrite only if auto-detection doesn't cover your setup:

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

Headers

Add custom HTTP response headers. Unlike redirects and rewrites, multiple header rules can match the same request.

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

Processing Order

Rules are evaluated in this order:

1. Static files — served first if they exist on disk
2. Headers — all matching rules apply
3. Redirects — checked before rewrites
4. Rewrites — only when no file or redirect matched

Within redirects and rewrites, rules are processed in array order. Put catch-all patterns last.