nuxt / nuxt/image

ipx runtime config documentation is misleading, not actually possible to provide list of domains at runtime

Open
#2,088 0 comments 2 reactions 0 assignees View on GitHub

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:

https://github.com/nuxt/image/blob/5d983d8487f9d48eb3e0092eca62714336626a2e/docs/content/3.providers/ipx.md#L28-L40

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:

https://github.com/nuxt/image/blob/5d983d8487f9d48eb3e0092eca62714336626a2e/src/runtime/image.ts#L82-L91

which is directly passed from image-options.mjs which is generated at build time and does not use the runtime config:

https://github.com/nuxt/image/blob/5d983d8487f9d48eb3e0092eca62714336626a2e/src/runtime/composables.ts#L5-L13

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:

  1. At the very least, update the documentation and remove misleading use of process.env in defineNuxtConfig():
- domains: process.env.NUXT_IPX_HTTP_DOMAINS,
+ domains: [], // Set in run-time with NUXT_IPX_HTTP_DOMAINS
  1. Actually add a way to provide runtime environment variables (make them public and thus accessible client-side).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.