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.