ipx runtime config documentation is misleading, not actually possible to provide list of domains at runtime
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.5k
- Forks
- 331
- Avg merge
- 19h 52m
- Merged PRs (30d)
- 9
Description
#1738 added this documentation:
The example says "You can update the options at runtime by passing the appropriate environment variable." and then it shows the actual usage of environment variables, but this is build-time usage, not run-time.
This code is a misleading antipattern. It misleads a user that they can refer to process.env in nuxt.config.ts and this will effective in runtime, which is not so. Whatever references to process.env are there in defineNuxtConfig, they are resolved during build time, and then literally imprinted to the output code:
https://github.com/nuxt/image/blob/5d983d8487f9d48eb3e0092eca62714336626a2e/src/module.ts#L159-L165
While NUXT_IPX_HTTP_DOMAINS indeed has runtime effect on the server ipx configuration, it is not happening because of reference to process.env.NUXT_IPX_HTTP_DOMAINS in the code above. It is caused by useRuntimeConfig().ipx inside routes/_ipx.ts.
Then, contrary to what the documentation implies, it is not possible to provide the list of domains at runtime with an environment variable.
The list of domains in resolveImage is taken from ctx.options:
which is directly passed from image-options.mjs which is generated at build time and does not use the runtime config:
Luckily, the options object is exposed by useImage() and one can fiddle with it in a plugin:
export default defineNuxtPlugin(async () => {
// Make `<nuxt-img>` use runtime list of domains.
// This relies on the respective server plugin that injects the data into Nuxt payload.
useImage().options.domains = useNuxtApp().payload.imageDomains
})
What I propose is:
- At the very least, update the documentation and remove misleading use of
process.envindefineNuxtConfig():
- domains: process.env.NUXT_IPX_HTTP_DOMAINS,
+ domains: [], // Set in run-time with NUXT_IPX_HTTP_DOMAINS
- Actually add a way to provide runtime environment variables (make them public and thus accessible client-side).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with docs/content/3.providers/ipx.md and compare its runtime configuration example with src/module.ts, src/runtime/routes/_ipx.ts, src/runtime/image.ts, and src/runtime/composables.ts. Trace which values are build-time versus runtime, then determine the documented behavior and scope for exposing the runtime domain list. Done means the documentation is accurate and the proposed runtime configuration behavior is clearly supported or explicitly scoped.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- nuxt, typescript
- Domain
- documentation, frontend
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100