Preparing a Next.js app so static export succeeds first time
Next.js App or Pages Router
Next.js converts best in static export mode. Server features must be removed or replaced with static content first.
Quick answer
Upload the Next.js source ZIP or GitHub URL — the engine runs a static export pass and converts every rendered route into a WordPress template.
Where do I find the ZIP?
- Open your Next.js project folder or repository
- Exclude node_modules and .next
- Zip the project with package.json and next.config.js in the root
- Or paste the GitHub repository URL
What your upload should contain
package.jsonnext.config.jsapp/ or pages/public/styles or Tailwind config
Next.js troubleshooting
output: export fails
The patch layer applies static export automatically and removes API routes and middleware that block it.
Dynamic segments missing
Provide generateStaticParams or getStaticPaths so the routes can be pre-rendered.
Fonts flash or fall back
next/font files are copied locally; self-host fonts to avoid CDN dependencies.
Best practices before exporting
- Use output: 'export' for a fully pre-rendered site
- Add generateStaticParams to every dynamic route
- Disable image optimisation for static export
- Remove middleware and API routes
How to export
Method 1 — Static export out/ folder (best result)
- Set output: 'export' in next.config
- Run npm run build
- Zip the out/ folder
- Upload the ZIP
Method 2 — Source project ZIP
- Delete node_modules and .next
- Zip the project root
- Upload it — the sandbox applies the export patch automatically
Method 3 — GitHub repository
- Push the project to GitHub
- Copy the repository URL
- Paste it into the converter
Accepted input
- ZIP archive
- GitHub repository
- Static export
- Source project
- Build output
Not recommended
- Old build folders from a previous version of the project
- Incomplete exports that are missing package.json or index.html
- Screenshots, Figma files, PSD files or design mockups
- node_modules — always exclude it, it makes uploads slow and adds nothing
Supported features
- App Router and Pages Router pages
- Static generation
- Tailwind and CSS modules
- Metadata API
- Static images
Unsupported features
- Server actions
- API routes
- Middleware
- ISR and streaming
Common mistakes
- Leaving API routes and middleware in place
- Dynamic routes without generateStaticParams
- Relying on runtime environment variables
Conversion tips
- Test the export locally with npx serve out before uploading
- Keep the route count reasonable — very large sites take longer to render
Readiness checklist
- Navigation — Use real anchor links with readable labels. Menus built purely from JavaScript state are harder to map to WordPress menu locations.
- Images — Reference images from your project folder (imports or /public). Images loaded from a temporary preview host may not be reachable at conversion time.
- Assets — Fonts, icons and CSS should live inside the project. Locally hosted assets are copied into the theme automatically.
- Forms — Standard form markup is converted to Contact Form 7 or WPForms. Custom JavaScript submit handlers are replaced by the WordPress form handler.
- Routing — Every route you want as a WordPress page must be reachable from the navigation, a sitemap or a route manifest.
- Animations — CSS animations and common libraries survive. Heavy scroll-timeline or canvas effects may render differently in WordPress.
- SEO — Titles, meta descriptions and canonical tags are extracted per page and mapped into the theme and your SEO plugin.
- Responsive — Breakpoints are preserved as-is. Check mobile before exporting — the converter never fixes a layout that was already broken.
Next.js FAQ
Can I upload build output?
Yes — the out/ folder from a static export is the highest-fidelity input.
What about server actions?
They cannot run in WordPress. Replace them with a WordPress form plugin or a custom endpoint.
App Router or Pages Router?
Both are supported.
Are API routes converted?
No. They are removed before the static export; rebuild them as WordPress endpoints or plugins.
Does ISR or SSR convert?
Pages are captured as rendered HTML at conversion time; live server rendering is not part of a static theme.
Do I need to install anything to convert a Next.js project?
No. Everything runs server-side. You upload a ZIP or paste a repository URL and receive a WordPress theme ZIP plus a live preview in the browser.
Should I remove node_modules before uploading?
Yes, always. node_modules is reinstalled during conversion, so including it only makes the upload slow and can push you over the size limit.
Can I preview the result before paying?
Yes. The WordPress preview is free for every conversion. Payment is only required when you download the theme ZIP.
What happens to my forms?
Standard HTML form markup is mapped to Contact Form 7 or WPForms shortcodes. Custom JavaScript submit handlers are replaced by the WordPress form handler.
Will my SEO titles and meta descriptions survive?
Yes. Titles, meta descriptions and canonical tags are extracted per page and written into the theme templates so your SEO plugin can take over.