Development & Preview
Daily development workflow and best practices for local development
Development modes
Next-Cloudflare-Turbo supports two development modes, each serving different purposes in your workflow.
Standard development uses the familiar next dev command with Hot Module Reloading (HMR). This is your primary development mode for building features, iterating on UI, and general application development.
The use of the initOpenNextCloudflareForDev() function in the next.config.ts provides mock Cloudflare bindings, allowing you to interact with D1 databases, R2 buckets, and other Cloudflare resources as if you were running in a Worker environment.
turbo run devWorker preview builds your application with the OpenNext adapter and runs it in the actual Workers runtime environment using wrangler dev. This is your final validation before deployment, though it requires rebuilding after each change.
npm run preview| Aspect | Standard development | Worker preview |
|---|---|---|
| Command | turbo run dev | npm run preview |
| Hot Module Reloading | Yes | No |
| Rebuild required | No | Yes |
| Runtime environment | Node.js with mocked bindings | Actual Workers runtime |
| Best for | Active development, UI iteration, rapid prototyping | Pre-deployment testing, runtime validation, debugging Worker-specific issues |
If your application previews successfully with npm run preview, it should deploy successfully to Cloudflare.
Development workflow
A typical development session would follow this pattern:
Start the dev server
turbo run devThis automatically starts all applications in the monorepo and builds/starts any dependencies that are required (like @nct/db)
app root. Remember to manually build or run dev for any dependencies.Develop the application
Make changes to the application. Hot module reloading will reflect changes in the browser instantaneously.
Test database changes
If you have modified the database schema:
npm run db:generateThen apply migrations locally:
npm run db:migrate:localPreview before deploying
Before deploying, validate everything works in the Workers runtime:
npm run previewTest critical functionality to ensure Worker compatability.
Deploy
Once preview succeeds, deploy to Cloudflare:
npm run deployTroubleshooting
Common error messages and issues are listed on the Issues & Errors page. For broader issues, the following steps may be helpful in debugging:
Preview not working correctly
When npm run preview fails or behaves unexpectedly, you can manually separate the build and preview steps to better identify where the problem occurs.
Build manually
npx opennextjs-cloudflare buildThis transforms your Next.js application into Worker-compatible code in the .open-next directory. If the build fails here, the error messages will help identify issues with your code or dependencies.
Preview with Wrangler
Once the build succeeds, preview using Wrangler directly:
npx wrangler devThis separates build-time errors from runtime errors, making it easier to diagnose issues.
If the build succeeds but preview fails, the issue is likely related to Worker-specific constraints like bundle size limits, incompatible packages, or runtime restrictions.
Clearing build caches
Sometimes stale caches can cause unexpected behaviour. The application has three different caches altogether:
- Next.js cache. This is the
.nextfolder which stores compiled pages, build artifacts, and cached data fetches - Turbo cache. This is the
.turbofolder which stores Turborepo's task execution cache. - Wrangler cache. This is the
.wranglerfolder which stores local development data for Cloudflare bindings; this includes D1 databases, KV namespaces and R2 buckets.
Removing .next and .turbo directories is safe and only costs you development speed. It's often a good first port-of-call if you suspect you have a stale cache problem.
You can safely delete the .wrangler folder, but you must be aware that this will delete your local instances of D1, KV, and R2. As a result, you will need to remember to re-apply migrations/seed locally before continuing with your application development.
To use the nuclear option of deleting all caches locally, from the project root, run:
# Stop any running development servers first
rm -rf .next .turbo .wranglerFAQs
How is this guide?
Last updated on