Multiple inconsistent ways of defining a site url

[cyrilf]

Details

:one: Various .env variables names in the doc

On the site config Getting started page, in the Site Config Quick Setup block it mentions that we can use the following keys in the .env file:

NUXT_PUBLIC_SITE_URL=https://example.com
NUXT_PUBLIC_SITE_NAME=My Awesome Website

But if I open the guide setting site config / Environment specific site config (which I need, because I have local, preprod and prod environments) it says:

NUXT_SITE_URL=https://test.example.com
NUXT_SITE_NAME="STAGING SITE NAME"
NUXT_SITE_ENV="staging"

which is not the same keys.

So I'm wondering which one is the most recommended?

:two: Runtime config mapping to .env

On the Nuxt runtime config documentation they explicitly say that something like that in the .env:

NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org

will match this in the nuxt.config.ts file:

export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // can be overridden by NUXT_API_SECRET environment variable
    public: {
      apiBase: '', // can be overridden by NUXT_PUBLIC_API_BASE environment variable
    }
  },
})

so I'm wondering why your example refers to:

NUXT_PUBLIC_SITE_URL=https://example.com
NUXT_PUBLIC_SITE_NAME=My Awesome Website

for

export default defineNuxtConfig({
  site: {
    url: 'https://example.com',
    name: 'My Awesome Website' 
   }
})

shouldn't it be that instead:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      site: {
        url: 'https://example.com',
        name: 'My Awesome Website' 
      }
    }
   }
})

---

Thanks a lot for the clarifications! :ok_hand:

[cyrilf]

Ok, I think that digging in the code is a good way of finding an answer :wink: So I think that the answer lies somewhere in this file or this one

So both NUXT_SITE_ and NUXT_PUBLIC_SITE_ are supported in the .env. Do you recommend one of them? The runtimeConfig in nuxt.config.ts is mentioned as legacy though..

[harlan-zw]

Hi, this is a good question (sorry for the delay).

The number of ways you can configure site config is a relic of how previous module version majors wanted this config. I realize it's confusing and there are too many options.

The recommendation is not to use runtimeConfig, either use site.*, env keys without public NUXT_SITE_ or use the hooks. But it's honestly up to you, whatever works for your site is the recommendation.

I've tried to clean up the doc related to this so will close for now as not too sure what else I can do without further breaking changes.