settings.toml

The .webslice/settings.toml file allows you to configure various settings directly from your repository instead of through your website settings in the Webslice Console. Place it in the .webslice directory at the root of your repository and any settings defined here will override matching settings in the Webslice Console. Conversely, settings that are not defined will continue to use their existing values.

Note

The .webslice/settings.toml file is only supported for websites using git deploys. It is not available for file deploys or SFTP.

This is useful for keeping your configuration versioned alongside your code, making it easier to review changes, share settings across team members, and maintain consistency between environments.

File Structure

The .webslice/settings.toml file uses the TOML format and currently supports the following sections:

.webslice/settings.toml

[deploy]
publish = "dist"

[deploy.commands]
build = "build.sh"
release = "release.sh"

[cdn.redirects]
"www.example.com" = { to = "example.com", type = 301 }
"old.example.com" = { type = 444 }

Settings

[deploy]

publish

An optional setting that specifies the directory containing your built site, relative to the repository root. When set, only the contents of this directory are copied to the live site instead of the entire repository. This is an optimization for faster deploys, as it reduces the amount of files that need to be synced.

[deploy]
publish = "dist"

Common values include dist, public, build, or _site depending on your framework.

Note

Since only the specified directory is deployed, your site must be fully self-contained within it. If your application depends on files outside this directory (e.g. files in the repository root), they will not be available on the live site.

[deploy.commands]

build

The path to your build script, relative to the repository root. This script runs during the deployment process to install dependencies, compile assets, and prepare your application.

[deploy.commands]
build = "build.sh"

release

The path to your release script, relative to the repository root. This script runs after your deployment is live and is typically used for database migrations, cache warming, or post-deployment tasks.

[deploy.commands]
release = "release.sh"

[cdn.redirects]

Configures domain-level redirects and connection drops at the CDN edge. Each entry maps a source domain (which must be a verified domain on the website) to a redirect target or a drop rule.

When a [cdn.redirects] section is present, it is the sole source of truth for all CDN redirects on the website. Redirects set here take effect on the next deploy and override any redirects configured in the Webslice Console. Domains removed from the section will have their redirect cleared on the next deploy.

Note

While a [cdn.redirects] section exists in your settings.toml, the redirect settings in the Webslice Console are locked. To manage redirects from the Console again, remove the [cdn.redirects] section entirely.

Redirect to another domain

Redirects all traffic from a source domain to a target domain. Both domains must be verified on the same website. Use type = 301 for a permanent redirect or type = 302 for a temporary one. If type is omitted, it defaults to 301.

[cdn.redirects]
"www.example.com" = { to = "example.com", type = 301 }
"old.example.com" = { to = "example.com", type = 302 }

The redirect preserves the request path and query string. For example, a visitor to https://www.example.com/about?ref=foo will be redirected to https://example.com/about?ref=foo.

Drop connections (444)

Silently closes incoming connections on a domain without returning an HTTP response. This is useful for blocking traffic to unwanted domains entirely, such as the default edge domain once you have a custom domain set up.

[cdn.redirects]
"pgba4vw8p0vocg6s.onwebslice.com" = { type = 444 }

Full Example

Here’s a complete .webslice/settings.toml for a site that builds to the dist directory and redirects www to the apex domain:

.webslice/settings.toml

[deploy]
publish = "dist"

[deploy.commands]
build = ".webslice/build.sh"
release = ".webslice/release.sh"

[cdn.redirects]
"www.example.com" = { to = "example.com", type = 301 }
"pgba4vw8p0vocg6s.onwebslice.com" = { type = 444 }

Tip

You only need to include the settings you want to configure. For example, if you only need to set a build command, you can omit the publish and release settings entirely.