Skip to main content

Specifying Headers, Routing, and Metadata

In its base configuration, Walrus Sites serves static assets through a portal. However, many modern web applications require more advanced features, such as custom headers and client-side routing.

Therefore, the site-builder can read a ws-resources.json configuration file, in which you can directly specify resource headers and routing rules.

The ws-resources.json file​

This file is optionally placed in the root of the site directory, and it is not uploaded with the site's resources. If you don't want to use this default location, you can specify the path to the configuration file with the --ws-resources flag when running the deploy, publish or update commands.

The file is JSON-formatted, and looks like the following:

{
  "headers": {
    "/index.html": {
    "Content-Type": "text/html; charset=utf-8",
    "Cache-Control": "max-age=3500"
    }
  },
  "routes": {
    "/*": "/index.html",
    "/accounts/*": "/accounts.html",
    "/path/assets/*": "/assets/asset_router.html"
  },
  "metadata": {
    "link": "https://subdomain.wal.app",
    "image_url": "https://www.walrus.xyz/walrus-site",
    "description": "This is a walrus site.",
    "project_url": "https://github.com/MystenLabs/walrus-sites/",
    "creator": "MystenLabs"
  },
  "site_name": "My Walrus Site",
  "object_id": "0xe674c144119a37a0ed9cef26a962c3fdfbdbfd86a3b3db562ee81d5542a4eccf",
  "ignore": ["/private/*", "/secret.txt", "/images/tmp/*"]
}

The ws-resources.json file expects the field names to be in snake_case.

Specifying HTTP response headers (headers)​

The headers section allows you to specify custom HTTP response headers for specific resources. The keys in the headers object are the paths of the resources, and the values are lists of key-value pairs corresponding to the headers that the portal attaches to the response.

In the example, the file index.html is served with the Content-Type header set to text/html; charset=utf-8 and the Cache-Control header set to max-age=3500. he resource path is always represented as starting from the root /.

This mechanism allows you to control various aspects of the resource delivery, such as caching, encoding, and content types.

Default headers​

By default, no headers need to be specified, and the ws-resources.json file can be omitted. The site-builder automatically tries to infer the Content-Type header based on the file extension, and set the Content-Encoding to identity (no transformation).

In case the content type cannot be inferred, the Content-Type is set to application/octet-stream. These defaults are overridden by any headers specified in the ws-resources.json file.

Specifying client-side routing (routes)​

The routes section allows you to specify client-side routing rules for your site. This is useful when you want to use a single-page application (SPA) framework, such as React or Angular. The configuration in the routes object is a mapping from route keys to resource paths.

The routes keys are path patterns in the form /path/to/some/*, where the * character represents a wildcard.

info

Currently, the wildcard can only be specified at the end of the path. Therefore, /path/* is a valid path, while /path/*/to and */path/to/* are not.

The routes values are the resource paths that should be served when the route key is matched. These paths in the values must be valid resource paths, meaning that they must be present among the site's resources. The Walrus sites contract aborts if you try to create a route that points to a non-existing resource.

The simple routing algorithm is as follows:

  • Whenever a resource path is not found among the sites resources, the portal tries to match the path to the routes.

  • All matching routes are then lexicographically ordered, and the longest match is chosen.

  • The resource corresponding to this longest match is then served.

In the previous example:

"routes": {
  "/*": "/index.html",
  "/path/*": "/accounts.html",
  "/path/assets/*": "/assets/asset_router.html"
}

The following matchings occur:

  • Browsing /any/other/test.html serves /index.html.

  • Browsing /path/test.html serves /accounts.html, as it is a more specific match than the previous one.

  • Similarly, browsing /path/assets/test.html serves /assets/asset_router.html.

/index.html, /accounts.html, and /assets/asset_router.html are all existing resources on the Walrus Sites object on Sui.

Displaying the site object on wallets and explorers (`metadata)​

It's possible to make your Site object prettier by displaying information about it on Sui explorers and wallets by using the metadata field. This is useful for adding human-readable information about the site. For example, you can add a link to your site's homepage, an image of your site's logo, and so on.

In the previous example, the fields correspond to the basic set of properties suggested by the Sui Display object standard.

"metadata": {
    "link": "https://subdomain.wal.app",
    "image_url": "https://www.walrus.xyz/walrus-site",
    "description": "This is a walrus site.",
    "project_url": "https://github.com/MystenLabs/walrus-sites/",
    "creator": "MystenLabs"
  }

All metadata fields are optional and can be omitted if not needed. There are some default values specified in the site-builder CLI, which can be overridden by your configuration.

It is recommended to use the above fields like this:

  • link: Add a link to your site's homepage.

  • image_url: Include a URL to your site's logo which is displayed on your wallet. For example you can place a link to your sites favicon.

  • description: Add a brief description of your site.

  • project_url: If your site is open-source, add a link to your site's GitHub repository.

  • creator: Add the name of your company, group, or individual creator of your site.

Site name (site_name)​

You can set a name for your Walrus Site through the optional site_name field in your ws-resources.json file. In case you have also provided a site name through the --site-name CLI flag, the CLI flag takes priority over the site_name field in the ws-resources.json, which is overwritten. If a site name is not provided at all, then a default name is used.

Site object ID (object_id)​

The optional object_id field in your ws-resources.json file stores the Sui object ID of your deployed Walrus Site.

The site-builder deploy command primarily uses this field to identify an existing site for updates. If a valid object_id is present, deploy targets that site for modifications. If this field is missing and no --object-id CLI flag is used, deploy publishes a new site. If successful, then the command automatically populates this object_id field in your ws-resources.json.

Ignoring files from being uploaded​

You can use the optional ignore field to exclude certain files or folders from being published. This is useful when you want to keep development files, secrets, or temporary assets out of the final build.

The ignore field is a list of resource paths to skip. Each pattern must start with a /, and might end with a * to indicate a wildcard match.

For example:

"ignore": [
  "/private/*",
  "/secret.txt",
  "/images/tmp/*"
]

This configuration skips all files inside the /private/ and /images/tmp/ directories, as well as a specific file /secret.txt.

Wildcards are only supported in the last position of the path, for example, /foo/* is valid, but /foo/*/bar is not.