Static Resources
A static resource is a file you upload to Salesforce so your code can reference it by name.
Definition
A static resource is a file you upload to Salesforce so your code can reference it by name. Static resources hold the supporting assets that custom UI needs, such as JavaScript libraries, CSS stylesheets, images, fonts, and ZIP or JAR archives that bundle several related files together.
Once uploaded, a static resource is served by Salesforce and pulled in from Visualforce pages, Aura components, and Lightning Web Components. Each resource can be up to 5 MB, and a single org can hold up to 250 MB of static resources in total.
How static resources fit into custom UI
What counts as a static resource
A static resource is any file your custom UI depends on but that does not belong in a record or a code body. Common examples are a third-party JavaScript library, a CSS stylesheet, a logo image, a web font, or a ZIP archive that packs many files into one upload. Salesforce accepts archives (.zip and .jar), images, stylesheets, JavaScript, and most other file types. The upload itself lives in Setup under Static Resources. Each resource has a Name, an optional Description, a MIME type that Salesforce infers from the file, and a Cache Control setting. The Name is how code finds the file later, so it matters. A resource holds exactly one uploaded file, but that one file can be an archive containing dozens of assets. That is the usual pattern for shipping a library with its images and stylesheets as a single unit. Treat the upload as a versioned artifact, because every page and component that names it will break if you delete or rename it carelessly.
Naming rules that the platform enforces
The Name field is not free text. Salesforce enforces a strict pattern so the value can be used safely as an identifier inside merge fields and import statements. A static resource name must begin with a letter and may contain only alphanumeric characters and underscores. Spaces are not allowed. The name cannot end with an underscore, and it cannot contain two underscores in a row. It also has to be unique within the org. These rules exist because the name becomes a token in code. In Visualforce you write $Resource.MyLibrary, and in a Lightning Web Component you import from @salesforce/resourceUrl/MyLibrary. A space or an odd character would break that reference. One helpful behavior: when you rename a static resource in Setup, Salesforce automatically updates the references in your Visualforce markup. That safety net does not extend everywhere, so renaming a resource that Apex or LWC code points to still needs a manual code check before you save.
Cache Control: Public versus Private
Every static resource carries a Cache Control value of either Public or Private, and the choice changes who can reach the cached copy. Public means the resource is accessible to all internet traffic, including unauthenticated users, once it is cached. Salesforce stores it in a shared cache, which gives faster load times because one cached copy serves many people. Private means the resource is stored in an individual user cache for the duration of the session, and the cached data is not shared with other users. The practical rule is simple. Use Public for anything served on a public page, such as a Salesforce Site or an Experience Cloud guest page, where the file holds no sensitive data and you want it cached aggressively. Use Private for resources that should only reach authenticated users inside the org. Getting this wrong on a public site can mean assets do not cache the way you expect, which shows up as slow first loads or, in the other direction, content cached more broadly than intended.
Referencing a resource in Visualforce
Visualforce uses the $Resource global merge field to point at an uploaded file. For a standalone file you name the resource directly. A stylesheet goes in with apex:stylesheet and a value of {!$Resource.MyStyles}. A script uses apex:includeScript, and an image uses apex:image with value {!$Resource.MyLogo}. When the resource is a ZIP archive, you reach a file inside it with the URLFOR function. The pattern is {!URLFOR($Resource.MyArchive, 'images/logo.png')}, where MyArchive is the resource name and the second argument is the path to the file within the archive. This is why archives are so common for libraries. You upload one ZIP, then address each asset inside it by its relative path. The same URLFOR approach lets a stylesheet inside an archive correctly resolve its own relative references to fonts or images packaged alongside it, which keeps a third-party library working without edits.
Referencing a resource in LWC and Aura
Lightning Web Components do not use merge fields. Instead you import the resource URL into JavaScript. The statement is import myResource from '@salesforce/resourceUrl/resourceReference', where resourceReference is the static resource name. You can then bind it in the template with standard {property} syntax, or load a script or stylesheet at runtime with the platformResourceLoader module by passing the imported URL to loadScript or loadStyle. Aura components take a third approach. They expose a $Resource global value provider, so markup can reference an uploaded image, stylesheet, or script with an expression. The takeaway is that the same uploaded file works across all three UI technologies, but each one reaches it differently. Visualforce uses $Resource merge fields, Aura uses the $Resource value provider, and LWC imports from the @salesforce/resourceUrl scoped module. Picking the right syntax for the framework you are in is the only real gotcha when wiring a resource into a component.
Source control and deployment
Static resources are metadata, so they move between orgs through the same pipelines as code. In a Salesforce DX project they live in the force-app/main/default/staticresources folder. Each resource is stored as the uploaded file plus a companion .resource-meta.xml file that records the content type and the cache control value. The folder does not use subdirectories for separate resources, so the file name and its meta file sit side by side. Because the resource and its metadata are plain files on disk, they belong in version control next to the components that use them. That is what makes the build-artifact mindset real. You can diff a library upgrade, review it in a pull request, and deploy it with the Metadata API or the Salesforce CLI. It also means you should retire resources the same way you add them, by removing them from the package and deploying the change, rather than deleting in production and hoping nothing still references the old name.
Limits, performance, and housekeeping
Two hard numbers shape how you use static resources. A single resource cannot exceed 5 MB, and the whole org is capped at 250 MB of static resources combined. A large library that pushes past 5 MB has to be split or trimmed, which is one reason teams favor minified production builds over full development bundles. The 250 MB org total is generous, but years of accumulated, unused resources can creep toward it. Performance is the other reason to stay tidy. Anything loaded on a frequently viewed page becomes part of that page's effective performance budget. An oversized JavaScript library that downloads on every render slows the experience, and an outdated version can introduce subtle bugs that only appear when a browser tightens security rules. Periodically audit which components depend on which resources, retire what nothing references, and keep production assets minified. A clean static resource catalog loads faster and is far easier to reason about during an upgrade.
How to create a static resource
Upload a file as a static resource in Setup so your Visualforce, Aura, or Lightning Web Component code can reference it by name. The steps below create a single resource; package it in a ZIP first if you need to upload several related files together.
- Open Static Resources in Setup
From Setup, type Static Resources into Quick Find and select it, then click New to start a new resource.
- Name the resource
Enter a Name that begins with a letter and uses only letters, numbers, and single underscores. Avoid spaces, trailing underscores, and consecutive underscores. Add a Description so future admins know what the file is for.
- Upload the file
Click Browse and choose the file. It must be 5 MB or smaller. To bundle a library with its images and stylesheets, zip them together and upload the single archive.
- Set Cache Control
Choose Public for files served on public Sites or Experience Cloud guest pages, or Private for resources that should reach only authenticated users in the org. Then click Save.
- Reference it from code
In Visualforce use $Resource.YourName, in LWC import from @salesforce/resourceUrl/YourName, and in Aura use the $Resource value provider. For a file inside a ZIP, use URLFOR($Resource.YourName, 'path/file.ext').
The unique identifier code uses to reference the resource. Must begin with a letter and contain only alphanumeric characters and underscores, with no spaces or consecutive or trailing underscores.
The uploaded file itself, up to 5 MB. Can be a single asset or a ZIP or JAR archive that packages many files together.
Public shares one cached copy with all traffic for faster loads; Private keeps the cached copy in each user session and limits it to authenticated users.
- The 5 MB per-resource cap is hard. Split or minify any library that exceeds it rather than trying to upload the full bundle.
- Renaming a resource auto-updates Visualforce markup, but it does not fix references in Apex or LWC. Check that code by hand before renaming.
- Choosing Private on a resource served from a public Site can stop it from caching as expected, which shows up as slow first loads for guests.
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Static Resources.
Hands-on resources to go deeper on Static Resources.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is required before deploying Static Resources-related code to production?
Q2. Where would a developer typically work with Static Resources?
Q3. What is a Governor Limit in the context of Static Resources?
Discussion
Loading discussion…