fix!: allow overriding default format/screens/densities

[DamianGlowala]

🔗 Linked issue

resolves #1874
resolves #2020

📚 Description

This moves non-empty arrays and objects from defaults of defineNuxtModule to setup block, so that they are not affected by default merging behaviour.

[cloudflare-workers-and-pages]

Deploying nuxt-image with    Cloudflare Pages

Latest commit:	dac3aef
Status:	✅  Deploy successful!
Preview URL:	https://d28e7d62.nuxt-image.pages.dev
Branch Preview URL:	https://fix-module-options-overridin.nuxt-image.pages.dev

View logs

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/image@2138

commit: dac3aef

[coderabbitai]

📝 Walkthrough

Walkthrough

Defaults for array/object image options were moved from module-definition time to setup-time normalization. The explicit type assertion for domains was removed (domains: []). During setup, densities now defaults to [1, 2] when not provided, format is normalized to a deduplicated array with a default of ['webp'], and screens defaults to a Tailwind-like breakpoint map (sm, 750, md, lg, xl, 2xl) if absent. These defaults are ensured before further processing. No public API signatures were changed.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the fix by describing the relocation of non-empty arrays and objects from defaults to the setup block to address default merging behavior issues.
Linked Issues check	✅ Passed	The pull request successfully addresses both linked issues (#1874, #2020) by moving array/object defaults to the setup block, allowing users to fully override format, screens, and densities options without unwanted merging.
Out of Scope Changes check	✅ Passed	All code changes are directly related to the objectives: modifying module defaults for domains, densities, format, and screens, plus updating the playground configuration to demonstrate the new behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately captures the main change: allowing users to override default format/screens/densities options instead of having them merged.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/module-options-overriding

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@playground/nuxt.config.ts`:
- Line 19: The formats array in playground/nuxt.config.ts currently contains
both 'jpg' and 'jpeg' which are aliases and can cause inconsistent provider
behavior; update the formats array (the format entry used by the image provider
config) to use a single canonical value (prefer 'jpeg') or explicitly
document/justify keeping both if testing aliases, and ensure the chosen value
works with your targeted providers (notably hygraph which only accepts 'jpg').

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4cfca91 and 891d766.

📒 Files selected for processing (1)

• playground/nuxt.config.ts

[Chrissi2812]

Finally a fix for this 👍 This has been a blocker to upgrade to v2, for me.

But the options.screens would be nice if they still be merged by defu, and filtered via .filter(Boolean) so that we could write something like this:

export default defineNuxtConfig({
  image: {
    screens: {
      'sm': undefined,
      '3xl': 2000,
    }
  }
})

But that's just my opinion ^^

[danielroe]

this seems like a breaking change - if users were previously only adding a value this will be unexpected.

we likely need to defer this to the next major of nuxt/image