CodePen Pen-to-Projects migration and embedded iframe cutover boundary

Answer the question first

When you replace a CodePen Pen embed with a CodePen Project, you must keep the following attributes and settings identical to avoid a layout shift:

• Iframe height – the height attribute on the <iframe> must match the rendered height of the Project output. Project embeds usually have a larger default wrapper, so copy the current height value from the Pen embed (e.g. height="300") and apply it to the Project embed.
• Iframe width – keep the same width or use width="100%" if the Pen already did so.
• Preprocessor configuration – any Sass, Less, TypeScript, Babel, or ES6 transpilation used in the Pen must be mirrored in the Project’s Settings → Settings → Preprocessors. The compiled CSS/JS output must be identical.
• External resource URLs – CDN links or custom scripts added to the Pen’s Settings → External Resources must be added to the Project’s Settings → External Resources and verified to load without CORS errors.
• Debug/preview mode – use the same mode in the embed URL: /embed/pen/ID?debug=1 for a Pen versus /embed/project/ID?debug=1 for a Project. This keeps the UI chrome minimal and the output size stable.

Supported cut‑over pattern

CodePen does not provide a native redirect from a Pen URL to a Project URL, so a zero‑downtime cut‑over is not possible. The practical pattern is:

1. Keep the original Pen embed live for all existing consumers.
2. Publish the Project and copy the new embed URL (/embed/project/ID).
3. Update the iframe src on all sites that host the embed (or use a small JavaScript proxy that rewrites the URL). You can also host the Project on your own domain and embed that, which gives you full control over the URL and height.
4. Once all consumers have switched, de‑publish or delete the old Pen.

Because the Project embed may render a slightly different wrapper, always test the new embed in a staging environment with the same height and width attributes before rolling out.

Does the plan matter?

• FREE account – Projects are not publicly embeddable. You would need to upgrade to Pro to use a Project embed. If you remain on Free, you must keep the Pen embed.
• PRO account – Projects can be embedded publicly. The same attribute preservation rules apply, but you have the option to host the Project on your own domain for more control.

One diagnostic detail that could change the recommendation

What is the current height value used on the Pen embed iframe? Knowing this exact value lets you set the same height on the Project embed and guarantees no layout shift.