Ember’s conventions for challenge format and file naming are central to the
developer expertise. It is essential that we get each the technical and
ergonomic particulars proper. I needed to offer an replace about Module
Unification and our plans for the file construction in Ember Octane.
In brief, we don’t plan to ship Module Unification in Octane. As a substitute,
Octane will ship with at the moment’s file system format, with one change: assist
for nested parts in <AngleBracket /> invocation syntax
As a result of Octane apps will proceed with at the moment’s file system format, we need to
tackle the biggest barrier to <AngleBracket /> adoption at the moment: parts
nested inside different directories.
For instance, in case you have a element positioned at
app/parts/icons/download-icon.js (i.e., nested inside an icons
listing), you’ll be able to invoke it with curly invocation syntax like this:
Nevertheless, it isn’t attainable to invoke the identical nested element with angle
bracket syntax with out resorting to clunky workarounds.
As proposed within the Nested Invocations in Angle Bracket Syntax
RFC, we plan to deal with this by including assist for
nested parts through the :: separator.
With this proposal, the element described above might be invoked with angle
bracket syntax like this:
<Icons::DownloadIcon />
As a result of it is a small change, it may be carried out rapidly with out
requiring us to delay the Ember Octane launch.
Standing of Module Unification
Provided that the Module Unification RFC was merged in late 2016, and we talked
about transport Module Unification within the 2018 Roadmap RFC,
it is truthful to ask what occurred and why we’re making this resolution now.
Heads up: this submit will get lengthy and detailed, so when you solely care concerning the
plan going ahead, you’ll be able to safely skip the remainder.
Within the spirit of transparency and overcommunication, although, I needed to
share just a little little bit of the historical past and evolution of MU from my perspective.
Let’s name the file system format that Ember apps use at the moment the “basic”
format. Whereas this construction has served us nicely, it additionally has a number of
shortcomings.
Within the basic format, recordsdata are grouped by sort, not by title. Typically,
because of this carefully associated recordsdata (like a element and its template) are
separated from one another, and navigating between them might be irritating.
Ideally, associated recordsdata can be shut to one another within the file system. For
instance, you might have considered trying an Ember Knowledge mannequin and its related serializer to be
co-located in the identical listing.
Early on, Ember CLI carried out an experimental “pods” format that grouped
recordsdata by title moderately than by variety. For instance, a Person mannequin and its
serializer can be grouped collectively in app/consumer/, as mannequin.js and
serializer.js respectively.
Suggestions from the group was that pods felt extra productive than the
basic format. Nevertheless, pods had a number of issues that wanted to be
addressed earlier than it might be enabled by default.
The hassle to deal with the design flaws of pods led to the Module Unification
RFC, a ground-up rethink of how the file system ought to work in Ember
apps. Importantly, this design grappled with overhauling Ember’s resolver and
dependency injection methods as nicely, which was simply as necessary as
shuffling round the place specific recordsdata went on disk.
The MU RFC was merged on the finish of 2016, however new Ember apps are nonetheless
generated with the basic format. So, why cannot we flip the swap on
enabling Module Unification-style format by default at the moment?
Keep in mind that MU described not only a new file system however a major
overhaul of Ember’s resolver. Implementing MU was a large initiative that,
whereas usually hidden, touched practically each a part of the framework. Regardless of this
giant scope, and because of the unimaginable period of time and power our
group dedicated to the work, MU implementation has made nice progress, and
practically all the pieces wanted to make Module Unification work has landed in Ember.
Almost all the pieces. Once we merged the Roadmap RFC final yr, there was one
final main piece of MU that also wanted to be designed: element
namespacing, or the way to seek advice from parts that come from different addons in
templates.
Whereas we had a plan, a shift within the JavaScript ecosystem despatched us again to the
drafting board. And the tougher we labored on fixing this final piece, the extra
we realized that basic elements of the general design wanted to be
rethought.
Namespaces and Scoped Packages
Apart from recordsdata being unfold out, one other drawback with the basic format is
that all the pieces goes into one massive world pool of names.
So, for instance, Ember Knowledge defines a service known as retailer that you could
inject into parts and companies. Should you set up one other addon that additionally
has a service known as retailer, there is no simple method to make use of each.
Equally, in case your app has a element known as small-button and you put in
an addon that additionally has a element known as small-button, you don’t have any approach to
inform Ember which one you imply whenever you sort {{small-button}} in a template.
One of many key advantages of the MU design is that names are not world,
however namespaced to the package deal the place they arrive from. So, for instance, if an
npm package deal known as ember-ui-library comprises a element known as
small-button, the MU RFC proposed referring to it in your template like
this:
...
Across the identical time we have been designing MU, nevertheless, npm introduced assist
for scoped package deal names. Previous to this variation, npm package deal
names have been restricted to alphanumeric characters and dashes. Now, although,
packages might begin with an @ and comprise a /, like
@glimmer/element.
Part invocations with scoped packages blew previous the verbosity restrict. We
merely couldn’t convey ourselves to simply accept a syntax that generally produced
code like this:
...
We additionally had considerations that this was complicated to scan visually, contemplating
that @ already means a element argument and / already means a closing
tag.
Whereas Ember had been utilizing it for years, round this time JavaScript module
syntax (import Publish from './submit') began gaining vital traction in
the broader ecosystem, together with instruments like webpack that would use these
modules to carry out code splitting.
After scoped npm packages scuttled our unique plan for namespaced
parts, we went again to the drafting board, and one thing just like
JavaScript’s import appeared like a promising resolution. Nevertheless, we
instantly hit some challenges whereas exploring this concept.
The idea of a “element” in Ember is not a singular factor, however the union
of a template and a element class. With the element and template in
separate recordsdata, it is not clear which one you are alleged to import. As a result of
of this, we needed one thing the place you’d import a element by title
(my-component), not a particular file like in JavaScript.
However regardless of the variations, the general idea of importing modules was
comparable. We needed to discover a syntax that might give customers who already knew
JavaScript an instinct concerning the similarities, whereas not making it look so
comparable that individuals can be misled into pondering it was actually the identical
factor.
We tried to discover a steadiness between these two constraints with a syntax that
regarded like this:
We hoped that it regarded comparable sufficient to JavaScript’s import syntax to
provide you with a clue about what it was doing, however by adopting the use key phrase
as a substitute of import, sign that this was not precisely the identical as JavaScript
modules.
Matthew Beale poured vital time into capturing all of those conflicting
constraints within the Module Unification Packages RFC, however, even after
months of debate, we could not come to consensus and the RFC was by no means
merged.
Regardless of everybody agreeing this was an pressing drawback, we could not persuade
ourselves that having completely different module methods for JavaScript and templates
was a viable resolution. Sadly, there wasn’t an apparent various
plan, and never having a solution meant MU was indefinitely blocked till we
might work out this final piece of the puzzle.
We felt caught.
Actual-World Suggestions
Within the meantime, sufficient of Module Unification was transport behind characteristic
flags (and in Glimmer.js) that we have been capable of get suggestions from early
adopters. Whereas general individuals actually preferred the brand new file system and actually
appreciated not coping with irritating title collisions, one thing felt
off.
One frequent theme within the suggestions was that MU felt too inflexible and often
obtained in the way in which of easy duties. To grasp why, it is necessary to
perceive that MU is about greater than a file system. MU can be a system
for controlling scope.
For instance, a characteristic of MU is the power to have non-public parts that
do not leak into the remainder of the app. If now we have a element known as
list-paginator and it has a baby element known as paginator-control, MU
permits us to prepare them like this:
src
├── ui
│ ├── parts
│ │ └── list-paginator
│ │ ├── paginator-control
│ │ │ ├── element.js
│ │ │ └── template.hbs
│ │ ├── element.js
│ │ └── template.js
On this instance, the list-paginator template can invoke
{{paginator-control}} to render its youngster element. Nevertheless, when you attempt to
invoke {{paginator-control}} from any template exterior the list-paginator
listing, you may get an error. In different phrases, paginator-control is
native to list-paginator.
MU, then, is about scope, and controlling who has entry to what. The place a
module lives within the MU file system determines what it could see to and who
else can see it.
It is a intelligent concept that eliminates a variety of boilerplate. If you need to
set up your recordsdata anyway, and if you wish to group associated issues collectively
anyway, it is sensible to attempt to create a single system that solves
group and scoping on the identical time.
In follow, although, we bumped into a number of challenges:
- This concept is just not frequent within the JavaScript ecosystem, so the file system
controlling scope is not intuitive for brand spanking new learners. In addition they need to
memorize these naming guidelines, that are implicit and get fairly advanced. - Equally, ecosystem instruments do not perceive MU. We now have to construct customized
integrations to get issues like “Go to Definition” to work in IDEs or code
splitting to work in webpack, that different libraries get at no cost. - JavaScript recordsdata in Ember use module syntax, which does not undergo the
MU system, including to the confusion. Having one system in a element’s
JavaScript and one other in its template is just not preferrred. - When file names and places are so significant, it may be irritating
if you wish to create a file that is not a part of the MU world. Duties that
are usually trivial, similar to extracting utility capabilities right into a separate
file or grouping associated recordsdata collectively in a listing, can simply flip
right into a battle the place your construct begins erroring since you’re not taking part in
by the MU guidelines.
A Private Anecdote
Personally, this final one was what actually triggered me to step again and
re-evaluate our plan for MU. It occurred throughout a challenge at work the place we
have been utilizing each Glimmer.js (with Module Unification) and Preact.
Because the variety of parts grew, a co-worker created a listing known as
icons within the Preact app to carry the entire parts for rendering
completely different SVG icons. I am certain it did not take quite a lot of minutes to
create the listing, drag the suitable element recordsdata in, and replace the
paths in all places these parts have been imported. (Actually, VS Code in all probability
up to date the import paths robotically.)
Once we tried to do the identical factor within the Glimmer app, it was a a lot
completely different expertise that became an hours-long slog. And regardless of all of the
nice issues it does do, MU does not actually have a approach to do this sort of
light-weight grouping.
We might have discovered a workaround. We might have extracted the SVG icon
parts right into a separate package deal, or created a higher-order element that
wrapped the entire youngster icon parts. Nevertheless it appeared ridiculous to burn so
a lot time on the lookout for a “workaround” to carry out a job that felt prefer it
ought to have been (and was, in Preact) trivial.
I knew, intellectually, the advantages of MU. I knew how rigorously it was
designed to implement construction and consistency as your utility grew and
had completely different engineers of various expertise ranges engaged on it. (Certainly,
by the top of the challenge, I discovered the Glimmer app a lot simpler to navigate,
whereas the Preact app had a number of inconsistently-followed conventions.)
However I by no means forgot how viscerally dangerous it felt to have my co-workers combat so
onerous to do one thing that felt prefer it ought to be really easy.
So this was the established order final yr. We have been all extremely annoyed that
we could not make progress on the scoped package deal drawback, however I used to be much more
overwhelmed making an attempt to determine what, if something, to do concerning the detrimental
experiences my co-workers had had when utilizing MU.
Discovering issues in a design you have been engaged on for thus lengthy is
painful, particularly in circumstances like this the place the vast majority of the work was
already full, and we thought we have been so near the end line.
Programming language and API design is basically onerous. Typically I learn outdated RFCs
and marvel at how apparent the answer appears now, in distinction to the weeks,
months, or years I do know it took to tease it out from the thousands and thousands of attainable
options.
Once you’re making an attempt to steadiness so many competing constraints, generally a
small change is all it takes to get you out of a design conundrum you have
struggled with for months. On this case, that change was angle bracket
element invocation.
One factor making JavaScript imports tough to make use of with templates was the
constraint that parts needed to have a touch of their title. Sadly,
dashes aren’t legitimate in JavaScript identifiers, so one thing like import produces a syntax error.
some-component from './some-component'
Angle bracket parts, alternatively, begin with a capital letter to
disambiguate themselves from regular HTML tags: <MyComponent /> as a substitute of
{{my-component}}. Most significantly, there is no sprint.
Because the Ember group began utilizing angle bracket syntax, early suggestions was
very optimistic. Impulsively, JavaScript import syntax was again on the
desk.
The Path Ahead: Template Imports
Talking for the Ember.js core crew, we try to get higher at updating
the group when plans have modified however the brand new plan is not totally locked in
but. So, take into account this a type of conditions.
We all know that the precise plan for Module Unification (MU), as described within the
unique RFC, might want to change. The way it adjustments is just not but sure,
however we imagine that among the issues we needed to resolve with MU are
higher solved with template imports.
With template imports, we intend to make templates play properly with
JavaScript, so you should use the import characteristic you already know and love. By
having parts and helpers be modules you’ll be able to import, we are able to remove the
most advanced components of Module Unification so it is simpler to be taught and use.
We lately posted the SFC & Template Imports RFC,
which describes among the low-level APIs wanted in Ember to make template
imports attainable.
Studying from previous errors, this RFC focuses on the primitives so we are able to
rapidly experiment, get suggestions, and iterate on template import proposals in
addons, earlier than stabilizing them within the core framework.
Whereas the Ember.js core crew has reached consensus that template imports are
the supposed path ahead, please word that the present RFC solely covers
low-level primitives, not the API that might be utilized by Ember builders to
creator templates.
Right here is one instance of a very hypothetical template imports syntax:
---
import UserProfile from './user-profile';
import UserIcon from './icons/consumer';
---
<h1></h1>
<UserIcon />
<UserProfile @userId= />
The syntax is up within the air and can nearly actually be completely different from this
instance. Regardless, it exhibits the good thing about template imports clearly: we have
imported two parts—UserProfile and UserIcon—similar to how we’d
seek advice from every other JavaScript module. This makes it very simple for
everybody—from developer who’re new to Ember, to IDEs, and different tooling in
the JavaScript ecosystem—to know what got here from the place.
You possibly can even think about an (once more, very hypothetical) single-file element
format that locations the template proper throughout the element’s class. Right here, a
unified imports resolution feels particularly pure:
// src/ui/parts/blog-post.gbs
import Part from '@glimmer/element';
import UserIcon from './icons/consumer';
export class BlogPost extends Part {
weblog = { title: 'Coming quickly in Octane', authorId: '1234' };
<template>
<h1>{{this.weblog.title}}</h1>
<UserIcon />
<UserProfile @userId={{this.weblog.authorId}} />
</template>
}
Once more, the precise syntax is up within the air and can nearly actually be
completely different from this instance. The good thing about exposing the low-level primitives
first is that we are able to check out a number of competing designs comparatively simply
earlier than comitting. And when you don’t love what we finally determine on, you’ll be able to
construct an alternate that’s simply as secure because the default implementation.
However word that template imports are usually not a substitute for MU. They do not assist
with issues like higher isolation of an addon’s companies, or a extra intuitive
file system format. As a substitute, we hope that template imports will higher remedy
one side of MU, so the general design might be simplified and its advantages
can shine via extra clearly.
Template imports additionally give us an excellent alternative to attempt to tackle the
ergonomic issues individuals reported when making an attempt MU.
With out template imports, we needed to depend on MU to resolve element names,
which means the recordsdata within the src/ui/parts listing needed to comply with strict
guidelines. However with template imports, customers can simply inform us which module on
disk they need. We will skip resolving parts via MU altogether, and
let Ember customers set up their element recordsdata nevertheless they need.
As irritating because it was on the time, the shortcoming to make progress on MU
might have been a blessing in disguise. It gave us time to implement angle
bracket syntax for parts, which allowed template imports to appear
possible once more—which implies we now have an answer that appears to deal with each
the scoped package deal drawback and the ergonomics drawback. Even higher, template
imports make issues like treeshaking and code-splitting in
Embroider a lot simpler.
I imagine the dead-end we discovered ourselves in was an indication from the universe
that one thing higher was simply across the nook. Time will inform, however my
hunch is that template imports remedy these necessary issues way more
elegantly than what we had earlier than. This course of additionally pushed us to discover
single-file parts, which I feel might be a surprisingly massive productiveness
enchancment for Ember builders.
Whereas we’re enthusiastic about template imports, we need to preserve our promise to
end what we began. We’re prioritizing Ember Octane and ensuring that
our first version is a cultured, cohesive expertise. Solely as soon as Octane is out
the door will we flip our consideration to new initiatives like template imports.
Hopefully, this submit helps present some context concerning the state of MU. Of
course, what I’ve written right here is my private, imperfect recollection of
occasions, simplified for readability. The fact of technical design is messy and
feels much more like going round in circles than the tidy sequence I’ve
introduced right here.
I will even point out that, as a challenge, I feel we have dramatically improved
how we design, implement, validate, and iterate on options since we
initially began the Module Unification RFC. The MU RFC is the final of the
proposals from the “mega-RFC” period, the place we had an inclination to do a ton of
upfront design and implementation earlier than we had any suggestions from actual customers.
These days, I feel we’re quite a bit higher about ensuring RFCs are comparatively
small and centered on doing one factor. We additionally are likely to prioritize exposing
hooks or different primitives that allow us take a look at out new concepts in addons. This
permits us to enhance designs primarily based on early suggestions, with out the strict
stability necessities that include touchdown one thing within the framework
correct.
This has labored nicely for issues like ember-decorators and Glimmer
parts, the place actual world suggestions and the power to make breaking
adjustments primarily based on that suggestions was essential. I am hopeful {that a} comparable
technique for template imports might be simply as profitable.
My honest because of everybody who has labored so onerous on MU and associated
efforts. I am proud to be a part of a group that refuses to cost forward
with one thing we all know is not proper. Ember’s longevity is, at the very least partially,
defined by our willingness to make these sorts of onerous selections.
I am so enthusiastic about Ember, our roadmap, and the newfound power in our
group. In 2019, a thriving Ember is extra necessary for the net than ever.
Thanks for being part of our group, and I hope to see you at
EmberConf in a number of weeks. It is gonna be an excellent one.
