feat!: migrate to esm only, unify exports, use pkg-utils for build, switch tests to Vitest by rdunk · Pull Request #84 · sanity-io/image-url

rdunk · 2025-08-29T11:44:41Z

To support signed URLs (the next PR upstack), I decided to add a specific signed version of the url builder available from a different export path /signed. This was to avoid bundling the crypto dependencies we rely on for signing, as this functionality will likely only be used by a very small subset of users.

I thought it would be a good time to "modernize" the repo a little to support that work. That included:

Replacing jest with vitest for tests
Replacing microbundle with @sanity/pkg-utils for building
Updating the TypeScript configuration to extend @sanity/pkg-utils strictest
Exporting all types defined in src/types.ts from the default export path

I’ve also added in a postbuild/prepack step which outputs some files for backwards compatibility. This is to support users who are currently importing types from paths like @sanity/image-url/lib/types/types.

changeset-bot · 2025-08-29T11:44:45Z

🦋 Changeset detected

Latest commit: 826e441

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sanity/image-url	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

rdunk · 2025-08-29T11:44:57Z

This stack of pull requests is managed by Graphite. Learn more about stacking.

socket-security · 2025-08-29T11:45:00Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@types/node@17.0.45 ⏵ 24.3.0	⁺¹		⁺¹
	typescript@4.9.5 ⏵ 5.9.2	⁺¹

View full report

…test

RitaDias · 2025-09-01T06:58:41Z

test/__snapshots__/builder.test.ts.snap

For a second I thought that the red & were them being removed on the updated version as was concerned 😅

RitaDias

This looks good to me though I would just want to have someone else that is a bit more knowledgeable on the config side of things double check that everything is good to go :)

rexxars

Thanks, this is great. I am wondering if it's time to just do a major version bump and break things?

There are imports to things like @sanity/image-url/lib/browser/builder on the internet, which will break with this change
Tempting to go ESM-only, Node.js >= 20 at this point. We list node >= 10 in the package, but also use @sanity/browserslist-config which says maintained node versions. These are not compatible with each other. Additionally, the dependencies introduced in the signed URL PR requires Node v20.19, so it would make sense to align here anyway.
Would love to use a named export instead of default export

rexxars · 2025-09-04T19:15:20Z

package.json

-    "index.js",
-    "urlForImage.js"
+    "src",
+    "build/compat-shims.mjs"


Don't think we need to ship this in the published npm module?

Ah thank you, good catch, build/compat-shims.mjs was a holdover from my first attempt at backwards compatibility (it doesn't actually exist anymore).

Would you prefer to remove src too?

Would you prefer to remove src too?

If the sourcemaps reference src I tend to include it, but also don't feel strongly about it.

Cool, they do, I'll include it.

rdunk · 2025-09-04T20:32:27Z

Thanks for taking a look @rexxars and for catching the node mismatches, I glossed over that.

I was trying to weigh up whether or not a major would be “worth it” without new features, but if you’re comfortable with that then it would definitely simplify things. Feels like it could be a bit of a pain to maintain full backwards compatibility, evidenced by my attempt to cover the types but not accounting for those browser imports.

Would we introduce a named export and keep/soft deprecate the default export to make things slightly less painful?

rexxars · 2025-09-04T22:16:37Z

Would we introduce a named export and keep/soft deprecate the default export to make things slightly less painful?

We could do that! Up to you :)

rdunk · 2025-09-09T11:14:44Z

I’ve added a follow up commit that makes breaking changes:

All default exports are replaced with named exports. I opted not to go for a a soft deprecation as it's unlikely we'll do another major of this package anytime soon, better to make the change cleanly I think. Is urlBuilder what we want to go with?
The CJS exports have been removed so the package will now build ESM only.

rexxars · 2025-09-17T18:29:25Z

Is urlBuilder what we want to go with?

I think createUrlBuilder or createImageUrlBuilder might be more descriptive? (mirrors createClient etc)

rdunk · 2025-09-17T21:08:28Z

I think createUrlBuilder or createImageUrlBuilder might be more descriptive? (mirrors createClient etc)

I very much agree. I prefer the former for terseness but the latter seems sensibly unambiguous and probably the safer option, so I've added a commit to refactor to that.

rexxars · 2025-09-19T16:01:21Z

Should likely add a MIGRATION.md or at least a note in the readme about how to migrate from the previous version, but we can do that as a separate PR 👍

rdunk · 2025-09-19T16:07:33Z

Absolutely, I assume I also need to add a changeset before merging.

I was planning on speaking to docs about this in advance of releasing too as there are a lot of references to @sanity/image-url around.

Thanks for the review 🙇.

rdunk · 2025-11-27T12:45:57Z

Merge activity

Nov 27, 12:45 PM UTC: A user started a stack merge that includes this pull request via Graphite.
Nov 27, 12:46 PM UTC: @rdunk merged this pull request with Graphite.

rdunk mentioned this pull request Aug 29, 2025

feat: support signed urls #85

Merged

rdunk force-pushed the 08-29-refactor_migrate_to_esm_use_pkg-utils_for_build_switch_tests_to_vitest branch from 05bed0c to e0fdb42 Compare August 29, 2025 14:43

refactor: migrate to esm, use pkg-utils for build, switch tests to Vi…

d2aec21

…test

rdunk force-pushed the 08-29-refactor_migrate_to_esm_use_pkg-utils_for_build_switch_tests_to_vitest branch from e0fdb42 to d2aec21 Compare August 29, 2025 16:06

rdunk marked this pull request as ready for review August 29, 2025 16:12

RitaDias requested review from RitaDias, rexxars and stipsan September 1, 2025 06:21

RitaDias reviewed Sep 1, 2025

View reviewed changes

stipsan approved these changes Sep 1, 2025

View reviewed changes

rexxars requested changes Sep 4, 2025

View reviewed changes

feat!: use named exports, build esm only

e2062d4

rdunk requested a review from rexxars September 12, 2025 08:39

refactor: urlBuilder to createImageUrlBuilder

db755bf

rexxars approved these changes Sep 19, 2025

View reviewed changes

rdunk mentioned this pull request Sep 23, 2025

docs: add v1 to v2 migration guide #86

Merged

rdunk changed the title ~~refactor: migrate to esm, use pkg-utils for build, switch tests to Vitest~~ feat!: migrate to esm only, unify exports, use pkg-utils for build, switch tests to Vitest Sep 23, 2025

chore: add changesets

826e441

rdunk force-pushed the 08-29-refactor_migrate_to_esm_use_pkg-utils_for_build_switch_tests_to_vitest branch from f80b5ba to 826e441 Compare September 23, 2025 13:11

rdunk mentioned this pull request Nov 20, 2025

feat: support media library urls #87

Merged

rdunk merged commit 440e082 into main Nov 27, 2025
7 checks passed

rdunk deleted the 08-29-refactor_migrate_to_esm_use_pkg-utils_for_build_switch_tests_to_vitest branch November 27, 2025 12:46

squiggler-legacy bot mentioned this pull request Nov 27, 2025

Version Packages #88

Merged

Conversation

rdunk commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

rdunk commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security bot commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RitaDias Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

RitaDias left a comment

Choose a reason for hiding this comment

Uh oh!

rexxars left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rexxars Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

rdunk Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

rexxars Sep 4, 2025

Choose a reason for hiding this comment

Uh oh!

rdunk Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

rdunk commented Sep 4, 2025

Uh oh!

rexxars commented Sep 4, 2025

Uh oh!

rdunk commented Sep 9, 2025

Uh oh!

rexxars commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rdunk commented Sep 17, 2025

Uh oh!

rexxars commented Sep 19, 2025

Uh oh!

rdunk commented Sep 19, 2025

Uh oh!

rdunk commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rdunk commented Aug 29, 2025 •

edited

Loading

changeset-bot bot commented Aug 29, 2025 •

edited

Loading

rdunk commented Aug 29, 2025 •

edited

Loading

socket-security bot commented Aug 29, 2025 •

edited

Loading

rexxars left a comment •

edited

Loading

rexxars commented Sep 17, 2025 •

edited

Loading

rdunk commented Nov 27, 2025 •

edited

Loading