Unclear step in Nuxt bridge migration guide
So there is this page: https://nuxt.com/docs/4.x/bridge/configuration#migration-of-each-option
And at the bottom there is this section:
What does it mean? Are those examples of migrating specific options? If yes, which option exactly?
Or are they mandatory? Then why aren't they mentioned on a previous page. I'm so confused.
When I should change those. Right after installing nuxt bridge or at any point after enabling certain bridge option?
8 Replies
Hi @Gumaa. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
You're correct that the section you referenced shows examples of how to migrate specific configuration options from Nuxt 2 to the new format used by Nuxt Bridge and Nuxt 3. These are not mandatory changes for every project, but rather examples of how to update your config if you were using those specific options.
What does it mean?
- The guide is showing how to migrate the following Nuxt 2 options:
-
You only need to make these changes if you were using those options in your Nuxt 2 config. That's why they're not mentioned as a required step on the main migration overview—they're only relevant if you used those features. When should you change these? - You should update these options as part of your migration to Nuxt Bridge, after installing and enabling Nuxt Bridge, and as you update your
- There is no need to wait for a specific bridge feature to be enabled; these are general config migrations to align with the new schema. Summary - These are examples of migrating specific options (
Nuxt Bridge Configuration Migration ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
router.base → now becomes app.baseURL
- build.publicPath → now becomes app.cdnURL
So, if your Nuxt 2 project used router.base or build.publicPath in nuxt.config, you should update them to the new format as shown. If you didn't use these options, you don't need to add them.
Are these changes mandatory?
- No, they are not mandatory for every project.You only need to make these changes if you were using those options in your Nuxt 2 config. That's why they're not mentioned as a required step on the main migration overview—they're only relevant if you used those features. When should you change these? - You should update these options as part of your migration to Nuxt Bridge, after installing and enabling Nuxt Bridge, and as you update your
nuxt.config to be compatible with the new format.- There is no need to wait for a specific bridge feature to be enabled; these are general config migrations to align with the new schema. Summary - These are examples of migrating specific options (
router.base and build.publicPath) to their new equivalents.
- Only update them if you used those options in your Nuxt 2 config.
- Do this as part of your config migration after installing Nuxt Bridge, not before.
You can see the migration examples directly in the Nuxt Bridge configuration migration guide and further details about the new app config options in the Nuxt config API docs.
If you need more details on when to migrate other options, the migration guides recommend updating your config to the new format as you enable Bridge and prepare for Nuxt 3 compatibility, but only for the options you actually use in your project.Nuxt Bridge Configuration Migration ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
<@453886256506601474> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai so which bridge option is corresponding to those changes?
Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on the knowledge sources, there is no specific Bridge option that directly corresponds to the migration of
router.base to app.baseURL or build.publicPath to app.cdnURL. These changes are part of the general configuration migration when updating your nuxt.config to be compatible with Nuxt Bridge and Nuxt 3.
The documentation simply states that you should update these options in your config if you were using them, but it does not mention that you need to enable a particular Bridge feature flag for these changes. The migration is about aligning your configuration with the new schema, not about toggling a specific Bridge option. You can make these changes after installing and enabling Nuxt Bridge, as part of your config migration process Nuxt Bridge Configuration.
If you were using:
- router.base, migrate it to app.baseURL
- build.publicPath, migrate it to app.cdnURL
No additional Bridge option needs to be enabled for these specific config changes.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@453886256506601474> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai So if I only did steps here: https://nuxt.com/docs/4.x/bridge/overview there is no need to change those?
But before I renamed nuxt.config and added defineNuxtConfig then I need to change those?
Nuxt
Migrate to Nuxt Bridge: Overview v4
Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.
Let me check the knowledge base for you again. One moment! :books:
----------------------
If you only follow the initial steps on the Nuxt Bridge overview page—such as installing Nuxt Bridge and updating your scripts—there is no immediate need to change
router.base or build.publicPath in your config. These changes are only necessary if you proceed to update your nuxt.config to use the new defineNuxtConfig format, as recommended for Nuxt Bridge and Nuxt 3 compatibility.
In summary:
- If you keep your old nuxt.config format (without defineNuxtConfig), you can leave router.base and build.publicPath as they are.
- If you rename your config to nuxt.config.ts and start using defineNuxtConfig, then you should migrate:
- router.base → app.baseURL
- build.publicPath → app.cdnURL
This is because the new config schema expects these options under the app key, not under router or build anymore Nuxt Bridge Configuration Migration.
If the documentation does not mention a required change, it is not mandatory unless you update to the new config format.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@453886256506601474> Kapa.ai is still learning and improving, please let me know how I did by reacting below.