Add Vyso to an existing website without a full migration

You can introduce Vyso into an existing website without replacing the CMS or rebuilding the frontend. Start with selected source assets, add them to the Vyso library, and update the website references that should use Vyso delivery.

That still involves media migration work. The source must be available to Vyso, and the consuming page must request the intended representation. The first placement can be small even when the eventual rollout is large.

Separate website migration from media adoption

A full platform migration replaces parts of the web stack, such as the CMS, application database, frontend or routing. Adding Vyso to selected media placements does not inherently require those changes.

Media adoption has a narrower scope: decide which sources belong in Vyso, how editors select them, and where the application stores their references. The existing CMS can continue holding article text, product information and publishing state.

existing website or CMS
→ selected source assets added to Vyso
→ asset references updated in the application
→ requested images delivered through Vyso CDN URLs

Your page routes, CSS framework and hosting can stay in place. Depending on the implementation, the work may involve a media field, a template helper or an image component. A static page with one hardcoded image and a CMS with structured media records need different changes.

Choose a first scope you can verify

Choose a boundary that editors and developers can identify. Avoid an initial project defined only as "move all our images." These are practical starting points:

New assets first

From a chosen date, upload new website images to Vyso and use its delivery URLs in new content. Existing published media keeps its current references. This avoids making the historical library a prerequisite for adoption.

The editorial change is real: someone needs to upload the source, select the asset and put its reference into the publishing workflow. Document that handoff so new content does not accidentally continue using the old upload path.

One page or section first

Start with a landing page, a blog section or one product category. Bring in the sources used by that area and update its placements. This contains the rollout while you check page rendering and the editor's asset-selection process.

One image role first

Article heroes or product-card images make useful pilots when they share a rendering helper. That helper can apply a consistent delivery recipe while other image roles continue using their existing sources.

Library first, delivery later

A team can add assets to the library for organization and discovery while leaving website delivery unchanged. Vyso supports generated context for images alongside user-managed metadata and library search. Using those library functions does not require changing a published website image.

This creates a period with two locations holding media. Decide which location is authoritative for new sources and who maintains the relationship between an existing website image and its Vyso asset.

Add sources before changing delivery references

Vyso's application supports file uploads. The documented upload API accepts one asset per request at POST https://api.vyso.io/v1/assets/upload, with the binary in a multipart field named file. Check the current upload limits and workspace storage capacity before selecting a migration batch.

For a newly stored file, the upload response includes its source key as asset.key. Use that returned key for delivery. The original filename, a legacy website URL and the management asset identifier are not interchangeable with the stored key. The assets reference covers retrieving library records.

For an existing website image, obtain the source file and upload it through a supported path before changing its reference. Merely replacing the hostname in /uploads/hero.jpg does not create a Vyso source asset. The delivery model resolves a Vyso asset key, not an arbitrary remote website URL.

Keep the authoritative original available. A resized website export is a delivery representation and may be a poor substitute for the source you will need later. Vyso delivery uses the stored source to generate requested representations without overwriting it.

Management requests use an authenticated Clerk session bearer token. Keep privileged management credentials out of public page code; ordinary image rendering uses the public CDN URL. Follow the authentication contract when building an editor or backend integration.

Change one consuming reference

A static page might currently contain:

<img
  src="/uploads/hero.jpg"
  alt="A red outdoor jacket photographed against a white background"
>

After uploading the source and obtaining its key, the same placement can request a Vyso representation:

<img
  src="https://cdn.vyso.io/resize:width=1200/ASSET_ID.jpg"
  alt="A red outdoor jacket photographed against a white background"
>

Replace ASSET_ID.jpg with the actual key. Choose the requested width for the placement; 1200 is an example. This changes the source of this image representation. The rest of the website remains outside this change.

The public delivery contract puts transformations in the URL path. Output format remains the source format unless an explicit format transformation or a format-specific operation changes it. For example, adding format:type=webp explicitly requests WebP; moving delivery to Vyso does not establish browser-format negotiation.

This single-URL example also does not implement responsive candidate selection. The application supplies responsive markup and loading behavior. Responsive images from one source with Vyso explains how to expose candidate URLs to the browser.

Keep the CMS and add an asset reference

In a CMS-backed site, the content record can retain its existing purpose:

CMS entry
├── title
├── body
└── selected image reference → Vyso source key

The frontend reads that reference and constructs the representation URL for the placement. Some CMS fields accept a URL; others expect a provider-specific media object. In the latter case, an application-defined field or adapter may be needed. Do not assume a native Vyso asset picker is already available.

During a pilot, a rendering helper can use the Vyso reference when present and retain the existing media renderer for records without it. This lets migrated and unmigrated content coexist. The helper is application code, not an official Vyso component or automatic migration feature.

A reusable role can also map to a saved delivery preset. After creating a preset with the illustrative slug article-hero, its URL would be:

https://cdn.vyso.io/preset/article-hero/ASSET_ID.jpg

Store asset identity separately from the presentation role where that fits the content model. A preset can keep a repeated recipe out of many individual content records. Its configuration still needs testing when it changes.

A staged rollout for an existing blog

Consider a blog whose headless CMS currently stores uploaded-image references and whose frontend renders them. A contained pilot can follow this sequence:

1. Select one article image and retain its existing source and CMS reference.
2. Upload the authoritative source to Vyso and record its returned asset key.
3. Add the Vyso reference to that article's content record. Choose a direct transformation recipe or a preset for the image role.
4. Update the rendering helper to use that reference for the selected entry, while retaining the existing path for other entries.
5. Publish and verify the page. Then make the same upload-and-selection process available for new articles.
6. Move useful historical article images in later batches, with a record of which placements changed.

At this stage, new articles can use Vyso while older articles keep their existing media. Editors continue publishing through the CMS. A later decision to migrate more assets can use evidence from the pilot, including whether the workflow is understandable and whether references remain easy to maintain.

Check the website's media boundary

Ordinary HTTPS APIs and image URLs make this model usable alongside many web stacks. Compatibility still depends on the site's media configuration.

A Content Security Policy must permit the CDN image source under its applicable image policy. MDN documents the img-src directive. Framework image components can impose additional requirements; for example, Next.js documents allowed external sources through remotePatterns. Test the component actually used by the site.

Vyso stores the selected sources and generates requested image representations. The application still owns layout, alt text, responsive markup, page publishing and the decision about which placements move. Search and library management belong in the editor or management workflow; a visitor does not need a management API call to render a known image URL.

Prioritize the historical library

Inventory what the website actually uses before copying a historical media archive. Start with active placements, reusable sources and images needed by new content. Dormant exports can be assessed separately.

Keep a mapping from the old media reference to the Vyso source key and the placements being updated. One image may appear in several entries, templates or CSS backgrounds. Moving one reference does not update the others automatically.

Do not copy every resized export merely because it exists. A delivery recipe can reproduce some technical variants from one source. A retouched campaign image or independently edited composition may deserve its own asset. Preserve meaningful creative versions and assess redundant exports without making deletion part of the pilot.

A larger migration becomes worthwhile when maintaining two upload workflows causes repeated mistakes, or when most active placements already depend on the new library. It then needs an explicit inventory, reference mapping and verification process. A storage connection alone should not be treated as proof that old assets and website references have been migrated.

Test the placement and keep rollback available

Preserve the previous media reference during testing where appropriate. If the selected placement fails, restore that reference through the site's normal content or deployment process. Rollback here is an application strategy, not a Vyso version-control feature.

Before expanding the rollout, verify:

• The uploaded source is the intended asset, and the delivery URL returns the expected image and content type.
• The crop, dimensions and visual quality work in the actual page layout.
• Responsive behavior, alt text and loading priority still match the placement.
• The image loads through the site's security policy and rendering component.
• Editors can select and publish the asset, and the previous reference can be restored.

Measure transferred bytes and page behavior rather than assuming the new host improves performance. Use the image quality and web performance workflow for those decisions.

Reuse stable delivery URLs for unchanged representations. Source or preset changes need cache and rollout consideration; How Vyso image delivery and CDN caching work covers that lifecycle. Keep the old source available until the placements using it have been accounted for and the rollback window has ended.