So, you received a part of a v2 addon conversion PR?.md

RFC#570: Background, motivation, reasoning.

Converting an addon to the v2/native format is described in detail here

NOTE: "v2 addons" are also known as "native packages", "native addons", "npm native", etc.

---

benefits tl;dr:

• Vite compatible (along with other packagers, rollup, etc)
• ESM-CDN compatible
• import-map compatible
• apps no longer need to build the addon (improved app build speed)
• tooling and typescript types provisioning "just makes sense" and is widely supported
• package.json#exports - not every module needs to be importable (nor should it be)

The main goal is that we want all libraries in the ember ecosystem to be compatible with broader ecosystem tooling. V1 addons, or "classic addons" are not browser libraries -- they are node programs that our special broccoli apps call in to and the program emits browser code -- so the more v1 addons you have, the more work your app has to do.

When all the core addons (including ember-source) are native packages, then our migration tool, embroider, can shed an entire compatibility layer, enabling much faster builds.

---

The approach i've been doing is to split this process in to as many PRs as possible -- incrementally giving maintainers the context needed to eventually take over v2 addon maintenance. I want to help folks get up to speed in easy / small bite-sized chunks! 🎉

Mulitple PRs:

graph TD;
  id0[0. Get CI green, and other upkeep]-.->id1
  id1[1. Convert solo-repo to single-package monorepo]-.->id2
  id1-.->id2-2
  id2[2. Make needed breaking changes if any ^1]-->id2
  id2-2[2. Convert monorepo to pnpm ^3]-.->id3
  id1-->id3
  id2-->id3
  id3[3. Extract the dummy app in to a separate workspace within the monorepo]-.->id4
  id3-->id5
  id4[4. Extract build-time behaviors to unplugin ^2]-->id5
  id5[5. Convert the addon to the v2 format]

¹²³

---

This may seem like a lot, but it's a migration path.

An end goal is to have addons back to solo-repos, but using vite to load their tests, and boot and setup an ember app in-memory, rather than having all the boilerplate code to run an ember-app that we have today.

Now this isn't without its trade-offs, and many folks will want to keep their separate test ember apps, as this is a better way to ensure that the build of an addon is successful, and will have high likelihood of working once published to npm.

For now, it's less maintenance effort to to use a separate ember app, than it is to re-implement what ember-cli is doing for an in-package test setup.

non-breaking changes?

changing / dropping engines or changing the volta node

Native browser packages don't use engines, so the field, if needed at all, would only be for development tooling. Changing the volta node only affects the dev-time node. (or the node on CI)

why pnpm?

many projects use yarn@v1 and it's just not suitable for real projects -- plagued with dependency management issues, incorrect peer decisions, and generally makes testing via ember-try harder than it needs to be.

official support from ember is in progress: emberjs/rfcs#907

Notes

Footnotes

1. this step could be skipped, but could include things like

   • removing require / requirejs
   • removing private API usage
   • other cleanup that we'd want to bundle in to a breaking release
   ↩

2. this step could be skipped as most addons do not have build-time behaviors, but unplugin is a reasonable approach for implementing cross-tool build-time behaviors. ↩

3. this step could be skipped, but a lot of repos are using yarn@v1 and there are too many bugs to deal with. pnpm has far better ecosystem support. ↩