Skip to main content

Create a Web Resource

Goal​

Add a Web Resource — an application file such as a JavaScript bundle, a stylesheet, an HTML fragment, a logo, or an SVG — that the platform stores in the database and packages with your solution, so it travels wherever the solution is imported.

A Web Resource is for the files an application is built from. A large document a user uploads at runtime is not a Web Resource — that belongs in file storage. A per-file size limit keeps the two apart.

Prerequisites​

  • You are signed in to the Admin Control Center.
  • An environment is selected in the top bar, and you have opened a solution (see Create a solution).

Steps​

  1. In the open solution, choose Web Resources in the left navigation.
  2. Select New.
  3. Enter a display name and a logical name. The logical name is publisher-prefixed and path-like — for example par_/dashboard/app.js or par_/logo.svg.
  4. Choose the type (JavaScript, CSS, HTML, JSON, XML, text, PNG, JPEG, GIF, SVG, icon, or other/binary).
  5. Provide the content:
    • For a text type (JavaScript, CSS, HTML, JSON, XML, text, SVG) you can either edit it inline in the editor or upload a file.
    • For an image or binary type you upload a file (there is nothing to type).
  6. Select Save. The file is stored with the solution and can be served by the platform.
  7. The list shows each file's Address: where the platform serves it. Open it in a new tab, or copy it with the button beside it, to hand it to whatever fetches the file.

A page that links its stylesheet, its script and its images by relative address needs all of them stored side by side. Rather than creating them one at a time:

  1. Zip the files: the files themselves, not a folder around them.
  2. On Web Resources, select Upload a folder.
  3. Give it a display name and a folder under your publisher's prefix, for example par_/badge.
  4. Choose the zip and select Upload.

Every file is created under that folder keeping its relative path, so badge.html linking badge.css finds par_/badge/badge.css.

Uploading to the same folder again replaces what is there, removing files the new zip no longer has. That is how you publish a change: a web resource is not edited in place. Files the platform does not serve, such as a .map, are skipped, and the result says which.

A Custom App or Custom Control is not uploaded here. Each is one package, installed under Custom Apps or Custom Controls (see Register a Custom Control).

What happens behind the scenes​

The file's bytes are stored in the platform database and recorded as a component of your solution, so exporting the solution carries the file with it and importing the solution re-creates it in the target environment. The platform validates the file's metadata, checks that the logical name starts with your publisher's prefix, and rejects a file that is over the size limit — a large file should go to file storage instead. The platform can then serve the file from its own address with the correct content type.

The Address in the list is …/environments/<environment>/webresources/<logical name>, and it answers anyone, without signing in: that is what lets a page, a printer or an email load the file. Put nothing in a web resource you would not publish.

Troubleshooting​

  • "…must start with the publisher prefix…" — the logical name has to begin with your publisher's prefix followed by _ (for example par_).
  • "The web resource manifest is invalid…" — the logical name must be lower-case and contain only letters, digits, _, ., /, or - (no spaces).
  • "…is over the … cap. Large files belong in Object Storage…" — the file exceeds the per-resource size limit; store large files in file storage, not a Web Resource.
  • "A web resource '…' already exists in this environment." — a resource with that logical name is already present; choose a different name.
  • "The bundle entry '…' has a path that would escape its folder." — the zip holds a .. segment or an absolute path. Zip the files themselves, not a path above them.
  • "The bundle holds no files the platform can serve." — nothing in the zip has a type the platform serves. Check you zipped the files and not a folder of something else.
  • "The bundle holds … files; the limit is 200." — almost certainly the wrong folder was zipped (node_modules, most likely).
  • Create a solution.
  • Register a Custom React App.