Skip to content

[routing-utils] Undeprecate routes#15010

Merged
MatthewStanciu merged 11 commits intomainfrom
matthew/add-src-etc-aliases
Feb 25, 2026
Merged

[routing-utils] Undeprecate routes#15010
MatthewStanciu merged 11 commits intomainfrom
matthew/add-src-etc-aliases

Conversation

@MatthewStanciu
Copy link
Copy Markdown
Contributor

@MatthewStanciu MatthewStanciu commented Feb 11, 2026

Some time ago, we deprecated the routes property and replaced it with new properties of its individual components: rewrites, redirects, headers. This made sense at the time. But then last year we added header transforms and made them only available on the deprecated routes in vercel.json.

THEN we built on top of this feature when we built vercel.ts by adding syntactic sugar that makes it easy to add transforms. This quickly caused some frustrating DX issues because we were abstracting away the vercel.json property where transforms lives but still compiling to vercel.json, which caused some confusing errors.

I normalized these in #14705, but that's just a band-aid. The real issue is that we're in this weird state where an important CDN feature can only be configured via a property in vercel.json/ts that your editor yells at you for using because it's "deprecated" and the only reason its replacements are not backwards-compatible is because have different names for source, destination, and statusCode.

@mknichel wrote a proposal for undeprecating routes here: Undeprecate routes in vercel.json

This PR implements part 1 of undeprecating routes:

  • removes deprecated in the schema
  • converts source, destination and statusCode to src, dest, and status
  • updates error messages & unit tests

Next steps will be implemented in follow-ups:

  • Deprecate handle, continue, override, important properties within routes
  • Remove mixed-routing-properties error; allow routes and headers / redirects / rewrites together
  • Update docs

Full stack

Smaller/loose ends:

Note

Low Risk Change

This PR removes the deprecated flag from the routes schema and adds property aliases (source/destination/statusCode) with corresponding validation and tests, which is a non-breaking schema change with no security implications.

  • Schema: removes deprecated: true from routesSchema, adds source/destination/statusCode aliases
  • Validation: adds convertRouteAliases function to normalize aliases to canonical forms with conflict detection
  • Tests: extensive unit test updates for new alias support and error messages

Risk assessment for commit 816ca41.

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Feb 11, 2026

🦋 Changeset detected

Latest commit: 816ca41

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

This PR includes changesets to release 4 packages
Name Type
@vercel/routing-utils Minor
@vercel/client Patch
@vercel/config Patch
@vercel/fs-detectors Patch

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

@MatthewStanciu MatthewStanciu changed the title [routing-utils] Add aliases for src, dest, and status to routes schema [routing-utils] Undeprecate routes Feb 11, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Feb 11, 2026

📦 CLI Tarball Ready

The Vercel CLI tarball for this PR is now available!

Quick Test

You can test this PR's CLI directly by running:

npx https://vercel-omp2yct0c.vercel.sh/tarballs/vercel.tgz --help

Use in vercel.json

To use this CLI version in your project builds, add to your vercel.json:

{
  "build": {
    "env": {
      "VERCEL_CLI_VERSION": "vercel@https://vercel-omp2yct0c.vercel.sh/tarballs/vercel.tgz"
    }
  }
}

Python Runtime Wheel

A vercel-runtime wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_RUNTIME_PYTHON="vercel-runtime @ https://vercel-omp2yct0c.vercel.sh/tarballs/vercel_runtime-0.6.0.dev1771985324+816ca41-py3-none-any.whl"

Python Workers Wheel

A vercel-workers wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_WORKERS_PYTHON="vercel-workers @ https://vercel-omp2yct0c.vercel.sh/tarballs/vercel_workers-0.1.0.dev1771985324+816ca41-py3-none-any.whl"

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Feb 11, 2026

🧪 Unit Test Strategy

Comparing: 4f9a1a3816ca41 (view diff)

Strategy: Affected packages only

✅ Only testing packages that have been modified or depend on modified packages.

Affected packages - 40 (100%)
  1. @vercel-internals/get-package-json
  2. @vercel/backends
  3. @vercel/build-utils
  4. @vercel/cervel
  5. @vercel/cli-auth
  6. @vercel/client
  7. @vercel/config
  8. @vercel/detect-agent
  9. @vercel/edge
  10. @vercel/elysia
  11. @vercel/error-utils
  12. @vercel/express
  13. @vercel/fastify
  14. @vercel/firewall
  15. @vercel/frameworks
  16. @vercel/fs-detectors
  17. @vercel/functions
  18. @vercel/gatsby-plugin-vercel-builder
  19. @vercel/go
  20. @vercel/h3
  21. @vercel/hono
  22. @vercel/hydrogen
  23. @vercel/koa
  24. @vercel/nestjs
  25. @vercel/next
  26. @vercel/node
  27. @vercel/oidc
  28. @vercel/oidc-aws-credentials-provider
  29. @vercel/python
  30. @vercel/python-analysis
  31. @vercel/redwood
  32. @vercel/related-projects
  33. @vercel/remix-builder
  34. @vercel/routing-utils
  35. @vercel/ruby
  36. @vercel/rust
  37. @vercel/static-build
  38. @vercel/static-config
  39. examples
  40. vercel

Results

  • Unit tests: Only affected packages will run unit tests
  • E2E tests: Running in parallel via E2E Tests workflow
  • Type checks: Only affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

this behavior used to be tested for when only "src" was required because
it would show up as an error slash in the output for assertError. but
when we changed it to anyOf it no longer tested for this behavior. so
this commit adds a new explicit test for this
@MatthewStanciu MatthewStanciu merged commit 0c961fc into main Feb 25, 2026
201 checks passed
@MatthewStanciu MatthewStanciu deleted the matthew/add-src-etc-aliases branch February 25, 2026 02:32
ricardo-agz pushed a commit that referenced this pull request Feb 25, 2026
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## vercel@50.24.0

### Minor Changes

- [dev] skip project setup for `vc dev` if `--local` or `-L` flag is
passed. ([#15239](#15239))

### Patch Changes

- feat(cli): add --format=json support to `integration add`
(auto-provision) ([#15250](#15250))

-   Updated dependencies \[]:
    -   @vercel/build-utils@13.5.0
    -   @vercel/next@4.15.34
    -   @vercel/redwood@2.4.9
    -   @vercel/rust@1.0.5
    -   @vercel/static-build@2.8.41

## @vercel/routing-utils@5.4.0

### Minor Changes

- Undeprecate `routes` schema and add aliases for `src`, `dest`, and
`status` ([#15010](#15010))

## @vercel/client@17.2.47

### Patch Changes

- Updated dependencies
\[[`0c961fce30d495620542066249dae447764d2eba`](0c961fc)]:
    -   @vercel/routing-utils@5.4.0
    -   @vercel/build-utils@13.5.0

## @vercel/config@0.0.34

### Patch Changes

- Undeprecate `routes` to match new routing-utils
([#15016](#15016))

- Updated dependencies
\[[`0c961fce30d495620542066249dae447764d2eba`](0c961fc)]:
    -   @vercel/routing-utils@5.4.0

## @vercel/fs-detectors@5.8.11

### Patch Changes

- [services] adds source information to detected services
([#15245](#15245))

- Updated dependencies
\[[`0c961fce30d495620542066249dae447764d2eba`](0c961fc)]:
    -   @vercel/routing-utils@5.4.0
    -   @vercel/frameworks@3.19.0


<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR is an automated Changesets release that only updates version
numbers in package.json files and CHANGELOG.md files, with no code logic
changes.
> 
> - Version bumps across 5 packages (vercel, client, config,
fs-detectors, routing-utils)
> - Deletes consumed changeset markdown files
> - Updates CHANGELOG.md files with release notes
>
> <sup>Risk assessment for [commit
987df11](https://github.com/vercel/vercel/commit/987df111fedc0eb57c982038befca199bbf7e6fe).</sup>
<!-- VADE_RISK_END -->

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
MatthewStanciu added a commit that referenced this pull request Feb 25, 2026
…rties in routes schema (#15015)

See #15010 for more context

<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR deprecates schema properties and updates error messages to
remove `handle` as a valid route option, which is a breaking API change
(marked as major version bump) but only adds deprecation warnings rather
than removing functionality.
> 
> - Error message updated to remove `handle` as valid route property
> - Added `deprecated: true` flags to `handle`, `important`, and
`override` in schema
> - Added JSDoc `@deprecated` comments to TypeScript types
>
> <sup>Risk assessment for [commit
f014d3d](https://github.com/vercel/vercel/commit/f014d3d180573de1754433fffeb17c218bd9aaac).</sup>
<!-- VADE_RISK_END -->

---------

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
MatthewStanciu added a commit that referenced this pull request Feb 25, 2026
…routes schema (#15014)

Follow-up to #15010. This is now
redundant after undeprecating `routes` and normalizing `source` and
`destination` to `src` and `dest`.

<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR removes typo suggestion mappings for routes schema, which is a
minor cleanup of error messaging with no impact on security, validation,
or business logic.
> 
> - Removes 'source' and 'destination' typo suggestions from routes
schema mapping
> - Changeset added for patch version bump
>
> <sup>Risk assessment for [commit
d3567cb](https://github.com/vercel/vercel/commit/d3567cb940a4a0086a6093ac3fc1abab0fc8793c).</sup>
<!-- VADE_RISK_END -->
MatthewStanciu added a commit that referenced this pull request Feb 25, 2026
… `cleanUrls`, and `trailingSlash` (#15020)

More context: #15010

<!-- VADE_RISK_START -->
> [!WARNING]
> High Risk Change
>
> Removes validation that previously prevented `routes` from coexisting
with other routing properties, loosening configuration constraints which
could affect routing behavior in production.
> 
> - Removes `invalid_mixed_routes` error check that blocked mixing
`routes` with `rewrites`, `headers`, etc.
> - Deletes integration test that validated the mixed routes error
> - Major version bump indicates breaking change to routing-utils
behavior
>
> <sup>Risk assessment for [commit
b202b0b](https://github.com/vercel/vercel/commit/b202b0b4bd292923eda142c65adec6a908842f58).</sup>
<!-- VADE_RISK_END -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants