Skip to main content
Contentstack MCP profile hub is in general availability!

Routing with launch.json

•
6 min read

Most sites collect redirects over time. A migration renames /blog to /news, marketing wants /spring to point at a campaign page, and a legacy host still serves half the site. On Launch you handle all of that in one file, launch.json, and the rules run at the CDN edge closest to the visitor. No framework code runs for a redirect, which keeps them fast and keeps your app code clean.

What you'll learn

  • Where launch.json lives and how Launch picks it up

  • How to write redirects with status codes, path variables and regex

  • How to write rewrites that proxy to another path or host

  • How to inject request and response headers

  • Which limits and ordering rules to remember

Create launch.json

Launch concept: launch.json is a configuration file in the root of your project. Launch reads it on every deployment.

Create the file next to your package.json and commit it:

{
  "redirects": [],
  "rewrites": []
}

Nothing happens until you deploy. After a successful deployment, the deployment logs show how many redirects and rewrites Launch loaded. Check that number when a rule doesn't seem to apply. A zero usually means the file is in the wrong folder or is not valid JSON.

The same file also holds the cache priming configuration, which is covered in chapter 3.

Add redirects

A redirect sends the browser to a new URL. The address bar changes.

{
  "redirects": [
    {
      "source": "/spring",
      "destination": "/campaigns/spring-2026",
      "statusCode": 302
    },
    {
      "source": "/blog/:slug",
      "destination": "/news/:slug",
      "statusCode": 308
    },
    {
      "source": "/docs-old",
      "destination": "https://docs.example.com/",
      "statusCode": 301,
      "response": {
        "headers": { "x-redirected-by": "launch" }
      }
    }
  ]
}

Pick the status code on purpose:

Status code

Meaning

Use it for

301

Permanent

Old URLs that never come back

308

Permanent, keeps the HTTP method

The default if you omit statusCode

302

Temporary

Campaigns, maintenance pages

307

Temporary, keeps the HTTP method

Temporary moves of form or API endpoints

The optional response.headers object adds headers to the redirect response itself.

Use path variables and regex

:slug in the example above is a path variable. It captures a segment of the source and you can reuse it in the destination.

You can constrain a variable with a regular expression in parentheses. This redirect moves two blog categories into a new section and drops the category from the URL:

{
  "redirects": [
    {
      "source": "/blogs/:category(product-updates|announcements)/:postId(.*)",
      "destination": "/product-updates/:postId",
      "statusCode": 301
    }
  ]
}

/blogs/announcements/march-release now goes to /product-updates/march-release. /blogs/engineering/march-release does not match and passes through.

Query strings are part of the match. Escape the ? as \\? in JSON, because a bare ? is a regex character. This rule turns /blogs/insights?postId=321 into /blogs/insights/321:

{
  "redirects": [
    {
      "source": "/blogs/:category(.+)\\?(.*)postId=:postId(.+)",
      "destination": "/blogs/:category/:postId",
      "statusCode": 301
    }
  ]
}

One pattern can replace hundreds of literal rules. That matters once you approach the file size limit.

Add rewrites

A rewrite serves a different path or host without changing the URL in the browser. Launch makes the call from the edge, so it works as a reverse proxy.

The most useful rewrite is the incremental migration. Launch serves the pages you have rebuilt, and everything else is proxied to the legacy host:

{
  "rewrites": [
    {
      "source": "/:path((?!blogs|docs|about-us).+)",
      "destination": "https://legacy.example.com/:path",
      "request": {
        "headers": { "x-origin-key": "replace-with-a-shared-secret" }
      }
    }
  ]
}

The negative lookahead (?!blogs|docs|about-us) excludes the migrated sections. The homepage also stays on Launch, because .+ needs at least one character after the slash. The request header lets the legacy host reject traffic that doesn't come through Launch.

You can also proxy one section to a different service:

{
  "rewrites": [
    {
      "source": "/assets/:category(products|storefront)/:path(.*)",
      "destination": "https://assets.example.com/:category/:path",
      "response": {
        "headers": { "x-robots-tag": "noindex" }
      }
    }
  ]
}

Inject headers on every response

A rewrite to the same path is a clean way to add security headers to the whole site:

{
  "rewrites": [
    {
      "source": "/:path(.*)",
      "destination": "/:path",
      "response": {
        "headers": {
          "X-Frame-Options": "DENY",
          "X-Content-Type-Options": "nosniff",
          "Referrer-Policy": "strict-origin-when-cross-origin",
          "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload"
        }
      }
    }
  ]
}

request.headers are added before Launch calls the destination. response.headers are added before the response goes back to the client, and they override headers with the same name from the destination.

Keep this catch-all at the end of the rewrites array. Rules are evaluated in order, so put specific rules before broad ones.

Where people get confused

Client-side navigation skips the edge. Rules in launch.json only run when the browser makes a request to Launch. A <Link> in Next.js or a <NuxtLink> in Nuxt navigates on the client, so a rewrite for that path never runs. Use a plain <a> for links that must go through an edge rule, or handle the route in the framework.

A redirect can get cached. If your origin sends a redirect with a long s-maxage, the CDN keeps serving it after you fix the rule. Don't put long cache lifetimes on redirect responses. Chapter 3 explains how to purge a path if it already happened.

The source cannot contain a hostname. "source": "https://old.example.com/page" does not work. When several domains point at the same environment and need different rules, branch on new URL(request.url).hostname in an edge function.

Monorepos. Launch does not read a launch.json from an app inside a monorepo. If your Launch project builds a sub-folder, move the routing logic into an edge function or check the current Launch docs for your setup.

Limits to remember

Limit

Value

launch.json file size

5 MB

Source URL length

512 characters

Destination URL length

512 characters

Source format

Relative path only

Hash fragments (#)

Never sent to the server, so you can't match on them

A file close to the size limit is slow to process. Long lists of one-to-one redirects usually mean the URLs follow a pattern you haven't written yet, or that the mapping belongs in an edge function that reads it from a data source.

Key takeaways

  • Put launch.json in the project root and check the redirect and rewrite counts in the deployment logs.

  • Default to 308 for permanent moves and 302 for temporary ones, and set statusCode explicitly.

  • Use :param(regex) patterns and escape ? as \\? to match query strings.

  • Use rewrites with a negative lookahead for incremental migrations, and a final /:path(.*) rewrite for global response headers.

  • Move hostname-based or data-driven routing to an edge function.

Frequently asked questions

  • Where does launch.json go?

    In the root of your project. Adding launch.json to an app inside a monorepo is not supported.

  • What status code does a redirect use by default?

    308. Set statusCode to 301, 302, 307 or 308 to choose a permanent or temporary redirect.

  • Can a redirect source include a hostname?

    No. Sources are relative paths. To route by hostname when several domains point to the same environment, use an edge function.

  • How big can launch.json be?

    The file size is limited to 5 MB, and each source and destination is limited to 512 characters. Use regex patterns to keep the file compact.