Web Files Best Practices

Web File size limit

By default, the Web File size limit is configured to be 256 Kb, see Web Files Configuration. On purpose, this value is not very high. Why? 

Why:

Our Web Files support has a very strong feature: Once a Web File has been served, it can be cached indefinitely on the client (browser) and on any intermediate content delivery network CDN or (caching) proxy, like varnish, squid, mod_cache, nginx, etc. Caching files like css, js, png etc on the client is required if you want a good customer experience with respect to rendering speed of the pages. The HST serves the Web Files with an expires of 1 year, aka, cache indefinitely on the client. When a Web File changes, the pathInfo in the URL changes as well, which triggers a reload for any client that requests the Web File. So, instead of invalidating or not caching a resource, we cache it indefinitely and change the URL in the html that triggers a get on the Web File. Since in case of for example cascading stylesheets (css files) importing other css files, also the imported stylesheet should be refetched, all URLs for all Web Files change are uploading new Web Files. This way, every client always gets all the most recent Web Files, while still being able to cache them all indefinitely. Since a change in a Web File changes the URLs of all Web Files (because of possible imports), you can better not store very large or large never changing files in there. Thus, when for example your javascript Web Files require angular.js (~ 1 Mb file), you can also store as static webapp file at /site/src/main/webapp/js/angular.js, and in your JSP or freemarker template just create a link for this static webapp file. 

If you have large movies, pdfs, or images, instead of storing them in Web Files, rather store them in the CMS as gallery item or asset.

If you want to reference a static webapp file (below /site/src/main/webapp) from a Web Files file, you need to use a relative path. The relative path is as follows:

An Example:

Assume you have a Web File as follows

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

and style.css needs to import a 5 Mb never changing  bootstrap.css, then, you can better not store this never changing bootstrap.css in Web Files. Instead, store it at

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

And in style.css import is as follows:

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

If you would had expected one ../ less, this is because one ../ is there to account for the path segment containing the anti-cache timestamp in the URL for style.css.

Web Files folder size

For local development, we tested with 1000+ small files in a single folder. Adding / removing / updating files is fast for quite large number of files in a single folder. Some operations however are more expensive than others. For example deleting a file in a folder triggers the folder to be re-imported. The more files a folder contain, the longer it will take. Likewise, the large the files are, the longer it will take. Hence we advice to keep the number of files within a folder not too large, and create subdirectories, for example when you have more than 100 files in a single folder. Note that on production it does not really matter, but most specifically during local development.