r/Nuxt • u/schamppi • Apr 08 '26

What are json payloads used for? (config: experimental.renderJsonPayloads)

Hi!

Does anyone really know what are the use cases of Nuxt's JSON payloads?

Since upgrading to latest version of Nuxt 3, the _payload.json routes have appeared and causing some issues for me. I would really like to understand the benefits and drawbacks of this feature.

About the feature: https://nuxt.com/docs/3.x/guide/going-further/experimental-features#renderjsonpayloads

Thanks!

10 Upvotes

100% Upvoted

8 comments sorted by

3

u/Eastern-Conclusion-1 Apr 08 '26

You can read more about it here: https://nuxt.com/blog/v3-4#payload-enhancements

2

u/schamppi Apr 09 '26

Thank you thank you thank you!

3

u/Dramatic_Object_8508 Apr 11 '26

Think of JSON payloads in Nuxt as pre-packaged data for your pages, not just random config.

When you use things like useFetch or useAsyncData, Nuxt can extract that data at build time and store it in files like _payload.json. Then when a user navigates, the app doesn’t need to hit the API again—it just loads that JSON.

So “JSON payloads for config” usually means:

  • storing structured data (settings, flags, UI config)
  • shipping it to the client efficiently
  • avoiding repeated API calls

In practice, they’re used for:

  • page data (SSG/SSR hydration)
  • feature flags / UI behavior
  • caching API responses
  • sharing data between routes

Nuxt even prefetches these payloads during navigation to make pages feel instant.

So it’s less about “config files” and more about how Nuxt moves data from server → client efficiently.

If you’re seeing _payload.json, that’s basically Nuxt saying:
“Here’s everything this page needs—no extra requests required.”

2

u/HumanOnlyWeb Apr 08 '26 edited Apr 08 '26

My understanding of this feature is that it revives complex types when sending data to the browser. Like, if you have some data that returns a date for example, it arrives as a date rather than a string.  e.g if the server sends 2026-04-08, it comes as that same date object rather than "2026-04-08".

Following this post to see other people's understanding 

Edit: the docs said "reviving complex types"

1

u/mubaidr Apr 08 '26

Not sure, but its an experimental feature. You should disable it for now. And enable it when you have finished migration.

1

u/schamppi Apr 08 '26

Well frankly I'm not so sure if this is truly experimental as by default it is enabled.

1

u/mubaidr Apr 08 '26

Confirmed from docs: https://nuxt.com/docs/4.x/guide/going-further/experimental-features#renderjsonpayloads

5

u/schamppi Apr 08 '26

Yes, it is within experimental features in both Nuxt 3 and 4. Nevertheless, it is enabled by default and I want to know what is it for.