diff --git a/ADDON-AUTHOR-GUIDE.md b/ADDON-AUTHOR-GUIDE.md index 6a20b5ebd..40b5712a9 100644 --- a/ADDON-AUTHOR-GUIDE.md +++ b/ADDON-AUTHOR-GUIDE.md @@ -1,77 +1 @@ -# Addon Author Guide - -This document lays out the recommended best practices for addon authors who want their addons to work in apps built with Embroider. - -## Give me the tl;dr: what should I do? - -The best thing for all addons authors to do right now is to achieve the "Embroider Safe" support level. Follow the instructions in the [@embroider/test-setup README](https://github.com/embroider-build/embroider/tree/main/packages/test-setup) to add the `embroider-safe` scenario to your ember-try config. - -There are other levels of support beyond "Embroider Safe", but as long as you get that far you unblock the ability of your users to use Embroider. And the good news is that many addons are already Embroider Safe without doing any work, and all they really need to do is verify by adding a new scenario to their test suite. - -## Big Picture - -Embroider defines a new format for Ember Addons, which we call **v2 format**. We call the traditional format **v1 format**. - -Under the hood, `@embroider/core` _only_ understands **v2** addons and that allows it to be simpler than the traditional build pipeline while doing more powerful static analysis. - -But because we care a lot about backward compatibility, we also have `@embroider/compat`: a layer that sits before `@embroider/core` that can compile _most_ **v1** addons to **v2**. It's "most" and not "all" because there are some things **v1** addons can do that are just too dynamic to bring forward into the more static format, or too locked-in to implementation details of the traditional build pipeline and its final output. - -While we definitely want to move the whole addon ecosystem to **v2** format over time, there is no rush. As long as your addon can be understood by `@embroider/compat`, your addon won't block anyone from using Embroider. - -We call addons that can be understood by `@embroider/compat` "Embroider Safe". "Embroider Safe" is the first of several different "support levels" an addon can achieve: - -| Support level | Format | -| ------------------------ | :----: | -| Embroider Safe | v1 | -| Optimized Embroider Safe | v1 | -| Embroider Native | v2 | - -## Support Level: Embroider Safe - -Your addon may already be Embroider Safe! Many addons are. We've done a lot of work in the `@embroider/compat` package to be able to compile v1 addons on-the-fly into v2 addons. - -The best way to see if your addon is Embroider safe is to add the `@embroider/test-setup` package and runs its `embroider-safe` ember-try scenario. See its [README](https://github.com/embroider-build/embroider/tree/main/packages/test-setup) for full details. - -If your tests _don't_ work under Embroider when you try this, please file an issue on the Embroider repo. We can help you triage whether there's a missing feature in `@embroider/compat` that would allow your addon to work unchanged, or whether there is a better way to refactor your addon to avoid incompatible behavior. - -If your addon does work under Embroider, congrats! It is Embroider Safe. Please keep running the tests in your CI so you will notice if a future change to either Embroider or your addon breaks compatibility. You can also move on to achieving the Optimized Embroider Safe support level. - -## Support Level: Optimized Embroider Safe - -Out of the box, Embroider runs with the maximum level of backward compatibility. Apps are encouraged to start there, and then once they have that working they can try to enable more optimizations (which really means _disabling_ some of the more heavy-handed backward compatibility systems in order to let the app be built more statically). - -The Embroider README [explains what the options are and which order you should try to enable them](https://github.com/embroider-build/embroider/#options). This includes: - -1. `staticAddonTrees` and `staticAddonTestSupportTrees` are relatively safe and easy. If these don't work, it's probably because you are consuming Javascript modules without importing them. If you can directly import them instead, you can probably enable these flags and keep your tests passing. -2. `staticHelpers` is also relatively safe. The way most code uses helpers in their templates tends to be statically analyzable. -3. `staticComponents` is harder, because addons tend to use the `{{component}}` helper frequently, and Embroider cannot always statically tell what this means. App authors are able to work around this problem by adding `packageRules`, but addons should actually solve the problem directly by making their code statically understandable. See "Replacing the {{component}} helper" below. - -You can follow these steps in your addon's dummy app to see if your tests continue to pass even under the higher levels of optimization. If you can get all the way to `staticComponents: true`, your addon is achieves the Optimized Embroider Safe support level. - -You don't need to try to test the `splitAtRoutes` option within your addon -- as long as you reach `staticComponents` your addon will work fine in apps that want to use `splitAtRoutes`. - -Once you achieve Optimized Embroider Safe, you should enable the `embroider-optimized` ember-try scenario provided by `@embroider/test-setup` to ensure you don't regress. It's a good idea to also continue testing the `embroider-safe` scenario too, because some common bugs can actually get optimized away under `embroider-optimized` that will break under `embroider-safe`. - -## Support Level: Embroider Native - -An addon achieves the "Embroider Native" support level by publishing to NPM in the **v2 format**, as defined by [the RFC](https://github.com/emberjs/rfcs/pull/507). - -For full details on porting an addon to V2, see [the V2 porting guide](https://github.com/embroider-build/embroider/blob/main/PORTING-ADDONS-TO-V2.md) - -Another good way to learn about V2 addons is to look at some examples: - -- [ember-welcome-page](https://github.com/ember-cli/ember-welcome-page) -- [ember-resources](https://github.com/NullVoxPopuli/ember-resources) -- [ember-stargate](https://github.com/kaliber5/ember-stargate) -- [glimmer-apollo](https://github.com/josemarluedke/glimmer-apollo) - -Several of these examples use a monorepo as a way to keep a clean separation between the addon and the application that holds their test suite. If you're comfortable working with monorepos this is a good solution. On the other hand, monorepos have some tradeoffs and are not always well-supported by all tools, so it's also OK to keep your test app in a subdirectory of your addon. This is closer to how V1 addons work, where `tests/dummy` serves this purpose. See [ember-welcome-page](https://github.com/ember-cli/ember-welcome-page) for an example of not using a monorepo -- instead it has a `test-app` subdirectory and uses the `addon-dev` command from `@embroider/addon-dev` to manage linkage between the addon and the test-app and to manage combining of dependencies from both into a single top-level package.json - -We support some tools to make V2 addon development more convenient: - -- [@embroider/addon-shim](https://github.com/embroider-build/embroider/blob/main/packages/addon-shim/README.md) makes your V2 addon understandable to ember-cli. All V2 addons should use this. -- [@embroider/addon-dev](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/README.md) is an optional `devDependency` for your addon that provides build tooling. This gives you more flexibility over how you author your addon (like taking advantage of automatic template-colocation or using TypeScript) while still producing a spec-compliant package for publication to NPM. - -## Replacing the {{component}} helper - -This section grew into its own separate document. +File moved to [docs/addon-author-guide.md](docs/addon-author-guide.md) diff --git a/ANALYZING.md b/ANALYZING.md index ff6905f45..84441c4fc 100644 --- a/ANALYZING.md +++ b/ANALYZING.md @@ -1,75 +1 @@ -# Analyzing Bundles - -You can analyze webpack's generated bundles using [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer#webpack-bundle-analyzer). - -1. require `BundleAnalyzerPlugin` at the top of your `ember-cli-build.js` file: - -```javascript -const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer'); -```` - -2. Configure webpack to use this plugin through embroider's `webpackConfig` option: - -```javascript -return require('@embroider/compat').compatBuild(app, Webpack, { - packagerOptions: { - webpackConfig: { - plugins: [new BundleAnalyzerPlugin()] - } - } -}); -``` - -Note this step modifies the snippet as described in step 2 in the [README.md](README.md). - -## Analyzer server - -Webpack Bundle Analyzer will spin up an additional server which serves a page that you can visit in the browser to see the results. That server is started no matter if one runs `ember build` or `ember serve`. To disable the server pass the following config to the instantiation of `BundleAnalyzerPlugin()` in the snippet above. - -```javascript -//... -new BundleAnalyzerPlugin({ - generateStatsFile: true, - openAnalyzer: false, - statsFilename: path.join( - process.cwd(), - 'concat-stats-for', - 'my-stats.json', - ), -}) -//... -``` - -With that configuration the results will be written to a json file in your projects directory. - -## Include legacy addons in analyzation - -The results will not show the contents of vendor.js, which provides legacy support for addons that import things into script context and doesn't go through webpack. To see what is contributing to the size of vendor.js, set the environment variable `EMBROIDER_CONCAT_STATS=true` like: - -``` -EMBROIDER_CONCAT_STATS=true ember build -``` - -Which will cause your build to print output like: - -``` -Concatenated assets/vendor.js: - ./node_modules/@embroider/synthesized-vendor/vendor/ember/ember.debug.js: 1.76 MB - ./node_modules/@embroider/synthesized-vendor/vendor/jquery/jquery.js: 265.38 KB - ./node_modules/@embroider/synthesized-vendor/vendor/hammerjs/hammer.js: 72.1 KB - ./node_modules/@embroider/synthesized-vendor/vendor/loader/loader.js: 8.75 KB - ./node_modules/@embroider/synthesized-vendor/vendor/propagating-hammerjs/propagating.js: 7.34 KB - in-memory: 85 B - ./node_modules/@embroider/synthesized-vendor/vendor/ember-paper/register-version.js: 57 B -Concatenated assets/test-support.js: - ./node_modules/@embroider/synthesized-vendor/vendor/qunit/qunit.js: 148.2 KB - ./node_modules/@embroider/synthesized-vendor/vendor/ember/ember-testing.js: 76.44 KB - ./node_modules/@embroider/synthesized-vendor/vendor/qunit-dom.js: 37.67 KB - ./node_modules/@embroider/synthesized-vendor/vendor/monkey-patches.js: 1.32 KB - ./node_modules/@embroider/synthesized-vendor/vendor/ember-qunit/qunit-configuration.js: 491 B - ./node_modules/@embroider/synthesized-vendor/vendor/overwrite-qunit-dom-root-element.js: 181 B - ./node_modules/@embroider/synthesized-vendor/vendor/define-dummy-module.js: 54 B -Concatenated assets/test-support.css: - ./node_modules/@embroider/synthesized-vendor/vendor/qunit/qunit.css: 7.69 KB - ./node_modules/@embroider/synthesized-vendor/vendor/ember-qunit/test-container-styles.css: 544 B -``` +File moved to [docs/analyzing.md](docs/analyzing.md) diff --git a/PORTING-ADDONS-TO-V2.md b/PORTING-ADDONS-TO-V2.md index cb84c7925..84e0e601e 100644 --- a/PORTING-ADDONS-TO-V2.md +++ b/PORTING-ADDONS-TO-V2.md @@ -1,264 +1 @@ -# 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](https://github.com/ember-cli/rfcs/issues/119). 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 Yarn Workspaces or NPM Workspaces. The example in this guide assumes a Yarn Workspaces monorepo. - -## 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 https://github.com/ember-cli/ember-page-title/pull/227. - -The steps: - -1. Delete yarn.lock. - -1. At the top-level of your repo, make new directories named `test-app` and `_addon` - -1. Move these files and directories into `_addon` - - - addon - - addon-test-support - - app - - blueprints - - config/environment.js (moves to `_addon/config/environment.js`) - - index.js - -1. 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. - -1. These things stay at the top level: - - - .git - - .github - - changelog, code of conduct, contributing, license, and readme - - Move **everything else** into `test-app` - -1. 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. - -1. Make a new top-level package.json for our new monorepo: - - ```json - { - "private": true, - "workspaces": ["addon", "test-app"] - } - ``` - -1. 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: - yarn-error.log - .DS_Store - ``` - -1. Copy `test-app/package.json` to `addon/package.json` -1. Edit `addon/package.json` to remove all `devDependencies`, `scripts`, and `ember-addon.configPath`. -1. 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. -1. 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: - - ```js - "name": "ember-page-title", - "version": "8.0.0", - ``` - - Then you would add this to `test-app/package.json`: - - ```js - "devDependencies": { - "ember-page-title": "8.0.0" - } - ``` - -1. `In test-app/package.json`, change the top-level "name" to "test-app", remove the "ember-addon" section, and remove "ember-addon" from keywords. -1. At the top-level of the project, run `yarn install`. -1. In `test-app/ember-cli-build.js` switch from the dummy app build pipeline to the normal app build pipeline: - - ```diff - -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. - -1. 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`. -1. Try to boot your test-app and run the tests. Debug as needed to get things passing again. - ```sh - cd test-app - ember s - ember test - ``` -1. 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 `yarn lint` works inside the `addon` workspace. - -1. 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. - -1. Edit `.github/workflows/ci.yml` to run tests in the right directory. For example: - - ```diff - - name: Test - run: yarn test:ember --launch ${{ matrix.browser }} - + working-directory: test-app - ``` - - And make separate linting steps for both workspaces: - - ```diff - - - name: Lint - - run: yarn lint - + - name: Lint Addon - + run: yarn lint - + working-directory: addon - + - name: Lint Test App - + run: yarn lint - + working-directory: test-app - ``` - -1. 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 https://github.com/ember-cli/ember-page-title/pull/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/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 https://github.com/ember-cli/ember-page-title/pull/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. `yarn 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: - - `yarn add --dev @embroider/addon-dev rollup @rollup/plugin-babel @babel/core @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators` - -6. Grab the [example babel config](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-babel.config.json) 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](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-babel.config.js) -7. Grab the [example rollup config](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-rollup.config.js) 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 - -11. Still editing `addon/rollup.config.js`, customize the `appReexports` to match all your **app reexports** as identified above. -12. Delete your `addon/index.js` file. -13. Create a new `addon/addon-main.js` file (this replaces `addon/index.js`) with this exact content: - -```js -const { addonV1Shim } = require('@embroider/addon-shim'); -module.exports = addonV1Shim(__dirname); -``` - -14. In your `addon/.eslintrc.js`, replace "index.js" with "addon-main.js" so that our new file will lint correctly as Node code. -15. In your `addon/package.json`, add these things: - ```js - "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 - } - ``` -16. In the `addon` directory, run `yarn start` to start building the addon. -17. In a separate shell, you should be able to go into the `test-app` directory and run `yarn start` or `yarn 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. +File moved to [docs/porting-addons-to-v2.md](docs/porting-addons-to-v2.md) diff --git a/README.md b/README.md index 44cf94085..1bfd41ed9 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ This repo implements a new three-stage build system for Ember apps: and 3 improves our ability to innovate and experiment with taking the best parts of wider JS ecosystem tooling. -You can read more about the motivation and key ideas in the [intro to the SPEC](SPEC.md). +You can read more about the motivation and key ideas in the [intro to the SPEC](docs/spec.md). ## Status / Should I Use It? @@ -41,7 +41,7 @@ Alternatively, it is totally safe to stick with the traditional build pipeline a ## For Addon Authors -The [v2 Addon Format RFC](https://github.com/emberjs/rfcs/pull/507) is the official spec for the packages that Embroider natively handles. Addon authors should see [ADDON-AUTHOR-GUIDE.md](ADDON-AUTHOR-GUIDE.md) for advice on how to get their addons ready for Embroider. +The [v2 Addon Format RFC](https://github.com/emberjs/rfcs/pull/507) is the official spec for the packages that Embroider natively handles. Addon authors should see [ADDON-AUTHOR-GUIDE.md](docs/addon-author-guide.md) for advice on how to get their addons ready for Embroider. ## How to try it @@ -131,7 +131,7 @@ See [@embroider/router README](./packages/router/README.md) for more details. ## Analyzing Bundles -see [`ANALYZING.md`](ANALYZING.md) +see [`ANALYZING.md`](docs/analyzing.md) ## Contributing diff --git a/REPLACING-COMPONENT-HELPER.md b/REPLACING-COMPONENT-HELPER.md index 11880c36a..6a4516c66 100644 --- a/REPLACING-COMPONENT-HELPER.md +++ b/REPLACING-COMPONENT-HELPER.md @@ -1,252 +1 @@ -# Replacing the Component Helper - -Using the `{{component}}` helper can prevent your app or addon from being -statically analyzed, which will prevent you from taking advantage of -`staticComponents` and `splitAtRoutes`. - -The exact rules for `{{component}}` are: - -- it's OK to pass a string literal component name like `{{component "my-title-bar"}}` -- it's OK to pass a value wrapped in the ensure-safe-component helper from `@embroider/util`, like `{{component (ensure-safe-component this.titleBar) }}`. But make sure you understand what ensure-safe-component itself is doing. Sprinkling existing code with ensure-safe-component without paying attention to the deprecation messages it emits will _not_ make your app work in Embroider. -- any other syntax in the first argument to `{{component ...}}` is NOT OK - -The following sections explain what to do in the common scenarios where you might have unsafe usage of the `{{component}}` helper. - -## When you're invoking a component you've been given - -Here's an example of a component that accepts an optional `@titleBar=` argument: - -```js -import Component from '@glimmer/component'; - -export default class extends Component { - get titleBar() { - return this.args.titleBar || 'default-title-bar'; - } -} -``` - -```hbs -{{component this.titleBar}} -``` - -The first step is to switch to angle bracket invocation: - -```hbs - -``` - -Now we eliminated the `{{component}}` helper. And this actually works, but with two big caveats: - -- it only works reliably on Ember versions before 3.23, because we might get passed a string, and invoking a string via angle brackets was an accidental behavior that was never intended, and it's fixed in that release. -- and we haven't really solved the underlying problem, which is that we can sneakily convert strings into components in a way that lets them escape Embroider's analysis. - -So we need another step. Add `@embroider/util` to your project, and use `ensureSafeComponent`: - -```js -import Component from '@glimmer/component'; -import { ensureSafeComponent } from '@embroider/util'; - -export default class extends Component { - get titleBar() { - return ensureSafeComponent(this.args.titleBar || 'default-title-bar', this); - } -} -``` - -```hbs - -``` - -This now works even on newer Ember versions. If the user passes a string, it emits a deprecation warning while converting the value to an actual component definition so the angle bracket invocation works. This will help your users migrate away from passing strings to your component. - -Notice also that if the user doesn't provide a component, we will trigger the deprecation warning by passing our own string `"default-title-bar"` into `ensureSafeComponent`. So we need one more step to clear this deprecation (and make our code truly understandable by embroider). Import the component class instead: - -```js -import Component from '@glimmer/component'; -import { ensureSafeComponent } from '@embroider/util'; -import DefaultTitleBar from './default-title-bar'; - -export default class extends Component { - get titleBar() { - return ensureSafeComponent(this.args.titleBar || DefaultTitleBar, this); - } -} -``` - -```hbs - -``` - -On old Ember versions (< 3.25), when `ensureSafeComponent` sees a component class, it converts it into a component definition so it can be safely invoked. On newer Ember versions, it does nothing because component classes are directly invokable. - -**Caution**: old-style components that have their template in `app/templates/components` instead of co-located next to their Javascript in `app/components` can't work correctly when discovered via their component class, because there's no way to locate the template. They should either port to being co-located (which is a simple mechanical transformation and highly recommended) or should import their own template and set it as `layout` as was traditional in addons before co-location was available. - -## When you're passing a component to someone else - -Here's an example `` component that accepts a `@titleBar=`. When the author of `` follows the steps from the previous section, if we try to call it like this: - -```hbs - -``` - -we'll get a deprecation message like - -> You're trying to invoke the component "fancy-title-bar" by passing its name as a string... - -The simplest fix is to add the `{{component}}` helper: - -```hbs - -``` - -This is one of the two safe ways to use `{{component}}`, because we're passing it a **string literal**. String literals are safe because they are statically analyzable, so Embroider can tell exactly what component you're talking about. - -But if instead you need anything other than a string literal, you'll need a different solution. For example, this is not OK: - -```hbs - -``` - -You can refactor this example into two uses with only string literals inside `{{component}}`, and that makes it OK: - -```hbs - -``` - -But if your template is getting complicated, you can always move to Javascript and import the components directly: - -```js -import Component from '@glimmer/component'; -import FancyTitleBar from './fancy-title-bar'; -import PlainTitleBar from './plain-title-bar'; - -export default class extends Component { - get whichComponent() { - return this.fancy ? FancyTitleBar : PlainTitleBar; - } -} -``` - -```hbs - -``` - -Note that we didn't use `ensureSafeComponent` here because we already stipulated -that `` is itself using `ensureSafeComponent`, and so ``'s public -API accepts component classes _or_ component definitions. But if you were unsure -whether `` accepts classes, it's always safe to run them through -`ensureSafeComponent` yourself first (`ensureSafeComponent` is idempotent). - -## When you need to curry arguments onto a component - -A common pattern is yielding a component with some curried arguments: - -```hbs -{{yield (component 'the-header' mode=this.mode)}} -``` - -In this particular example, we're using a **string literal** for the component name, which makes it OK, and you don't need to change it. - -But what if you need to curry arguments onto a component somebody else has passed you? - -```hbs -{{yield (component this.args.header mode=this.mode)}} -``` - -Because we're only adding a `mode=` argument to this component and not invoking it, we can't switch to angle bracket invocation. Instead, we can wrap our component in the `ensure-safe-component` helper from the `@embroider/util` package: - -```hbs -{{yield (component (ensure-safe-component this.args.header) mode=this.mode)}} -``` - -This works the same as the Javascript `ensureSafeComponent` function, and by appearing **directly** as the argument of the `{{component}}` helper, Embroider will trust that this spot can't unsafely resolve a string into a component. - -## When you're matching a large set of possible components - -Another common pattern is choosing dynamically from within a family of -components: - -```js -import Component from '@glimmer/component'; - -export default class extends Component { - get whichComponent() { - return `my-app/components/feed-items/${this.args.model.type}`; - } -} -``` - -```hbs -{{component this.whichComponent feedItem=@model}} -``` - -You can replace this with native `import()` or the `importSync()` macro, because -they support dynamic segments (for full details on what exactly is supported, -see "Supported -subset of dynamic import syntax" in the Embroider V2 Package RFC. - -In this case, we're refactoring existing synchronous code so we can use -`importSync`: - -```js -import Component from '@glimmer/component'; -import { importSync } from '@embroider/macros'; -import { ensureSafeComponent } from '@embroider/util'; - -export default class extends Component { - get whichComponent() { - let module = importSync(`./feed-items/${this.args.model.type}`); - return ensureSafeComponent(module.default, this); - } -} -``` - -```hbs - -``` - -This code will cause every module under the `./feed-items/` directory to be eagerly included in your build. - -To instead _lazily_ include them, refactor to use asynchronous `import()` instead of `importSync`. BUT CAUTION: using `import()` of your own app code is one of the few things that works _only_ under Embroider and not in classic builds, so don't do it until you have committed to Embroider. - -## When using one-off components in tests - -If you find yourself defining custom, one-off components to be used in your tests, you might have been using a syntax like this: - -```js -import { setComponentTemplate } from '@ember/component'; -import Component from '@glimmer/component'; - -test('my test', async function (assert) { - class TestComponent extends Component {} - - setComponentTemplate(hbs`Test content: {{@message}}`, TestComponent); - - this.owner.register('component:test-component', TestComponent); - - await render(hbs` - - `); -}); -``` - -This will fail, as `test-component`cannot be statically found. Instead, you can directly reference the component class: - -```js -import { setComponentTemplate } from '@ember/component'; -import Component from '@glimmer/component'; - -test('my test', async function (assert) { - class TestComponent extends Component {} - - setComponentTemplate(hbs`Test content: {{@message}}`, TestComponent); - - this.testComponent = TestComponent; - - await render(hbs` - - `); -}); -``` +File moved to [docs/replacing-component-helper.md](docs/replacing-component-helper.md) diff --git a/SPEC.md b/SPEC.md index 806d491b5..438abe5bb 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,824 +1 @@ -# V2 Package Spec - -# Motivation - -One of the good things about Ember is that apps and addons have a powerful set of build-time capabilities that allow lots of shared code with zero-to-no manual integration steps for the typical user. We have been doing “zero config” since before it was a cool buzzword (it was just called “convention over configuration”). And we’ve been broadly successful at maintaining very wide backward- and forward-compatibility for a large body of highly-rated community-maintained addons. - -But one of the challenging things about Ember is that our ecosystem’s build-time capabilities are more implementation-defined than spec-defined, and the implementation has accumulated capabilities organically while only rarely phasing out older patterns. I believe the lack of a clear, foundational, build-time public API specification is the fundamental underlying issue that efforts like the various packaging / packager RFCs have tried to work around. - -The benefits to users for this RFC are: - -- faster builds and faster NPM installs -- “zero-config import from NPM — both static and dynamic” as a first-class feature all apps and addons can rely on. -- immediate tree-shaking of app- and addon-provided modules that are consumed directly via ECMA imports (for example, any ember-animated transition you don’t use in your app won’t get included in the build), with a smooth improvement path for steadily increasing the level of static analysis as other efforts like templates imports land. -- a more approachable build system that enables more people to contribute and better integration with other JS toolchains. - -# Key Ideas - -## Fully Embrace ES Modules - -Ember was one of the earliest adopters of ECMAScript modules, and Ember core team members were directly involved in helping move that features through TC39. Ember’s early experiences with modules influenced the spec itself. _Yet we have lagged in truly embracing modules._ - -For example, how do Ember apps express that they depend on a third-party library? The [app.import](https://ember-cli.com/user-guide/#javascript-assets) API. This should be ECMA standard `import`. - -Another way to state the problem is that apps and addons all _push_ whatever code they want into the final built app. Whereas ES modules can _pull_ each other into the build as needed. - -## Play nice with NPM Conventions - -The ECMA module spec by itself doesn’t try to define a module resolution algorithm. But the overwhelmingly most popular convention is the [node_modules resolution algorithm](https://nodejs.org/api/all.html#modules_all_together). - -Ember addons do respect node_module resolution for build-time code, but they do not respect it for runtime code. There’s no reason not to. - -## Verbose, Static Javascript as a Compiler Target - -Ember’s strong conventions mean that many kinds of dependencies can be inferred (including _statically_ inferred) without requiring the developer to laboriously manage them. This is a good thing and I believe the current fad in the wider Javascript ecosystem for making developers hand-write verbose static imports for everything confuses the benefits of having static analysis (which is good) with the benefits of hand-managing those static imports (which is unnecessary cognitive load when you have clear conventions and a compiler). - -This design is about compiling today’s idiomatic Ember code into more “vanilla” patterns that leverage ES modules, node_modules resolution, and spec-compliant static and dynamic `import` to express the structure of an Ember application in a much more “vanilla Javascript” way. - -This compile step lets us separate the authoring format (which isn’t changing in any significant way in this RFC) from the packaging format (which can be more verbose and static than we would want in an authoring format). - -# Detailed Design - -## Definitions - -**package**: every addon and app is a package. Usually synonymous with “NPM package”, but we also include in-repo packages. The most important fact about a package is that it’s often the boundary around code that comes from a particular author, team, or organization, so coordination across packages is a more sensitive design problem than coordination within apps. - -**app**: a package used at the root of a project. - -**addon**: a package not used at the root of a project. Will be an **allowed dependency** of either an **app** or an **addon**. - -**allowed dependency**: For **addons**, the **allowed dependencies** are the `dependencies` and `peerDependencies` in `package.json` plus any in-repo addons. For **apps**, the **allowed dependencies** are the `dependencies`, `peerDependencies`, and `devDependencies` in `package.json` plus any in-repo addons. - -**Ember package metadata**: the `ember-addon` section inside `package.json`. This already exists in v1, we’re going to extend it. - -**v2 package**: a package with `package.json` like: - - "keywords": [ "ember-addon" ], - "ember-addon": { - "version": 2 - } - -**v1 package**: a package with `package.json` like: - - "keywords": [ "ember-addon" ] - -and no `version` key (or version key less than 2) in **Ember package metadata**. - -**non-Ember package**: a package without `keywords: ["ember-addon"]` - -## Package Public API Overview - -The structure we are about to describe _is a publication format_. Not necessarily an authoring format. By separating the two, we make it easier to evolve the authoring formats without breaking ecosystem-wide compatibility. The publication format is deliberately more explicit and less dynamic that what we would want for an authoring format. - -First, here’s the list of things a v2 package can provide. More detail on each of these will follow: - -- **Own Javascript**: javascript and templates under the package’s own namespace (the v1 equivalent is `/addon/**/*.js/`) -- **App Javascript**: javascript and templates that must be merged with the consuming app’s namespace (the v1 equivalent is `/app/**/*.js`). This likely stops being needed when use with a template imports feature, but v2 package format is not dependent on that. -- **CSS:** available for `@import` by other CSS files (both in the same package and across packages) and by ECMA `import` directives in Javascript modules (both in the same package and across packages). -- **Assets**: any files that should be available in the final built application directory (typical examples are images and fonts). -- **Middleware**: express middleware that will mount automatically during development, unchanged from v1. -- **Preprocessors**: for producing JS, CSS, or HBS. -- **Commands**: commands that can be invoked from the command line. Unchanged from v1. -- **Blueprints**: blueprints for generating new files from the command line. Unchanged from v1. -- **ContentFor**: the ability to insert snippets into key places, like the document header. -- **Active Dependencies**: the subset of a given package’s **allowed dependencies** that are Ember packages and that the given package considers active. - -## Own Javascript - -The public `main` (as defined in `package.json`) of a v2 package points to its **Own Javascript**. The code is formatted as ES modules using ES latest features. Templates are in place in hbs format, and any custom AST transforms have already been applied. - -(Remember, we’re describing the _publication_ format, not the _authoring_ format. Authors can still do what they do today, using preprocessors provided by other addons. But that will all run before publishing.) - -The benefit of this design is that it makes our packages understandable by a broader set of tooling. Editors and build tools can follow `import` statements across packages and end up in the right place. - -In v1 packages, `main` usually points to a build-time configuration file. That file is moving and will be described in the **Addon Hooks** section below. - -Modules in **Own Javascript** are allowed to use ECMA static `import` to resolve any **allowed dependency**, causing it to be included in the build whenever the importing module is included. This replaces `app.import`. - -Notice that a package’s **allowed dependencies** do not include the package itself. This is consistent with how node module resolution works. This is different from how run-time AMD module resolution has historically worked in Ember Apps, so the build step that produces the v2 publication format will need to adjust import paths appropriately. For example, if `your-package/a.js` tries to import from `"your-package/b"`, that needs to get rewritten to “`./b`". - -Modules in **Own Javascript** are also allowed to use the (currently stage 3) ECMA dynamic `import()`, and the specifiers have the same meanings as in static import. We impose one caveat: only string-literal specifiers are supported. So `import('./lang-en')` is OK but `import("./lang-"+language)` is not. We retain the option to relax this restriction in the future. The restriction allows us to do better analysis of possible inter-module dependencies (see **Build-time Conditionals** below for an example). - -Modules in **Own Javascript** are allowed to import template files. This is common in today’s addons (they import their own layout to set it explicitly). - -Modules in **Own Javascript** are allowed to use `hbs` tagged template strings as provided by `ember-cli-htmlbars-inline-precompile`, and we promise to compile the templates at app build time. - -You’re allowed to `import` from both other v2 Ember packages and non-Ember packages. The only difference is that v2 Ember packages necessarily agree to provide ES modules with ES latest features, and so we will always apply the application’s browser-specific Babel transpilation to them. Non-Ember packages can be authored in lots of ways, and we will use best-effort to consume them, including conversion of ESM or CJS to whatever format we’re using in the browser (currently AMD), but we won’t apply the app’s Babel transpilation to them, because it’s usually just unnecessary expense — the most common way to ship NPM packages outside of well-known build systems like ember-cli is to transpile before publication. - -_A recent lesson from ember-auto-import is that we’re going to want to allow people to opt-in to babel transpilation of specific foreign packages, as the wider ecosystem’s norms evolve and more projects ship modern JS untranspiled. Unfortunately there is no simple correct universal answer here. Double transpilation is not safe in general, since choices get made about how to map between modules, AMD, UMD, etc._ - -## App Javascript - -To provide **App Javascript**, a package includes the `app-js` key in **Ember package metadata**. For example, to duplicate the behavior of v1 packages, you could say: - - "ember-addon": { - "version": 2, - "app-js": "./app" - } - -Like the **Own Javascript**, templates are in place in hbs format with any AST transforms already applied. Javascript is in ES modules, using only ES latest features. ECMA static and dynamic imports from any **allowed dependency** are supported. - -By making this an explicit key in **Ember package metadata**, our publication format is more durable (you can rearrange the conventional directory structure in the future without breaking the format) and more performant (less filesystem traversal is required to decide which features the package is using). - -## CSS - -To provide **CSS**, a package can include any number of CSS files. These files can `@import` each other via relative paths, which will result in build-time inclusion (as already works in v1 packages). - -If any of the **Own Javascript** or **App Javascript** modules depend on the presence of a CSS file in the same package, it should say so explicitly via an ECMA relative import, like: - - import '../css/some-component.css'; - -This is interpreted as a build-time directive that ensures that before the Javascript module is evaluated, the CSS file's contents will be present in the DOM. - -> Q: Does this interfere with the ability to do CSS-in-JS style for people who like that? - -> A: No, because that would be a preprocessing step before publication. It’s a choice of authoring format, just like TypeScript or SCSS. - -It is also possible for other packages (including the consuming application) to depend on a CSS file in any of its **allowed dependencies**, from either Javascript or CSS. From Javascript it looks like: - - // This will resolve the `your-addon` package and find - // './some-component.css' relative to the package root. - // The .css file extension is mandatory - import 'your-addon/some-component.css'; - -And from CSS it looks like: - - @import 'your-addon/some-component'; - -What about SCSS _et al_? You’re still free to use them as your authoring format, and they should be transpiled to CSS in your publication format. If you want to offer the original SCSS to consuming packages, you’re free to include it in the publication format too. Since we’re making all packages resolvable via normal node rules, it’s now dramatically easier to implement a preprocessor that supports inter-package dependencies. (The same logic applies to TypeScript.) - -## Assets - -To provide **Assets**, a package includes the `public-assets` key in **Ember package metadata**. It's a mapping from local paths to app-relative URLs that should be available in the final app. - - "name": "my-addon", - "ember-addon": { - "version": 2, - "public-assets": { - "./public/image.png": "/my-addon/image.png" - } - } - -with: - - my-addon - └── public - └── image.png - -will result in final build output: - - dist - └── my-addon - └── image.png - -Notice that we’re _not_ choosing to include assets via explicit ECMA `import`. The reason is that fine-grained inclusion of asset files is not critical to runtime performance. Any assets that your app doesn’t actually need, it should never fetch. - -## ContentFor - -The following targets are supported the same as in v1 packages: - -- head -- head-footer -- body -- body-footer -- test-head -- test-head-footer -- test-body -- test-body-footer -- config-module - -The following targets are deprecated because they tie us permanently to the idea of fixed app/test/vendor Javascript bundles, and because they are not widely used according to the EmberObserver code search: - -- app-boot -- app-prefix -- app-suffix -- test-support-prefix -- test-support-suffix -- vendor-prefix -- vendor-suffix - -## What about Tests? - -v1 packages can provide `treeForTestSupport`, `treeForAddonTestSupport`, and `app.import` with `type="test"`. All of these features are dropped. - -To provide test-support code, make a separate module within your package and tell people to `import` it from their tests. As long as it is only imported from tests, it will not be present in non-test bundles. -​​ - -## Package Hooks - -In today’s v1 addon packages, the `index.js` file is the main entrypoint that allows an addon to integrate itself with the overall ember-cli build pipeline. The same idea carries forward to v2, with some changes. - -It is no longer the `main` entrypoint of the package (see **Own Javascript**). Instead, it’s located via the `build` key in **Ember package metadata**, which should point at a Javascript file. `build` is optional — if you don’t have anything to say, you don’t need the file. - -It is now an ECMA module, not a CJS file. The default export is a class that implements your addon hooks (no base class is required). - -One area that is under-documented and under-designed in the existing hooks is: which ones cascade into active grandchild addons? Do they cascade via `super` so you can (accidentally or on purpose) block the cascade? Section **Active Dependencies** makes these rules consistent and clear. - -List of existing v1 public methods and properties on addons, and their disposition in v2: - -- blueprintsPath: unchanged in v2 -- buildError: Kept. This is an event hook that makes it possible to implement things like ember-cli-build-notifications. -- cacheKeyForTree: Dropped. This is a build-time feature, it doesn’t belong in the publication format. -- config: TODO. -- contentFor: Some of the possible destinations for content are removed. See **ContentFor** section. -- dependencies: Dropped. Can’t find any usages in the wild. -- description: Dropped. This is redundant with the description in package.json. -- import: Dropped. This is replaced with actual ECMA `import` for both Javascript and CSS. -- importTransforms: Dropped, because this goes with `this.import()` above. All examples in the wild that I could find are handled better by other alternatives. - - the CJS and AMD transforms aren’t needed because better packagers can automate the transformation of both, as demonstrated by ember-auto-import - - the fastboot transform is used to neuter whole dependencies in fastboot. This can be handled by ECMA dynamic `import()` instead. - - most other occurrences in the EmberObserver code search are actually addons re-exporting the fastboot transform (because apparently `importTransforms` doesn’t cascade properly). -- included: Unchanged, but it should be needed much more rarely. Today it is mostly used to `this.import()` things, which is not a thing anymore. -- includedCommands: Unchanged. -- init: Dropped in favor of `constructor`, since we’re now talking about a native class. -- isDevelopingAddon: Dropped. This doesn’t belong in each addon’s code, it’s a runtime decision and control over it belongs in ember-cli proper. Under embroider developers can set a comma-separated list of addon package names in the EMBROIDER_REBUILD_ADDONS environment variable instead. -- isEnabled: Dropped. Rarely used. This decision doesn’t belong inside an addon, it belongs in the addon’s parent which will decide to activate it or not. Putting it here means every addon needs to invent its own API for how to tell it to activate or not. -- lintTree: Kept. This is a legit runtime thing to do. -- moduleName: Dropped. Using a moduleName that doesn’t match your NPM package name is a megatroll, and it won’t work with build tools that know how to follow the Node package resolution algorithm. -- name: Dropped. Setting a name that doesn’t match your NPM package name is a megatroll. -- outputReady: Kept. -- postBuild: Kept. -- postprocessTree: TODO. need to confirm existing pre/postprocessTree behaviors. I think most of the trees (js, styles, templates, all) only apply to your immediate parent, meaning they can run at publication time when they’re being applied to an addon. -- preBuild: Kept -- preprocessTree: TODO. Same boat as postprocessTree. -- serverMiddleware: Kept. -- setupPreprocessorRegistry: Kept. But remember, it will have an effect whenever the consuming package is built, which for apps will be the same as today, but for addons will be publication time. -- shouldIncludeChildAddon: Dropped in favor of `activeDependencies` because we’re changing the semantics. This method receives a complete instance representing each child addon, which unintentionally exposes way too much API. And the meaning of being an active dependency has been rationalized. See section **Active Dependencies**. -- testemMiddleware: Kept. -- treeFor, treeForAddon, treeForAddonTemplates, treeForAddonTestSupport, treeForApp, treeForPublic, treeForStyles, treeForTemplates, treeForTestSupport, treeForVendor: Dropped. Dynamically generating broccoli trees at app build time is no longer supported. Your trees are built at publication time. If you need to produce different output at build time based on dynamic configuration, see **Build-time Conditionals**. - -New addon hooks: - -- `activeDependencies`: defined in its own section below - -Finally, your `build` module may export named constants that will be made available to your runtime Javascript. See **Build-time Conditionals** for details. - -## Build-time Conditionals - -The v2 format deliberately moves a lot of dynamic behavior to publication time. So how do we deal with remaining cases where different code needs to be included based on dynamic information? - -You may export named `const` values from your `build` module (as defined in the **Addon Hooks** section). These constants will be available to your Javascript via `import { someConstant } from` `'@ember/build-time-config/your-package-name'`, and we guarantee that a dead-code elimination step can see any boolean constant branch predicates (this is how feature flags already work inside Ember itself). For example: - - import { needsLegacySupport } from '@ember/build-time-config/my-package'; - let MyComponent = Component.extend({ - //.... - }); - if (needsLegacySupport) { - MyComponent.reopen({ - // add some extra code here. It will be stripped from builds that don't need it. - }); - } - export default MyComponent; - -This is also a motivating example for our support of dynamic `imports()`: it allows you to conditionally depend on other JS modules or CSS: - - import { provideDefaultStyles } from '@ember/build-time-config/my-package'; - if (provideDefaultStyles) { - import("../css/default-styles.css"); - } - -Your `build` module is evaluated in Node, not the browser. We just promise that any JSON-serializable constants it exports will get packaged up into the special Ember-provided `@ember/build-time-config` package. - -**Template Build-time conditionals** - -TODO: this section is a rough first pass. Once clarified, it should also get reflected in the other places where we talk about the template publication format. - -We also need build-time conditional capability in templates, because (for example) many of the AST transforms we will be asking addons to pre-apply are supposed to behave differently depending on the Ember version. - -The input data is exactly the same as used for Javascript build-time conditionals (any JSON-serializable constants exported from your build module are available via the `@ember/build-config-config` package). We add a helper for accessing those values: - - {{#if (ember-build-time-config "my-package" "needsOldFeature")}} - ... - {{else}} - ... - {{/if}} - -And we implement a transform in the template compiler that does branch elimination based off the values. - -Note that only Boolean predicates are handled by the dead-code elimination. You can produce Booleans from arbitrary logic in your `build` module (including things like semver tests or feature probing). - -## Active Dependencies - -The `activeDependencies` hook receives the list of names of your **allowed dependencies** that are Ember packages as input and returns either the same list or a subset of the list: - - activeDependencies(childPackageNames) { - if (someThingIsDisabled) { - return childPackageNames.filter(name => name !== 'the-one-we-dont-need'); - } else { - return childPackageNames; - } - } - -If you don’t implement the `activeDependencies` hook, all your `dependencies` are considered active. - -When and only when a package is active: - -- all standard Ember module types (`your-package/components/*.js`, `your-package/services/*.js`, etc) from its **Own Javascript** _that cannot be statically ruled out as unnecessary_ are included in the build as if some application code has `import`ed them. (What counts as “cannot be statically ruled out” is free to change as apps adopt increasingly static practices. This doesn’t break any already published packages, it just makes builds that consume them more efficient.) -- if your **Ember package metadata** contains `"implicit-scripts"` or `"implicit-test-scripts"`, the listed scripts will be included in the consuming app or its tests, respectively. Each of these keys can contain a list of specifier strings that will be resolved relative to the package. This is a backward-compatibility feature for capturing the behavior of v1 packages. New features are encouraged to use direct `import` where possible. - -Example: -"ember-addon": { -"version": 2, -"implicit-scripts": ["./vendor/my-package/some-shim", "lodash/sortBy"] -} -Scripts included this way are _not_ interpreted as ES modules. They are evaluated in script context (think `