Skip to main content
Assets are the images and media files that appear throughout your portfolio — hero backgrounds, project covers, blog post thumbnails, and profile photos. Studio includes a built-in asset manager so you can upload files directly from your browser, reference them in any image field, and have them committed to your repository automatically when Save2Repo is enabled.

​
Uploading an Asset

You upload assets from within any image field in Studio — there is no separate upload page to visit.
1

Open an image field in Studio

Navigate to /admin, select the page or collection entry you want to edit, and click an image field. The asset picker opens inline.
2

Choose a file to upload

Click Upload in the asset picker and select a file from your local machine. Studio sends the file to POST /api/upload-asset.
3

Select the uploaded asset

After the upload completes, the file appears in the asset list. Click it to populate the image field’s url property automatically.
4

Add alt text

Fill in the alt field with a descriptive caption for the image. This is required for accessibility and SEO.
5

Save your changes

Click Save. In Save2Repo mode, the uploaded file and the updated JSON are both committed to your GitHub repo in the same operation.
Both url and alt are required on every image field. Studio will warn you if alt is empty before allowing a save.

​
How Assets Are Stored

Where your uploaded files live depends on your environment. In Save2Repo mode, assets become part of your repository’s version history. Every upload is traceable and reversible through standard Git operations.

​
Asset API Endpoints

Studio uses three protected API routes to manage assets and content. All routes require an authenticated session on Vercel deployments.
These endpoints are admin-only. The middleware blocks all unauthenticated requests to these routes on Vercel when ADMIN_PUBLIC_KEY is configured. Do not expose these routes publicly.

​
Supported File Formats

Studio accepts the following image formats for upload:
  • JPEG (.jpg, .jpeg) — photographs and complex images
  • PNG (.png) — images requiring transparency
  • WebP (.webp) — recommended for best compression and quality
  • SVG (.svg) — logos, icons, and vector graphics
  • GIF (.gif) — simple animations
SVG files are ideal for logos and icons because they scale without quality loss. For photographs and section backgrounds, prefer WebP.

​
Best Practices

Follow these guidelines to keep your portfolio loading fast and looking sharp.

​
Optimize Before Uploading

1

Resize to the display size

Export images at the size they’ll be displayed. For full-width hero backgrounds, 1600px wide is sufficient. For thumbnails, 800px wide is plenty.
2

Use WebP format

Convert JPEG and PNG images to WebP before uploading. WebP typically produces 25–35% smaller files at equivalent visual quality.
3

Compress the file

Run images through a compressor (e.g., Squoosh or ImageOptim) before upload. Aim for files under 300KB for most use cases.

​
Use Unsplash for Placeholder and Stock Photography

The default content in next-dev-portfolio uses Unsplash URLs with query parameters for on-the-fly resizing. You can do the same in any image field without uploading anything:
For portfolio hero images, ?w=1600&q=80 on an Unsplash URL gives you a high-quality, fast-loading image without any upload step. Add &fm=webp to serve WebP to supported browsers automatically.

​
Always Write Descriptive Alt Text

Every image field in a page section has both a url and an alt property. Both are required.
Good alt text:
  • Describes the content and purpose of the image
  • Is concise — typically one sentence or fewer
  • Does not begin with “image of” or “photo of”
  • Is unique per image
Poor alt text:
  • Empty strings ("")
  • Generic labels ("hero", "image1")
  • Redundant descriptions already present in surrounding text