Express v4 -> v5 Migration

[karlhorky]

Copied from my comment in the Release 5.0 PR:

Maybe I missed a v5 planning document somewhere - I'm looking for a few details to help determine how and when to migrate our projects:

1. When is it planned that [email protected] be published to the npm latest tag?
2. Is there a plan to publish an Express v4 -> v5 Migration Guide? (or a visible list of breaking changes with short suggestions about what to do about them) The closest thing that I can see is this small breaking note in History.md
3. What's the current plan for the TypeScript types in DefinitelyTyped @types/express and @types/express-serve-static-core? Does anything need to be changed here? Specifically, things like [@types/express-serve-static-core] 🏷️ Add Promise<void> to RequestHandler's return type DefinitelyTyped/DefinitelyTyped#69660 (comment) cc DT maintainers @borisyankov @samijaber @NatoBoram @bombillazo @AndrewLeedham @gabritto @sandersn

[UlisesGascon]

Thanks for creating this issue. I added a reference in the 5.x backlog expressjs/discussions#266 👍

[wesleytodd]

When is it planned that [email protected] be published to the npm latest tag?

We have not set a date yet. Largely it depends on how quickly we can get the docs and the rest of the ecosystem dependencies (like DT for example) updated. We also have an LTS proposal we are working on to better schedule this stuff in the future.

Is there a plan to publish an Express v4 -> v5 Migration Guide?

Yes, this is part of the docs we need to write.

What's the current plan for the TypeScript types in DefinitelyTyped

We would love to chat with the DT folks to get better at this in the future. We know it has lacked attention for too long, but we never had a lot of folks signing up and showing up to help us with this. If that is changing now I would love it, but we need more than just drive by help, we need folks who are here to help us get all the ~30 some packages we maintain all doing this consistently and well.

---

There are existing issues for all of this, I will edit this comment when I get a chance to add them, but wanted to get this written sooner rather than later.

[jonkoops]

We would love to chat with the DT folks to get better at this in the future. We know it has lacked attention for too long, but we never had a lot of folks signing up and showing up to help us with this. If that is changing now I would love it, but we need more than just drive by help, we need folks who are here to help us get all the ~30 some packages we maintain all doing this consistently and well.

Calling @borisyankov @CMUH @puneetar @dfrankland

[aredridel]

I might be able to help with type work

[wesleytodd]

@aredridel That would be awesome! I have been super busy keeping up with the chatter around the release while trying to spare some time for my paying job 😆, so I have not had a chance to pull in all the links to previous conversations around this, but most are in https://github.com/expressjs/discussions

[RobinTail]

The author of the original PR to DefinitelyTyped is sick.
I began my own approach here, but it's promising to be massive: dozens of packages have internal references to express' types, declaring * compatibility, having discrepancies in tests, such as returning something where void was expected. That did actually work with void before, but no longer works with void | Promise<void> and that is the issue, but not the only one — so that each package failing tests seems to be requiring an individual handling to fix it.

[RobinTail]

OK. I fixed all issues in my PR to types of Express 5 — DefinitelyTyped/DefinitelyTyped#70563
I welcome advises and suggestions on how to make it better and release faster.

[jonkoops]

@RobinTail perhaps it would be better to coordinate the efforts towards upstreaming the types here in the Express repo? And then subsequently to deprecate the @types/ package.

[RobinTail]

Perhaps, @jonkoops .
Did you already start doing that?
My job is finished meanwhile — everything is ready and needs only an approval to release the types for Express 5 via the established workflow.

[jonkoops]

I have not, but I would not mind taking this on. I see also @aredridel volunteered for this, so perhaps they already started working on it. Let me know, I could set up a PR where we can collaborate.

[RobinTail]

I have not
I would
I could

You know, in my system of values getting things done is more important and cherished rather than

• ruminating for 10 years
  • on how to arrange the seats
    • for a potential opportunity
      • to begin negotiations
        • on a proposed cooperation
          • in matters of shared responsibility
            • towards finding a suggested solution
              • to the elementary problem.

So, I have done it.
If you're having your own solution in mind, which perhaps you believe could be better than mine — don't hesitate and do it @jonkoops

[jonkoops]

I'd say get the PR merged for the the @types/ package, then we can simply copy them over later 🤷‍♂️

[RobinTail]

Exactly, @jonkoops !
Express always has been pure-JS repo, having no types. So that adding them is a brand new feature, requiring either:

• rewriting the code in Typescript with a consequential compilation;
• or keeping a manually written declaration in sync with that code.

Anyway, it's a new workflow to establish — it will take time and moreover, as a new feature, it will require a new version — 5.1.0 for example, while already now we have the opportunity to adjust the existing @types/express for supporting the already released version 5.0.0, enabling its availability for the community.

[jonkoops]

or keeping a manually written declaration in sync with that code.

This is already the case now, with the added complexity (for end users) of it being a separate package. The only downside of moving them in here would be that maintenance needs to happen in this repo, which is totally fine as long as it's taken into account going forward.

[RobinTail]

This is it

[targetlucked69]

@RobinTail, is this still the correct way to add additional properties to the request object in Express TypeScript?

declare global {
  namespace Express {
    export interface Request { // do I need export here
      someProperty: string
    }
  }
}

export {}

Also, is it compatible with @types/express v4 and v5? Thank you for all your hard work!

[RobinTail]

This part wasn't changed, @walmartwarlord . If that augmentation did work for v4, it should work for v5 as well.

[trivikr]

Migration guide to Express 5 https://expressjs.com/en/guide/migrating-5.html

[kasir-barati]

Irrelevant to some extend, but, any news on when v5 will become the default version on npm?

I read this issue: #4920

But the last comment there was stating 2023 and now we are entering 2025. I am not sure if this is normal.

[wesleytodd]

We have had a flurry of events and distractions among the TC members, primarily we have a few deadlines we have been focused on (the STF grant proposal and planning) which will be wrapped up soon. Luckily a lot of folks have been doing great work on the docs and other things we needed to get done, and so as soon as we have time to get back to this it will be the top priority. My guess is that we won't likely push the button on it until the new year to save folks from a lot of noise over the holidays. That said, we have not discussed it directly yet so I would love to hear others opinions.

[kasir-barati]

Just to fill you in as why I brought up this topic here is this "discussion" I had in @apollo/server GH repo regarding its integration with ExpressJS v5: apollographql/apollo-server#7994 (reply in thread)

[kamilmysliwiec]

@wesleytodd apologies for bugging you here, but I was wondering if you could give me a ballpark estimate for when v5 might become the default version. The reason I'm asking is that the NestJS v11 release is pretty much ready to go. However, I'd like to make Express v5 the default as part of the next major release.

If the Express team is thinking that a Q1 release is feasible, I'd consider postponing and waiting. On the other hand, if it's likely to take a few more months, I'll move forward with what we have now and include it in a future release instead.

Thanks in advance!

[wesleytodd]

No problem @kamilmysliwiec, happy to hear from you and your plans to udpate! We just discussed on the TC call today and we think we will be targeting early Jan for promoting to latest. That said, you should absolutely have NestJS depend on ^5.0.0 right now, it is stable and we have had increasing adoption and have all good signals, the only thing delaying us was the docs and lack of community prep after a 10 year stall out, nothing unstable about depending on the release now. The only thing that will change is what users get when they type npm i express, but things like @nestjs/platform-express depending on "express": "^5.0.0" will work just fine today and in the future.

[kamilmysliwiec]

Excellent, thank you @wesleytodd!