Skip to content

Starting a team for the package examples initiative #3

Open

Description

@joyeecheung

Proposed goals of this initiative:

  1. Identify and document package shipping patterns in the ecosystem (e.g. how people write their package.json). This is primarily about patterns in generic Node.js packages. For specific patterns of packages developed for various frameworks, or plugin packages etc. this repository can point readers to credible sources, but the source of truth for them should be hosted elsewhere (ideally in respective projects themselves).
  2. Write and maintain guides/tutorials/examples in this repository on how to ship various kind of packages e.g. how to write package.json for different consumers, how to perform certain package migrations e.g. from shipping CJS to shipping ESM. Personally I am a fan of the mini tutorial book + folders full of working examples approach in https://github.com/nodejs/node-addon-examples and I hope we can do something similar here.
  3. Providing a venue for folks to discuss about the patterns and ask questions about package shipping, and aid ecosystem cleanup efforts such as https://e18e.dev/

This is largely inspired by the NAPI effort, I think the NAPI team did a great job in putting out practical guides and resources for the NAPI migration, which was indispensable for the success of NAPI, and I hope we can learn from their success to help with the CJS -> ESM migration :)

Previously there was the @nodejs/package-maintenance team but the goals in https://github.com/nodejs/package-maintenance look very different and have a different audience. So I propose that we start a new team, which could be either a subteam under @nodejs/package-maintenance or just a different one, ideally involving maintainers of package tooling/package managers into the discussions to make sure that we are on the same page. Maybe it can be called @nodejs/package-examples , or @nodejs/package-patterns or a better name? (personally, it feels weird to me to have "examples" in the name of a team, so @nodejs/package-patterns sounds better).

About the joining this team: from previous experience (e.g. starting the automation team), I learned that if we just create a team and just add anyone who sign up to the team (i.e. including those who were not participating in anything in the organization), it's easy to end up with a team where most people were only active during the signup phase and after that >80% of the people don't respond to pings, and we ended up disbanding the largely inactive team and formed a smaller team with those who were active instead. To prevent that from happening again, I propose that we set up some simple rules:

  1. Anyone already in @nodejs/package-maintenance @nodejs/loaders @nodejs/tsc (and other related teams that I am forgetting, feel free to nominate) can be added directly
  2. Anyone who's not already part of 1 can be nominated by existing members with a simple explanation issue about why they should join.

While we are setting up this team, I propose that we grant write access to @nodejs/package-maintenance @nodejs/loaders and @nodejs/tsc to this repository, and the reviews etc. are delegated to existing teams. After the new team has gone through the initial setup phase and we have something up and going, we can switch the write access to that team.

Activity

  1. JakobJingleheimer commented on Nov 18, 2024

    @JakobJingleheimer
    Member
  2. charlieforward9 commented on Nov 20, 2024

    @charlieforward9

    Following this development along to support in https://github.com/yuzhva/react-leaflet-markercluster

  3. joyeecheung commented on Nov 20, 2024

    @joyeecheung
    MemberAuthor

    Discussed in the TSC meeting. Seems people are on board with the proposal. I granted the following access to this repo:

    Screenshot 2024-11-20 at 22 13 41

    One thing I cannot finish is setting up the new team, because both @nodejs/package-examples and @nodejs/package-patterns sound odd to me as team names. After some thoughts, I come up with @nodejs/package-pathfinders, which I think is better than the other two. Any objections to just creating the new team as @nodejs/package-pathfinders?

  4. mhdawson commented on Nov 20, 2024

    @mhdawson
    Member

    @nodejs/package-pathfinders sounds good to me.

  5. joyeecheung commented on Dec 9, 2024

    @joyeecheung
    MemberAuthor

    Added @nodejs/package-pathfinders and set it up as maintainers - I will add a guide on how to join later.

  6. slongdotexe commented on Aug 8, 2025

    @slongdotexe

    Hey everyone,
    Great to see a repository like this coming together. It seems to me that this will be pretty valuable, especially as more maintainers potentially look to migrate existing projects to ESM.

    I noticed that most of the documentation is still a work in progress. I am interested in contributing to anything where possible. If there is some material on the desired structure and content of these guides then that would be very helpful. But I could otherwise get started by modelling the documentation off the existing NodeJS site.

    No problem if there is no apetite for this at the moment, but I'd love to contribute to the ecosystem.

  7. joyeecheung commented on Aug 8, 2025

    @joyeecheung
    MemberAuthor

    Hi @slongdotexe ! Thanks for reaching out. I've been preoccupied with other works and haven't been able to get back to this initiative, but I do wish to get it complete as require(esm) graduates into stability.

    For how to contribute and the general roadmap of this initiative, see https://github.com/nodejs/package-examples/blob/main/CONTRIBUTING.md

    I had a WIP branch to fill out the first chapter of the minibook main...joyeecheung:package-examples:bootstrap-book - I'll probably take some time to at least finish the first chapter and send it to review soon. Would be helpful to get some feedback from readers :)

  8. slongdotexe commented on Aug 9, 2025

    @slongdotexe

    Hey @joyeecheung, no worries and thanks for the quick response!

    Regarding your WIP branch for the first chapter, I think it reads well, and I like the level of depth. It serves well to let a reader match up syntax they've probably seen before with the underlying technical definitions (CJS vs ESM) without being too verbose. It's also a good example of the writing style and tone for the content, too. Keen to read the rest once you have some more time :)

    In the meantime, I'll start a branch on another chapter and hopefully have something to share soon!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions