From 9393a2216b22d794aa287a25d535a983009b0928 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Sun, 10 Mar 2019 08:00:51 +0100 Subject: [PATCH 1/4] Add initial RFC --- text/0000-addon-module-config.md | 122 +++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 text/0000-addon-module-config.md diff --git a/text/0000-addon-module-config.md b/text/0000-addon-module-config.md new file mode 100644 index 0000000000..be0b0ba259 --- /dev/null +++ b/text/0000-addon-module-config.md @@ -0,0 +1,122 @@ +- Start Date: 2019-03-10 +- Relevant Team(s): Ember CLI +- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) +- Tracking: (leave this empty) + +# Configuring Addon modules in Module Unification layout + +## Summary + +Provide an API for addons to register their own types and collections for Module Unification apps. + +## Motivation + +The Octane layout uses the Module Unification layout described on the [RFC-143](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md), but addons that require apps to locate classes into a non-default app folder will not work. + +For example, the ember-simple-auth addon allows defining the application authenticators on the `authenticators` folder. + +> The authenticator to use is chosen when authentication is triggered via the name it is registered with in the Ember container: + +```js +this.get('session').authenticate('authenticator:custom) +``` + +App developers don’t need to register the authenticator manually into the application container, only to locate the module on the **expected project folder**. + +```js +// app/authenticators/custom.js +import Base from 'ember-simple-auth/authenticators/base'; + +export default Base.extend({ + ... +}); +``` + +In an Octane application, you would likely locate `custom` within `src/authenticators` but this will not work automatically. The Module Unification RFC provides a broader convention for naming and organizing a project's modules, and the options of the application module structure must be set up in the application resolver for MU applications. + +You can read more about the [MU Module Naming and Convention](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md#module-naming-and-organization). + +In Ember, the application resolver defines the lookup rules to resolve container lookups. The Resolver class has been updated to support the MU layout, and the Octane blueprint will generate the following `src/resolver.js`: + +```js + import Resolver from 'ember-resolver/resolvers/fallback'; + import buildResolverConfig from 'ember-resolver/ember-config'; + import config from '../config/environment'; + + let moduleConfig = buildResolverConfig(config.modulePrefix); + + export default Resolver.extend({ + config: moduleConfig + }); +``` + +The config option on the MU resolver is a hash that includes the `types` and `collections` mappings defining the rules to resolve container lookups. Now, an app can update the default resolver configuration to add their types and collections like: + +```js +moduleConfig.collections = Object.assign(moduleConfig.collections, { + // ember-simple-auth + authenticators: { + types: ['authenticator'], + defaultType: 'authenticator' + } +}); +``` + +Because there is not an API for addons to add their types and collections, developers have to add them in the application resolver to make the addon works in an MU application. +The following proposal provides an API for addon authors to add their types and collections in order application developers do not have to configure them. + + +## Detailed design + +The API proposal is to define a new addon hook to define their own types and collections. + +```js +// my-addon/index.js +module.exports = { + name: require('./package').name, + resolverConfig() { + return { + collections: {session: { definitiveCollection: 'session' }}, + types: {translation: { definitiveCollection: 'main' }} + }; + } +}; +``` + +The types and collections for all the application addons will be automatically merged into the default MU types and collections. + +The app will throw an exception if: + +- an addon tries to overwrite a type or collection mapping that is included on the default MU configuration. + +- two addons define the same type or collection. + +For more implementation details, there is an [open PR](https://github.com/ember-cli/ember-resolver/pull/348). + +## How we teach this + +The Octane guides should include a section explaining how to extend the default Octane resolver configuration for application developers or addon authors. + +The "writing addons" tutorial has to document the `resolverConfig` hook. + +## Drawbacks + +The proposal does not allow: + +- two addons to register the same type or collection. + +- an addon to extend the MU types and collections. + +This behaviour can be modified. + +## Alternatives + +1) Don’t change anything and app developers need to register their addon types and collections based on the addon instructions. + +2) Provide a different API than the `resolverConfig` hook. + +Even though it is related, this RFC does not try to define the API to define Module Type and Module Collections on the resolver configuration; other RFC should cover any alternative to this API. + +## Unresolved questions + +The Drawbacks section comments the unresolved questions. From faa01d98879ac513dfaa8ab027fbcb5b9b9acc5d Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Sun, 10 Mar 2019 08:02:38 +0100 Subject: [PATCH 2/4] Fixes --- text/0000-addon-module-config.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/text/0000-addon-module-config.md b/text/0000-addon-module-config.md index be0b0ba259..180448fb90 100644 --- a/text/0000-addon-module-config.md +++ b/text/0000-addon-module-config.md @@ -3,7 +3,7 @@ - RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) - Tracking: (leave this empty) -# Configuring Addon modules in Module Unification layout +# Configuring addon modules in Module Unification layout ## Summary @@ -18,7 +18,7 @@ For example, the ember-simple-auth addon allows defining the application authent > The authenticator to use is chosen when authentication is triggered via the name it is registered with in the Ember container: ```js -this.get('session').authenticate('authenticator:custom) +this.get('session').authenticate('authenticator:custom') ``` App developers don’t need to register the authenticator manually into the application container, only to locate the module on the **expected project folder**. @@ -39,15 +39,15 @@ You can read more about the [MU Module Naming and Convention](https://github.com In Ember, the application resolver defines the lookup rules to resolve container lookups. The Resolver class has been updated to support the MU layout, and the Octane blueprint will generate the following `src/resolver.js`: ```js - import Resolver from 'ember-resolver/resolvers/fallback'; - import buildResolverConfig from 'ember-resolver/ember-config'; - import config from '../config/environment'; +import Resolver from 'ember-resolver/resolvers/fallback'; +import buildResolverConfig from 'ember-resolver/ember-config'; +import config from '../config/environment'; - let moduleConfig = buildResolverConfig(config.modulePrefix); +let moduleConfig = buildResolverConfig(config.modulePrefix); - export default Resolver.extend({ - config: moduleConfig - }); +export default Resolver.extend({ + config: moduleConfig +}); ``` The config option on the MU resolver is a hash that includes the `types` and `collections` mappings defining the rules to resolve container lookups. Now, an app can update the default resolver configuration to add their types and collections like: From 115057eae867b8cdbba531a3d448ca34b5d77a10 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Sun, 10 Mar 2019 08:18:52 +0100 Subject: [PATCH 3/4] Some text changes --- text/0000-addon-module-config.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/text/0000-addon-module-config.md b/text/0000-addon-module-config.md index 180448fb90..cfd7327362 100644 --- a/text/0000-addon-module-config.md +++ b/text/0000-addon-module-config.md @@ -1,17 +1,17 @@ - Start Date: 2019-03-10 - Relevant Team(s): Ember CLI -- RFC PR: (after opening the RFC PR, update this with a link to it and update the file name) +- RFC PR: [#462](https://github.com/emberjs/rfcs/pull/462) - Tracking: (leave this empty) # Configuring addon modules in Module Unification layout ## Summary -Provide an API for addons to register their own types and collections for Module Unification apps. +Provide an API for addons to configure their module types and collections for Module Unification apps. ## Motivation -The Octane layout uses the Module Unification layout described on the [RFC-143](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md), but addons that require apps to locate classes into a non-default app folder will not work. +The Octane layout uses the Module Unification layout described on the [RFC-143](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md), but at this moment classic addons that require apps to locate classes into a non-default app folder do not work "out of the box" in an Octane application. For example, the ember-simple-auth addon allows defining the application authenticators on the `authenticators` folder. @@ -21,7 +21,7 @@ For example, the ember-simple-auth addon allows defining the application authent this.get('session').authenticate('authenticator:custom') ``` -App developers don’t need to register the authenticator manually into the application container, only to locate the module on the **expected project folder**. +App developers only need to locate the module on the **expected project folder** to make the addon work. ```js // app/authenticators/custom.js @@ -32,9 +32,9 @@ export default Base.extend({ }); ``` -In an Octane application, you would likely locate `custom` within `src/authenticators` but this will not work automatically. The Module Unification RFC provides a broader convention for naming and organizing a project's modules, and the options of the application module structure must be set up in the application resolver for MU applications. +In an Octane application, you would likely locate `custom` within `src/authenticators` but this will not work **automatically**. -You can read more about the [MU Module Naming and Convention](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md#module-naming-and-organization). +The Module Unification RFC provides a broader convention for naming and organizing a project's modules, and the options of the application module structure must be set up in the application resolver for MU applications. You can read more about the [MU Module Naming and Convention](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md#module-naming-and-organization). In Ember, the application resolver defines the lookup rules to resolve container lookups. The Resolver class has been updated to support the MU layout, and the Octane blueprint will generate the following `src/resolver.js`: @@ -62,13 +62,13 @@ moduleConfig.collections = Object.assign(moduleConfig.collections, { }); ``` -Because there is not an API for addons to add their types and collections, developers have to add them in the application resolver to make the addon works in an MU application. +Because there is not an API for addons to add their module types or collections, developers have to add them in the application resolver to make the addon works in an MU application. The following proposal provides an API for addon authors to add their types and collections in order application developers do not have to configure them. ## Detailed design -The API proposal is to define a new addon hook to define their own types and collections. +The API proposal provides a new hook `resolverConfig` for addons to define their module types and collections. ```js // my-addon/index.js @@ -103,9 +103,9 @@ The "writing addons" tutorial has to document the `resolverConfig` hook. The proposal does not allow: -- two addons to register the same type or collection. +- an addon to extend the Module Unification types and collections. -- an addon to extend the MU types and collections. +- two addons to register the same type or collection. This behaviour can be modified. From 3288a1aab6e1cb987498e9c81aee148038ddb19c Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Sun, 10 Mar 2019 20:55:36 +0100 Subject: [PATCH 4/4] Remove Octane references Module Unification is being descoped from Octane --- text/0000-addon-module-config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0000-addon-module-config.md b/text/0000-addon-module-config.md index cfd7327362..ef7317ae06 100644 --- a/text/0000-addon-module-config.md +++ b/text/0000-addon-module-config.md @@ -11,7 +11,7 @@ Provide an API for addons to configure their module types and collections for Mo ## Motivation -The Octane layout uses the Module Unification layout described on the [RFC-143](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md), but at this moment classic addons that require apps to locate classes into a non-default app folder do not work "out of the box" in an Octane application. +The Module Unification layout is described on the [RFC-143](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md). At this moment Classic addons that require apps to locate classes into a non-default app folder do not work "out of the box" in an Module Unification application. For example, the ember-simple-auth addon allows defining the application authenticators on the `authenticators` folder. @@ -32,11 +32,11 @@ export default Base.extend({ }); ``` -In an Octane application, you would likely locate `custom` within `src/authenticators` but this will not work **automatically**. +In an Module Unification application, you would likely locate `custom` within `src/authenticators` but this will not work **automatically**. The Module Unification RFC provides a broader convention for naming and organizing a project's modules, and the options of the application module structure must be set up in the application resolver for MU applications. You can read more about the [MU Module Naming and Convention](https://github.com/emberjs/rfcs/blob/master/text/0143-module-unification.md#module-naming-and-organization). -In Ember, the application resolver defines the lookup rules to resolve container lookups. The Resolver class has been updated to support the MU layout, and the Octane blueprint will generate the following `src/resolver.js`: +In Ember, the application resolver defines the lookup rules to resolve container lookups. The Resolver class has been updated to support the MU layout, and the blueprint will generate the following `src/resolver.js`: ```js import Resolver from 'ember-resolver/resolvers/fallback'; @@ -95,7 +95,7 @@ For more implementation details, there is an [open PR](https://github.com/ember- ## How we teach this -The Octane guides should include a section explaining how to extend the default Octane resolver configuration for application developers or addon authors. +The guides should include a section explaining how to extend the default resolver configuration for application developers or addon authors. The "writing addons" tutorial has to document the `resolverConfig` hook.