Theme's Size

As a developer, you know the importance of structuring a customized theme. The theme’s size determines the steps to bundling and uploading your theme. This section focuses on if your bundled theme exceeds the 50 MB upload file size.

Prerequisites

• Customized theme variation that exceeds the 50 MB upload limit after bundling

Size Limit

Ideally, your theme should bundle into an archive of only a few megabytes (MB). BigCommerce imposes a hard limit of 50 MB, but most themes do not approach this limit unless they include many large static assets.

If your bundled theme exceeds the 50 MB limit, you have two options:

1. Shrink your theme with the help of WebDAV
2. Stage your theme for CDN delivery

Shrink your theme with the help of WebDAV

Restructuring your theme

First, isolate your static assets from your theme’s local directory. Then use WebDAV to cloud-host those assets, and finally reference those assets using Stencil’s {{cdn}} Handlebars helper. For an existing theme, don’t forget to always make a backup of your whole theme-name directory before proceeding.

Examine your theme’s assets subdirectory and its intended contents. Check for large static assets like images, especially in assets/img/, and videos that are likely to cause a bundled ZIP file to exceed BigCommerce’s 50 MB limit.

Use WebDAV to upload these items to WebDAV’s remote/content/ directory. For more information on WebDAV, see Connecting to WebDAV.

Throughout your theme, reference each of these assets using Stencil’s {{cdn}} Handlebars helper, prepending the webdav: option to the assetPath parameter.

Prepending webdav: will build a URL in the remote WebDAV directory. This allows your theme’s deployed topology to diverge from your local directory structure. The {{cdn}} helper will treat content as the root WebDAV directory.

See the example below:

<img src="{{cdn "webdav:img/image.jpg"}}">
Builds the following URL:
<img src="https://cdn.bcapp/3dsf74g/content/img/image.jpg">

On your local machine, move the large static assets to a location where the stencil bundle command will ignore them. This can be a location outside your theme’s directory, or it can be the assets/cdn/ subdirectory, which stencil bundle excludes from bundling.

NOTE: Separating these assets is necessary to exclude them from the next step.

Run the stencil bundle command from inside your streamlined theme-name directory. Once your resulting ZIP file is 50 MB or smaller, you are ready to upload it to BigCommerce.

WebDAV folders and the Stencil themes

Depending on the type of theme that is active in the merchant’s store, the directories accessible through WebDAV will change as shown below.

Stencil theme

• content
• product images
• product downloads
• import files
• exports

Stage your theme for CDN Delivery

For themes that would otherwise exceed BigCommerce’s 50 MB limit on uploads, delivering your theme’s large static assets using a CDN is an alternative to WebDAV.

Advantage

The advantage of this alternative is that all assets stay within your theme’s directory, so your theme’s local structure matches its deployed structure.

Disadvantage

The disadvantage is that the procedure outlined below requires the expense of a CDN.

To stage your theme for CDN delivery, you would locally store your large static assets within your theme’s assets/cdn/ subdirectory.

NOTE: By design, the stencil bundle command omits this subdirectory’s contents. So those contents do not count against the 50 MB limit on the resulting ZIP file.

As you develop your theme, reference each of these assets using Stencil’s {{cdn}} custom Handlebars helper, for example:

<img src="{{cdn "webdav:img/image.jpg"}}">