feat: add sharp file transformer with dynamic image resizing - #18411
Merged
paulpopus merged 10 commits intoOct 5, 2026
Merged
Conversation
r1tsuu
changed the title
Contributor
📦 esbuild Bundle Analysis for payloadThis analysis was generated by esbuild-bundle-analyzer. 🤖
Largest pathsThese visualization shows top 20 largest paths in the bundle.Meta file: packages/next/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_index.json, Out file: esbuild/index.js
Meta file: packages/payload/meta_shared.json, Out file: esbuild/exports/shared.js
Meta file: packages/richtext-lexical/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_client.json, Out file: esbuild/exports/client_optimized/index.js
Meta file: packages/ui/meta_shared.json, Out file: esbuild/exports/shared_optimized/index.js
DetailsNext to the size is how much the size has increased or decreased compared with the base branch of this PR.
|
paulpopus
requested changes
Sep 30, 2026
…s-sharp # Conflicts: # pnpm-lock.yaml
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub. |
paulpopus
requested changes
Oct 2, 2026
paulpopus
left a comment
paulpopus
left a comment
Member
There was a problem hiding this comment.
There's also the question of downgraded pnpm lock file dependencies vs main but lets fix that in the base PR right before it goes back to main to ensure it catches all instances properly
| @@ -0,0 +1,69 @@ | |||
| { | |||
| "name": "@payloadcms/transformer-sharp", | |||
Member
There was a problem hiding this comment.
@payloadcms/transformer-sharp is absent from packagePublishList. The release tool will not update its version or publish it. Add transformer-sharp after payload and add a completeness test for public packages.
| "lint:fix": "eslint . --fix" | ||
| }, | ||
| "dependencies": { | ||
| "file-type": "22.0.1", |
Member
There was a problem hiding this comment.
file-type and sanitize-filename are not imported by this package. Remove both dependencies and regenerate the lockfile.
r1tsuu
force-pushed
the
feat/file-transformers-sharp
branch
from
October 5, 2026 10:54
b91074d to
8563a75
Compare
paulpopus
approved these changes
Oct 5, 2026
paulpopus
pushed a commit
that referenced
this pull request
Oct 5, 2026
> [!NOTE] > Part 2 of 3 in a stacked PR. See #17827 for the full description, breaking changes and migration. > 1. #17827 — tests, fixtures, test configuration and generated test types > 2. **This PR** — Payload core, storage adapters, codemod, templates and documentation > 3. #18411 — `@payloadcms/transformer-sharp`, its README, workspace registration and lockfile ## Scope - `payload`: `upload.transformers` pipeline, dynamic file requests behind `access.read` / `req.fileTransform`, `generatePayloadFileURL`, removal of the built-in Sharp processing and Sharp-specific config/types - `@payloadcms/ui`: upload and file manager updates - Storage adapters and `plugin-cloud-storage`: internal `transform` file-handler operation - `@payloadcms/codemod`: `migrate-sharp-to-transformer` - `create-payload-app` and templates: migrated to `sharpTransformer` - Docs: `upload/transformers.mdx`, upload and storage adapter docs, v4 migration guide
paulpopus
added a commit
that referenced
this pull request
Oct 5, 2026
> [!NOTE] > Stacked on #18411. Draft. ### What? Upload documents now store generated image sizes under `variants` instead of `sizes`, matching the `variants` config option. ```diff - doc.sizes?.thumbnail?.url + doc.variants?.thumbnail?.url ``` ### How? - Renames the stored field and every place that reads or queries it, across core, the admin UI, the storage plugins, tests, templates and docs. - Adds a `sizes-to-variants` migration for each database adapter (MongoDB, Postgres, Vercel Postgres, SQLite, D1): `payload migrate:create --file @payloadcms/db-<adapter>/sizes-to-variants`. On SQL databases it renames the columns in place, so no data is lost. - Stops the predefined migration before it changes data or indexes when legacy `sizes` storage conflicts with custom `variants` storage. - Escapes custom SQL identifiers, makes SQLite index replacement safe to retry, and preserves and validates MongoDB index definitions, including partial filters and text-index weights. - Fixes the `db-postgres` and `db-vercel-postgres` builds, which shipped `migration-utils` importing a predefined-migration helper that was only published as `.mjs`, so importing `@payloadcms/db-postgres/migration-utils` failed. ### Breaking changes Payload 4 uses `variants` as the top-level field for generated upload variants. An upload collection can already define a custom field with this name. If a collection has a custom `variants` field, rename it before running the predefined migration: 1. Choose a new field name, such as `customVariants`. 2. Update the collection config to use the new name. 3. Write a custom migration that moves the existing custom data from `variants` to the new field. 4. Run the predefined `sizes-to-variants` migration after the custom data has moved. 5. Start Payload 4 only after both migrations succeed. The predefined migration cannot choose a name or merge custom `variants` data because Payload cannot determine the intended schema. It checks MongoDB documents, SQL columns, and SQL snapshots for conflicts and reports what must be moved before it can continue. A partly completed migration that contains only expected generated variant fields remains safe to retry. ### Testing - `test/sizes-to-variants` covers the migration on MongoDB, SQLite and Postgres, including camelCase variant names and running inside a transaction, the way `payload migrate` does. - Regression coverage includes custom `variants` collisions, quoted SQL identifiers, SQLite retry and rerun behaviour, MongoDB partial filters and index options, text indexes, and incompatible destination indexes. - End to end on blank projects outside the monorepo, upgrading a real Payload 3.90.2 project to this branch's packed packages: 1. Set up and seed with 3.x (`sharp` + `imageSizes`), using migrations for SQL. 2. Upgrade and run the `migrate-sharp-to-transformer` codemod. 3. Run the `sizes-to-variants` migration. 4. For SQL, generate a plain v4 migration and check it creates v4's new tables without dropping any `sizes`/`variants` columns. 5. Compare every stored size before and after, run runtime checks, then roll back with `migrate:down`, migrate up again and compare. | | Postgres | SQLite | MongoDB | | ------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Config | drafts + localization, camelCase/webp sizes, custom `dbName`, a collection without sizes, upload relationship | versions without drafts, crop/focal point, `generateImageName`, upload in an array, `hasMany` upload | drafts + 3 locales, `generateImageName`, avif size, upload in a block, polymorphic `hasMany` upload | | Documents and versions compared | 15 | 10 | 16 | Runtime checks after the upgrade cover `where` and `select` on `variants.*`, generated files on disk, and new uploads. Index names match the v4 schema. ### Notes - The `templates/with-vercel-website` initial migration still creates `sizes_*` columns and needs regenerating. Written with AI --------- Co-authored-by: Paul Popus <paul@payloadcms.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Part 3 of 3 in a stacked PR. See #17827 for the full description, breaking changes and migration.
@payloadcms/transformer-sharp, its README, workspace registration and lockfileThis is the top of the stack, where CI is expected to pass.
Scope
@payloadcms/transformer-sharppackage and README: upload-time processing (variants, crop, focal point, format/trim/resize options, metadata) and opt-in dynamic resizingpayload(getImageResizeAction,sanitizeResizeConfig,optionallyAppendMetadata)build:transformer-sharpscript, roottsconfig.jsonreferencesharpremoved frompayload, bumped0.32.6→0.35.4; lockfile