Skip to content

Latest commit

 

History

History
286 lines (200 loc) · 17.1 KB

porting-addons-to-v2.md

File metadata and controls

286 lines (200 loc) · 17.1 KB
Raw

Guide: Porting an Addon to V2

This is a guide for addon authors who want to publish their addon in v2 format.

The actual V2 Format RFC only cares what format you publish to NPM. It doesn't necessarily care about your authoring format or toolchain. But in this guide, we are picking good defaults, and we hope to polish this experience until it's ready to become a new RFC as the default new Ember Addon authoring blueprint.

What Addons should and should not be converted to V2?

The best candidates to convert to V2 are addons that provide only run-time features, like components, helpers, modifiers, and services. That kind of addon should definitely port to V2.

In contrast, addons that are primarily an extension to the build system (like ember-cli-sass or ember-cli-typescript) are not good candidates to be V2 addons, at present. V1 addons will continue to work through @embroider/compat for Embroider apps.

If your addon is a mix of both build-time and run-time features, consider replacing the build-time features with @embroider/macros. This would let you drop all your custom build-time code and port to V2. Alternatively, if you really need build customizations, you can provide users with instructions and utilities (like a webpack rule or plugin) to add those customizations to their Embroider build. We do not let V2 addons automatically manipulate the app's build pipeline. Thar be dragons.

Monorepo Organization

Traditionally, an Ember addon is a single NPM package that combines both the actual addon code and a "dummy" app for hosting tests and docs. This was problematic for several reasons. V2 addons instead require clean separation between addon and app, so you're going to be working with more than one distinct NPM package: one for the addon, one for the test-app, and optionally one for the documentation site.

Our recommended way to manage these multiple packages is using a monorepo, via pnpm, Yarn, or npm workspaces. The example in this guide assumes a pnpm workspaces monorepo because it's a good solution to work with Embroider in general.

Part 1: Separate Addon from Dummy App

In this part of the guide, our goal is to separate our existing V1 addon from its "dummy" app and rename the dummy app to "test-app". At the end of this part, you will still have a V1 addon but it will be independent of its test-app, making it much easier to convert to V2 format in a subsequent Part.

For a complete example of a PR that performed these steps on a real addon, see ember-cli/ember-page-title#227.

The steps:

  1. Delete pnpm-lock.yaml.

  2. At the top-level of your repo, make new directories named test-app and _addon

  3. Move these files and directories into _addon

    • addon
    • addon-test-support
    • app
    • blueprints
    • config/environment.js (moves to _addon/config/environment.js)
    • index.js

  4. Now you can rename _addon to addon without a name collision.

    • yes, this means you will have an addon/addon directory. This looks silly, but it will go away when we finish porting the addon to v2.

  5. These things stay at the top level:

    • .git
    • .github
    • changelog, code of conduct, contributing, license, and readme

    Move everything else into test-app

  6. Move everything under test-app/tests/dummy to directly under test-app instead.

    • for example, test-app/tests/dummy/app becomes test-app/app
    • you will be merging config directories because both test-app/config and test-app/tests/dummy/config will exist at the start of this step. They shouldn't have any file collisions because you already moved the one colliding file (environment.js) to addon/config/environment.js in a previous step.

  7. Make a new top-level package.json for our new monorepo:

    {
  "private": true,
  "workspaces": ["addon", "test-app"]
}

    With pnpm, the workspace packages must also be described in pnpm-workspace.yaml:

    packages:
  - 'addon'
  - 'test-app'

  8. Make a new top-level .gitignore:

    # you definitely want this:
node_modules

# and you can put in anything else that tends to accumulate in your environment:
.pnpm-debug.log
.DS_Store

  9. Copy test-app/package.json to addon/package.json

  10. Edit addon/package.json to remove all devDependencies, scripts, and ember-addon.configPath.

  11. Edit test-app/package.json. For each package in dependencies, either remove it (if it's only used by the addon and not the test-app) or move it to devDependencies (if it's actually used by the test-app).

    • For example, "ember-cli-babel" and "ember-cli-htmlbars" most likely need to move to devDependencies because test-app still needs JS and template transpilation.

  12. In test-app/package.json, add your addon as a devDependency of the test-app by name and exact version. Our monorepo setup will see this and link our two packages together. For example, if addon/package.json has this:

    "name": "ember-page-title",
"version": "8.0.0",

    Then you would add this to test-app/package.json:

    "devDependencies": {
  "ember-page-title": "8.0.0"
}

  13. In test-app/package.json, change the top-level "name" to "test-app", remove the "ember-addon" section, and remove "ember-addon" from keywords.

  14. In test-app/package.json, add the field "private": true because this package is not meant to be published on npm.

  15. At the top-level of the project, run pnpm install.

  16. In test-app/ember-cli-build.js switch from the dummy app build pipeline to the normal app build pipeline:

    -const EmberAddon = require('ember-cli/lib/broccoli/ember-addon');
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
...
-let app = new EmberAddon(defaults, {
+let app = new EmberApp(defaults, {

    You may also find other places in ember-cli-build.js that refer to files under tests/dummy. Update those paths to point directly to their new locations directly inside test-app instead.

  17. Search for all uses of the word "dummy" in the test-app. If they're referring to the app name, replace them with "test-app". This includes modulePrefix in test-app/config/environment.js and dummy.js and dummy.css in test-app/app/index.html and in test-app/tests/index.html.

  18. Try to boot your test-app and run the tests. Debug as needed to get things passing again.

    cd test-app
ember s
ember test

  19. The lint scripts are expected to work the same way as before inside the test-app. However, there's one common issue you may encounter when running the linter if you use eslint-plugin-n or eslint-plugin-node:

    error  "@embroider/test-setup" is not published  n/no-unpublished-require
error  "ember-cli" is not published  n/no-unpublished-require

    The lint rule tells that "@embroider/test-setup" and "ember-cli" are devDependencies being imported with require(). It's not a problem since the test-app is a private package. To solve the issue, make sure you use an up-to-date version of eslint-plugin-n (at least 15.4.0). If you don't want to update the lint tools right now, you can also deactivate the rule.

  20. At this point all tests and lint scripts work the same way as before inside the test-app. But we will also want linting, prettier, etc for the newly-separated addon workspace too.

    You could create one unified config at the top of the monorepo if you want, but I think it's simpler over the long run to manage each workspace separately. It's nice that the test-app is a totally stock Ember app that can be updated by ember-cli-update -- including all the default linting setup.

    Copy .gitignore, .eslintrc.js, .eslintignore, .prettierrc.js, .prettierignore, and .template-lintrc.js from test-app to addon.

    Edit them down so they only cover the thing the addon workspace has. For example, there's no dummy app or tests inside the addon workspace anymore, so the eslintrc will get simpler.

    Copy eslint, relevant eslint plugins, prettier, ember-template-lint, and npm-run-all from test-app/package.json devDependencies to addon/package.json devDependencies.

    Copy the lint-related scripts from test-app/package.json to addon/package.json.

    Test that pnpm lint works inside the addon workspace.

  21. Remove test-app/config/ember-cli-update.json because it still says you're using the addon blueprint and next time you run ember-cli-update in test-app it uses the app blueprint instead.

  22. Edit .github/workflows/ci.yml to run tests in the right directory. For example:

     - name: Test
   run: pnpm test:ember --launch ${{ matrix.browser }}
+  working-directory: test-app

    And make separate linting steps for both workspaces:

    -    - name: Lint
-      run: pnpm lint
+    - name: Lint Addon
+      run: pnpm lint
+      working-directory: addon
+    - name: Lint Test App
+      run: pnpm lint
+      working-directory: test-app

  23. If you're using volta, move the volta config to the top-level package.json and make both workspaces say:

    "volta": {
  "extends": "../package.json"
}

At this point, you should still have a fully-working V1 Addon, and if you want you can test, review, and merge this work before moving on.

Part 2 (Optional): Split docs from tests

Many addons have a deployable documentation app. Usually it is the same app as the test suite.

This causes a lot of pain because the test suite needs to support every Ember version your addon supports, and when your docs site is mixed in with your test suite, your docs site also needs to support every Ember version, and that's unnecessarily difficult. Documentation apps deal with lots of typical production app concerns (deployment, styling, server-side rendering) that mean they benefit from using many additional addons, which makes broad version compatibility challenging.

The solution is to split the docs from the test suite. The docs app can pick a single Ember version, and it can stay on older, deprecated patterns as long as you like without impacting your ability to test your addon against the latest Ember canary. When you get test failures on Ember Canary, they will be real failures that impact your users, not irrelevant failures caused by forcing your docs app and all its dependencies to upgrade to Canary.

To split out the docs, you could start by just copying all of test-app into a new docs directory. Add your new docs workspace to the top-level package.json. Then edit both apps down to eliminate documentation and deployment features from test-app and eliminate test-suite concerns from docs. It's still appropriate for docs to have its own tests of course, to prove that the docs pages themselves render correctly.

When the docs app is ready, expand the CI settings to cover linting and testing of the docs app, just like we did when we expanded it to cover linting of both addon and test-app above.

For a complete example of a PR that splits docs from test-app, see ember-cli/ember-page-title#228.

Part 3: Prerequisites for V2 addon

In this part, we address potential blockers before we actually switch to V2. This lets you test your changes and make sure they're still working before we move on to V2 format.

  1. Make sure your test-app (and docs app if you have one) has ember-auto-import >= 2. Once you convert your addon to v2 format, it can only be consumed by apps that have ember-auto-import >= 2. This also means you should plan to make a semver major release to communicate this new requirement to your users.

  2. Make sure all the files in the addon/app contain only reexport statements. If there's anything that's not a reexport statement, move that code into somewhere in the addon/addon directory and reexport it from addon/app. This was already best practice, but we're about to enforce it.

  3. Make sure all the reexports in addon/app follow the default naming convention, such that addon/app/components/whatever.js contains only a reexport of your-addon-name/components/whatever. If the names don't align, move files around inside addon/addon until they do.

  4. Make sure your addon has co-located templates. By default, the build tools expect to find the component's .js and .hbs in the same folder. If your addon used to have an addon/templates/components folder, move to co-location. Note that a codemod has been released when co-location has become the recommended structure.

  5. Make sure your addon/index.js file isn't trying to do anything "interesting". Ideally it contains nothing other than your addon's name.

    • if it was using app.import() or this.import(), port those usages to ember-auto-import instead
    • if you're trying to modify your own source code based on the presence of other packages or based on development vs testing vs production, switch to @embroider/macros instead
    • if you have other cases you're not sure what to do with, ask in an issue on this repo, or https://discuss.emberjs.com, or the #dev-embroider channel in the Ember community discord.

Part 4: Convert addon to v2

In this part we actually convert our addon from v1 to v2 format by reorganizing it and setting up a default toolchain for building and publishing it.

For an example of a complete PR that applies these steps to a real addon, see ember-cli/ember-page-title#229

Now that we've separated the test-app and docs app concerns from the addon, we can focus on reorganizing the addon itself to V2 format.

  1. Rename the addon/addon directory to addon/src.

  2. If you have an addon/addon-test-support directory, move it to addon/src/test-support.

  3. In addon/package.json, remove any of these that appear in dependencies:

    • ember-cli-htmlbars
    • ember-cli-babel
    • ember-auto-import
    • @embroider/macros

    All of these implement standard features of V2 addons that don't need to come as dependencies.

  4. pnpm add @embroider/addon-shim. This is the only dependency a v2 addon needs (in order to interoperate with ember-cli.

  5. We're going to set up a default build pipeline for things like template colocation and decorator support. Install these dev dependencies:

    pnpm add --save-dev @embroider/addon-dev rollup @rollup/plugin-babel @babel/core @babel/plugin-transform-class-properties @babel/plugin-proposal-decorators

  6. Grab the example babel config and save it as addon/babel.config.json

    • If you addon requires template transforms in order to publish to a shareable format. Apply transforms using the babel-plugin-ember-template-compilation. View how to use this in the example babel.config.js

  7. Grab the example rollup config and save it as addon/rollup.config.js.

  8. Identify your app reexports. This is the list of modules from your addon that get reexported by files in the addon/app directory.

  9. Delete the addon/app directory. You aren't going to need it anymore.

  10. Edit addon/rollup.config.js. Customize the publicEntrypoints so it includes

  • every module that users should be allowed to import from your addon
  • every module in the app reexports you identified in the previous step
  1. Still editing addon/rollup.config.js, customize the appReexports to match all your app reexports as identified above.
  2. Delete your addon/index.js file.
  3. Create a new addon/addon-main.js file (this replaces addon/index.js) with this exact content:
const { addonV1Shim } = require('@embroider/addon-shim');
module.exports = addonV1Shim(__dirname);
  1. In your addon/.eslintrc.js, replace "index.js" with "addon-main.js" so that our new file will lint correctly as Node code.
  2. In your addon/package.json, add these things: 
    "exports": {
  ".": "./dist/index.js",
  "./*": "./dist/*",
  "./test-support": "./dist/test-support/index.js",
  "./addon-main.js": "./addon-main.js"
},
"files": [
  "addon-main.js",
  "dist"
],
"scripts": {
  "build": "rollup --config",
  "prepublishOnly": "rollup --config",
  "start": "rollup --config --watch"
},
"ember-addon": {
  "main": "addon-main.js",
  "type": "addon",
  "version": 2
}
  3. In the addon directory, run pnpm start to start building the addon.
  4. In a separate shell, you should be able to go into the test-app directory and run pnpm start or pnpm test and see your tests passing.

When all tests are passing, you have a fully-working V2 addon and you're ready to release it. To publish, you will run npm publish in the addon directory.