feat(nuxt): add experimental View Transitions API support

[danielroe]

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This adds an experimental View Transitions API integration for Nuxt.

You can play around with the implementation in this sandbox or read more about the API.

ℹ Tips

If you are using Vue transitions to achieve the same result as View Transitions (yes, this is incredibly confusing), then you may wish to disable Vue transitions if the user's browser supports native View Transitions. You can do this by creating ~/middleware/disable-vue-transitions.global.ts with the following contents:

export default defineNuxtRouteMiddleware(to => {
  if (!document.startViewTransition) { return }

  // Disable built-in Vue transitions
  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})

🚨 Known issues

• View transitions may not work as expected with nested pages/layouts/async components owing to this upstream Vue bug: Nested components in detached branch render while being detached vuejs/core#5513. If you make use of this pattern, you may need to delay adopting this experimental feature or implement it yourself. Feedback is very welcome.
• If you perform data fetching within your page setup functions, that you may wish to reconsider using this feature for the moment. (By design, View Transitions completely freeze DOM updates whilst they are taking place.) We're looking at restrict the View Transition to the final moments before <Suspense> resolves, but in the interim you may want to consider carefully whether to adopt this feature if this describes you.

✅ TODO

I would very much welcome thoughts and improvements even at this stage, but expect that there's some considerable improvement to be made here. In particular, some avenues to explore:

• See if it's possible to call the route change within startViewTransition, so any errors can be caught there. (This results in a cleaner error handling story and is a nice-to-have but not essential objective.) We can listen to vue errors and throw the promise passed to startViewTransition.
• Consider whether to disable native Vue page transitions by default when this feature is enabled (setting app.pageTransition to false). Added instructions for how to do this manually, which feels like a better choice.
• See if we can restrict the transition to the final moments before <Suspense> resolves. The transition completely freezes DOM updates. We therefore don't want it pending while data fetching takes place, so ideally we only want to initiate the transition before the DOM is updated.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codesandbox]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[nuxt-studio]

✅ Live Preview ready!

Name	Edit	Preview	Latest Commit
Nuxt Docs	Edit on Studio ↗︎	View Live Preview	41ae229