Common Framer to Next.js conversion issues and how to fix them

Most problems when converting a Framer site to Next.js with Deframer fall into five groups: the site can't be read (it isn't a published Framer site), the conversion doesn't fit (too large or too slow, usually fixed by turning "Include assets locally" off), the result page lists notices that need a follow-up in the code, the download stays locked (your verification code isn't on the live page), or the Next.js App Router project shows build errors or hydration warnings on your machine. This guide goes through each one, what it means and what to do.

Deframer is an independent tool and isn't affiliated with Framer; everything below concerns the converted project, not your Framer account, which Deframer never touches.

Before the conversion starts

"Not a published Framer site"

Deframer checks the page for Framer's generator tag or its site bundle. If neither is there, there is nothing to convert. Check:

1. You pasted the published address, what visitors open (yoursite.framer.website, yoursite.framer.app or your custom domain), not the editor link (framer.com/projects/…).
2. The site is actually published. Open the address in a private browser window and confirm it loads.

Rate limits and queueing

You can start up to 5 conversions per 10 minutes, with up to 2 running at once. When the service is busy, your conversion waits in line and shows its place. The limits section of the FAQ lists the current defaults.

During the conversion

The site is too large, or the conversion took too long

A conversion can run for up to 10 minutes and produce a project of up to 1 GB. Image- and video-heavy sites with "Include assets locally" turned on are the usual cause of hitting either limit, because every asset and every responsive variant is downloaded into public/.

What to do:

1. Retry with "Include assets locally" off. Assets stay on Framer's CDN, the download is smaller and the conversion faster. See CDN vs. local assets for the trade-offs.
2. Don't worry about credits. Converting is free, so a conversion that fails or is interrupted costs nothing.

Notices on the result page

The result page lists notices about the conversion. They aren't failures; they tell you where to look. The common ones:

For a missing redirect, Next.js 16 expects this shape in next.config.ts:

async redirects() {
  return [{ source: "/old-work", destination: "/projects", permanent: true }];
},

If the project already has a redirects() list, add the entry to it rather than declaring a second one. SEO when moving off Framer covers redirects and metadata in more detail.

Before you download

The verification code isn't found

Converting doesn't need it, but the download stays locked until your code is on the live page, and no credit is used until it's found. Work through these in order:

1. Copy the whole tag: <meta name="deframer-verification" content="dfv_…">, with all 24 characters after dfv_.
2. Paste it in Site Settings → Custom Code, at the end of the <head> (the body works too).
3. Publish. Saving in the editor isn't enough; the code has to be on the published page.
4. Click Check again. If you just published, give it a moment and try again.

The code is checked before each new project is downloaded, so if someone removed it, further downloads of that site's projects stop until it's back. Verifying Framer site ownership covers checking the right domain, agencies and removing the tag afterwards.

Build errors

npm install fails

1. Check Node.js. Next.js 16 needs Node.js 20.9 or later: node -v.
2. Look for "Packages not found on npm" in the notices, and set a published version in package.json.
3. Delete node_modules and try again with a clean install.

npm run build fails on types

If the site has Framer code components, next.config.ts sets typescript: { ignoreBuildErrors: true }, with a comment explaining why: that code was written in Framer's editor, which never type-checks it. Those projects build even when npx tsc --noEmit reports errors.

A project without code components builds with Next's type check on, so errors you introduce while editing will stop the build. Read the first error, fix it, and rebuild. Code components and overrides in Next.js explains how to tighten types gradually.

"Module not found"

Usually the same file as an "Imports that couldn't be resolved" notice. Open the file in the error, correct or remove the import, and rebuild. Code a site imports from other URLs is copied into src/vendor/, so look there before reinstalling anything.

Hydration warnings

A hydration warning means the HTML rendered on the server differs from what React rendered first in the browser. The converted project already handles the most common causes: browser-only components load after hydration (via next/dynamic, overrides via the kit's lazyOverride), and <html> and <body> accept attributes the site's own scripts may add before hydration.

If you still see one:

1. Rule out browser extensions. Reproduce in a private window with extensions off.
2. Compare dev and production. Run npm run build && npm run start; some warnings appear only in development.
3. Find the component named in the warning, and look for values that differ between server and browser during render: dates, random numbers, window or localStorage.
4. Move browser-only values into an effect, or load the component only in the browser from a client component:

"use client";
import dynamic from "next/dynamic";

const Clock = dynamic(() => import("@/components/clock"), { ssr: false });

Here @/components/clock stands in for your own component.

After you deploy

• Social images or canonical URLs point at the old domain. Update metadataBase in the root layout to your production domain.
• robots.txt and sitemap.xml show the old domain. They're copied as published; edit them in public/.
• Forms don't arrive. By default submissions are only logged. Set FORMS_WEBHOOK_URL or the form's own variable on your host, not just in .env.local.