Skip to content

docs: add comprehensive guide for Next.js 16 + Cloudflare (OpenNext) integration#368

Closed
lora-sys wants to merge 4 commits intoaymericzip:mainfrom
lora-sys:docs/cloudflare-opennext-guide
Closed

docs: add comprehensive guide for Next.js 16 + Cloudflare (OpenNext) integration#368
lora-sys wants to merge 4 commits intoaymericzip:mainfrom
lora-sys:docs/cloudflare-opennext-guide

Conversation

@lora-sys
Copy link
Copy Markdown
Contributor

📝 Summary

This PR introduces a detailed deployment guide for using Intlayer with Next.js 16 (App Router) on Cloudflare Workers via the OpenNext adapter. It addresses critical configurations required for Edge Runtime compatibility and React 19 hydration stability.

✨ Key Changes

  • New Documentation: Added cloudflare-opennext.md (in both English and Chinese) covering:

    • Optimized middleware.ts matcher to reduce Edge Runtime overhead.
    • Correct nesting of IntlayerClientProvider with ThemeProvider for React 19.
    • Simplified wrangler.jsonc and build scripts to bypass mandatory R2 requirements.
  • Website Integration: Updated docData.content.ts and home/index.md to include the new section in the navigation tree.

🚀 Reference Implementation

Successfully tested in a production-ready environment:

  • Repo: lora-website
  • Stack: Next.js 16.1.1, React 19, Intlayer 7.x, Cloudflare Workers.

💡 Future Suggestions (RFC)

  1. Type Inference: Improve useIntlayer types to reduce manual .value access.
  2. CLI Scaffolding: Add npx intlayer scan to auto-generate content templates.

Branch: docs/cloudflare-opennext-guide

@lora-sys
Copy link
Copy Markdown
Contributor Author

lora-sys commented Jan 18, 2026

Hi, I see the CI failed with an error in @intlayer/chokidar related to @intlayer/vue-transformer.
I've double-checked my changes, and I only touched the documentation, AI embeddings, and tests within @intlayer/design-system. This packageEntryFailure seems to be a pre-existing issue in the current main branch or a build order issue in the Monorepo, as it's unrelated to my modifications.
My local tests for @intlayer/design-system are all passing. Could you please check if the main branch is currently stable?

@aymericzip
Copy link
Copy Markdown
Owner

aymericzip commented Jan 18, 2026

hey @lora-sys

Thank you so much for this doc submission!

However, I will probably not merge it.

Here's why:

  • Cloudflare deployment are too specific element to be listed on docs/docs/en/index.md
  • the points in ## 4. Known Issues & Tips are also potentially incorrect. I do not think that ThemeProvider and IntlayerClientProvider order has an importance. And the version of next-intlayer seems to also be a generic issue, as is not directly related to that Cloudflare focusing doc.
  • in nextjs 16, middleware.ts got replaced by proxy.ts
  • I would rather create another doc doc/deployment/cloudflare with generic instructions for Cloudflare, that can explain that process for all frameworks (next/vite) etc

@lora-sys
Copy link
Copy Markdown
Contributor Author

OK, thanks for the review!

@lora-sys lora-sys closed this Jan 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants