Referencing Static Files with CodePen Asset Hosting

The Problem: Hosting External Assets in CodePen

When building a Pen, you often need custom images, specialized fonts, or JSON data files. While you can link to external hosting services, CodePen provides a built-in Asset Hosting feature for Pro users. This allows you to upload files directly to CodePen's Content Delivery Network (CDN), ensuring your assets are stored alongside your project and served via a stable URL.

How Asset Hosting Works

Asset Hosting is a Pro-tier feature that provides a dedicated storage area for static files. Once a file is uploaded, CodePen generates a permanent URL. These files are served as static assets; the CDN does not perform server-side processing, meaning you cannot dynamically resize images or execute scripts on the hosted files.

Worked Example: Implementing a Custom Logo and Font

1. Open a Pen and click the Settings button in the top navigation.
2. Navigate to the Assets tab (this tab is only available to users with an active Pro subscription).
3. Upload your file (e.g., logo.png) by dragging it into the upload area or using the file browser.
4. Copy the generated URL. It typically follows a pattern similar to https://assets.codepen.io/[account-id]/[file-name].

HTML Implementation:

<img src="https://assets.codepen.io/1234567/logo.png" alt="Company Logo">

CSS Implementation (Custom Fonts): If you upload a font file such as BrandFont.woff2, reference it in your CSS panel using @font-face:

@font-face {
  font-family: 'BrandFont';
  src: url('https://assets.codepen.io/1234567/BrandFont.woff2') format('woff2');
}

Constraints and Limitations

• Subscription Requirement: Asset Hosting is strictly for Pro accounts. Free accounts cannot upload files to the assets.codepen.io domain.
• File Size Limits: There is a maximum limit for individual file uploads (commonly cited as 25 MB), and a total storage quota based on your specific Pro plan tier.
• Static Delivery: Assets are delivered as-is. There is no built-in tool for image optimization or format conversion upon upload.
• CDN Caching: Files are cached globally. This means updates to a file may not be reflected immediately across all regions.

Common Pitfalls and Solutions

The Caching Delay

If you upload a new version of a file with the same name, the browser or CDN may continue to serve the old version. To force an update, use a cache-busting query string. Append a version number to the end of the URL:

<img src="https://assets.codepen.io/1234567/logo.png?v=2">

Incorrect URL Construction

Manually typing the URL can lead to 404 errors if the account ID or filename is slightly off. Always copy the URL directly from the Assets panel to ensure the path is correct.

Storage Quota Exhaustion

If you receive an error during upload, check your storage usage in Account Settings → Billing → Assets. You may need to delete unused legacy assets to make room for new files.

Practical Verification

To verify your assets are working correctly:

1. Upload a small test image (< 100 KB) via Settings → Assets.
2. Insert the resulting URL into an <img> tag in your HTML panel.
3. Check the Pen preview; if the image renders, the asset is public and correctly linked.
4. Open the browser's Developer Tools (F12) and check the Network tab to confirm the request to assets.codepen.io returns a 200 OK status.