Redirects and Path Rewrites

Handle redirects and path rewrites with Stormkit at the load balancer level.

Overview

Stormkit is able to handle path rewrites and redirects on the load balancer level. This allows you to:

• Redirect old URLs to new ones
• Rewrite paths without changing the URL
• Proxy requests to external services
• Configure custom 404 pages
• Set up domain-specific routing

Configuration

To make use of this feature, create a redirects.json file at the root level of your repository. This file will be parsed on each deployment, so if you change this file, previous deployments won’t be affected.

redirects.json

[
  {
    "from": "string",      // (required): The path. Supports regexp syntax.
    "to": "string",        // (required): The destination path.
    "status": "number",    // (optional): The HTTP Status Code for redirect. Default is empty.
    "assets": "boolean",   // (optional): Whether to apply to static files. Default is false.
    "hosts": "Array<string>" // (optional): Apply rule only for specific hosts.
  }
]

Path Rewrites

If you omit the status property, or provide a status different than 3xx, Stormkit will not redirect the request but will simply rewrite the path.

redirects.json

[
  {
    "from": "/my-path/*",
    "to": "/my-new-path/$1"
  }
]

In this case, all requests coming to /my-path will be served as if they were coming to /my-new-path.

Path rewrites are transparent to the user - the URL in the browser doesn’t change.

Redirects

301 Permanent

Use for permanent URL changes. Search engines will update their indexes.

302 Temporary

Use for temporary redirects. Search engines won’t update their indexes.

307 Temporary

Like 302 but preserves the HTTP method (POST, PUT, etc.).

308 Permanent

Like 301 but preserves the HTTP method.

Proxies

You can also use redirects as a proxy. If your redirect is an absolute URL (starting with http), the request will be proxied.

redirects.json

[
  {
    "from": "/my-path/*",
    "to": "https://example.com/my-new-path/$1",
    "status": 200
  }
]

In this case, all requests coming to /my-path will be proxied to https://example.com/my-new-path/*.

Proxied requests will add latency as the request is forwarded to the external service.

Common Examples

SPA Configuration

redirects.json

[
  {
    "from": "/*",
    "to": "/index.html"
  }
]

The above example will rewrite all requests to index.html. By setting assets to false (default), static files are not affected. This is useful for single page applications.

Redirect Non-WWW to WWW

redirects.json

[
  {
    "from": "stormkit.io",
    "to": "www.stormkit.io",
    "assets": true,
    "status": 301
  }
]

Regular Expressions

redirects.json

[
  {
    "from": "/documentation/*/page/*",
    "to": "/docs/$1/$2"
  },
  {
    "from": "/documentation$",
    "to": "/docs"
  }
]

You can use regexp syntax for redirects. The example above creates two redirects:

1. The first one will redirect /documentation/welcome/page/getting-started to /docs/welcome/getting-started
2. The second will redirect /documentation to /docs

Note the $ sign at the end of the string. That sign simply tells to redirect only the path /documentation and not anything that contains /documentation.

Matching Host Names

redirects.json

[
  {
    "from": "/path",
    "to": "/new-path",
    "hosts": ["example-a.org"]
  },
  {
    "from": "/path",
    "to": "/different-path",
    "hosts": ["example-b.org", "example-c.org"]
  }
]

If you have multiple domains configured for your environment, you can specify for which host name the redirect rule should apply to.

The example above will rewrite the /path to /new-path for example-a.org and to /different-path for example-b.org and example-c.org.

Custom 404 Pages

By default, when a page is not found, Stormkit will try to serve /404.html or /error.html if any of these files are found in your deployment. You can customize this behavior:

1. Navigate to Redirects config

   Go to Environment Config > Redirects

2. Set custom error file

   Find the Custom Error File field and type the file that should be served instead (e.g., /index.html)

3. Save

   Click save. Changes take effect immediately.

This setting will be applied to all of your deployments and take effect instantly. There is no need for a deployment.

• If you have API routes configured, the custom error file will not be applied to paths starting with your API Path (default: /api)
• If you have serverless side logic, the custom error file will not be applied

Redirecting API Routes

Please note that if your application contains API routes, paths starting with /api will not be matched. This is to allow /api routes to handle the redirect themselves.

If you do not have any API function, this rule does not apply.

You can configure the API routes through the Serverless configuration section.

Environment Level Redirects

You can specify the same rules at an environment level, which will override the redirects.json file.

1. Navigate to Redirects config

   Go to Environment Config > Redirects

2. Enable overwrite

   Switch Overwrite redirects toggle

3. Add rules

   Specify the rules from the Redirects Editor

4. Save

   Click save

These rules will be applied to all of your deployments and take effect instantly. There is no need for a deployment.

Best Practices

• Test redirects - Verify redirect rules work as expected before deploying to production
• Use 301 for permanent changes - This helps with SEO
• Keep regex simple - Complex regex can be hard to maintain
• Document redirects - Comment why specific redirects exist
• Monitor redirect chains - Avoid multiple redirects in sequence