Web Files Best Practices

Web File Size Limit

By default, the maximum size for a single Web File is set to 256 KB. For configuration details, see Web Files Configuration. This limit is intentionally conservative.

Rationale

Web Files are designed to be cached indefinitely by browsers and intermediate caching layers such as CDNs, Varnish, Squid, mod_cache, or nginx. This approach improves page rendering speed by ensuring that static assets like CSS, JavaScript, and images are always served from cache when possible.

The HST framework sets the Expires header to one year for Web Files, allowing clients to cache them long-term. When a Web File changes, its URL path (including a cache-busting segment) also changes. This forces clients to fetch the updated file. All references to Web Files in your HTML are updated to use the new URLs, ensuring clients always receive the latest versions while benefiting from aggressive caching.

Because a change to any Web File can update the URLs for all Web Files (to account for dependencies such as CSS imports), avoid storing large or rarely changing files in the Web Files system. For example, if your JavaScript depends on a large library like angular.js (~1 MB), store it as a static web application file at /site/webapp/src/main/webapp/js/angular.js. Reference this file directly in your JSP or Freemarker templates.

For large videos, documents, or images, do not store them in Web Files or in the CMS as gallery items or assets. Instead, integrate with a dedicated digital asset management (DAM) solution.

To reference a static web application file (located under /site/webapp/src/main/webapp) from within a Web File, use a relative path.

Example

Suppose you have the following Web File structure:

/repository-data:
  /webfiles:
    /src:
      /main:
        /resources:
          /site:
            /css:
              /style.css:
copy

If style.css needs to import a large, rarely changing file such as bootstrap.css (5 MB), do not store bootstrap.css in Web Files. Instead, place it at:

/site/webapp/src/main/webapp/css/bootstrap.css

Then, in style.css, import it using:

@import '../../../css/bootstrap.css';

The additional ../ in the path accounts for the anti-cache timestamp segment in the URL for style.css.

Web Files Folder Size

During local development, performance has been tested with over 1,000 small files in a single folder. Adding, removing, or updating files remains fast even with a large number of files. However, some operations are more resource-intensive. For example, deleting a file causes the entire folder to be re-imported. The more files or larger the files in a folder, the longer these operations take.

To maintain performance during development, keep the number of files per folder manageable. If a folder contains more than 100 files, create subdirectories to organize your assets. While this is less critical in production environments, it significantly improves efficiency during local development.