Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

v2 Addon Format (Embroider compatibility) #507

Open
wants to merge 4 commits into
base: master
from

Conversation

Projects
None yet
6 participants
@ef4
Copy link
Contributor

commented Jun 22, 2019

Rendered.

Edward Faulkner
@NullVoxPopuli

This comment has been minimized.

Copy link
Contributor

commented Jun 22, 2019

is it going to be flexible enough to handle a structure change? like maybe future src top level directory for addons and apps?


In many cases, converting addons to v2 makes them simpler. For example, today many addons use custom broccoli code to wrap third-party libraries in a fastboot guard that prevents the libraries from trying to load in Node (where they presumably don’t work). In v2, they can drop all that custom build-time code in favor of a macro-guarded `importSync`.

This design does _not_ advocate loudly deprecating any v1 addon features. Doing that all at once would be unnecessarily disruptive. I would rather rely on the carrot of faster builds and Embroider stability than the stick of deprecation warnings. We can choose to deprecate v1 features in stages at a later time.

This comment has been minimized.

Copy link
@jenweber

jenweber Jun 23, 2019

Contributor

Some additional points to cover in this section:

  • Where to document this system (CLI guides)
  • How to divide up the learning: general overveiw, change tutorial for new addons, write a tutorial for addon authors to help them migrate their addons, a tutorial for configuration that app users can reference if they run into problems with their addons, and abilities that unlock by having webpack compat. We would also need to revise some existing materials for regular ember-cli builds so that we appropriately present both options. (side note, what would we actually recommend as the happy path).
- a layered build system with clearly documented APIs between the layers, so it's easier to experiment and contribute
- a build system that can take advantage of current and future investments by the wider Javascript ecosystem into code bundling & optimization.

## Key Ideas

This comment has been minimized.

Copy link
@jenweber

jenweber Jun 23, 2019

Contributor

This section would benefit from a link to an existing, Embroidered Ember app or two (Octane + Super Rentals) and an addon (???). The necessary detail in this RFC makes it sound very complicated to use Embroider, while the median experience is pretty straightforward.

@ef4

This comment has been minimized.

Copy link
Contributor Author

commented Jun 23, 2019

is it going to be flexible enough to handle a structure change? like maybe future src top level directory for addons and apps?

There are two levels of indirection that make it flexible.

One is that this is a publication format, not an authoring format. But I don't think that's a totally satisfying answer, because there will be a natural desire over time to make the two conform more closely.

The other indirection is that no directories in this format are hard-coded. For example, to use a feature like App Javascript, there's no special directory. Instead there's a property in package.json (ember-addon.app-js) that you can point at any directory in the package.

But there is a hard rule here: whatever paths you publish to NPM in your package, those are the actual paths your users can import from. That is an area where too much flexibility has been bad for us, and we need to follow a clear standard.


**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.

This comment has been minimized.

Copy link
@buschtoens

buschtoens Jun 27, 2019

I recognize that we want to keep devDependencies as an allowed dependency for apps, since this is how it's always been conventionally for Ember apps and we want to reduce churn as much as possible.

Out of curiosity I would still like to understand, why it ever was this way. Is it just a side-effect of the fact that apps are always the root of any given project and thus will always have access to devDependencies?

I would argue that, while still officially supporting it, we should discourage adding runtime dependencies for apps to devDependencies instead of dependencies, for the following reasons:

  • It is confusing for Ember newbies.
  • It is inconsistent.
  • When I turn an app into an engine (an addon) or extract certain parts of an app into an addon (or engine), devDependencies suddenly turn into dependencies, just because the code was moved.

Instead, I would recommend that we encourage the same mental model for apps and addons. Everything that needs to be available at runtime / should influence the production build (an allowed dependency), has to be a dependency. Everything else, like testing or development support, linters, etc. are devDependencies.

What is your opinion regarding this?

If you agree, we could have an opt-in flag to enforce the same semantics for apps and addons.

This comment has been minimized.

Copy link
@chriskrycho

chriskrycho Jun 27, 2019

Contributor

I strongly agree with this but would go a step further: if at all possible, I would very much like to see us get to a world where devDependencies and dependencies mean what they sound like: the latter is genuinely runtime-only, the former genuinely development- and build-time only.

It’s possible there are reasons that cannot be the case, in which case I’d love clarification there, because my understanding of the three-phase build pipeline for Embroider suggests that precisely that distinction should be possible. But I very well may be missing something!

This comment has been minimized.

Copy link
@ef4

ef4 Jun 27, 2019

Author Contributor

Yes, for addons the distinction gets quite strong under this RFC. And it will reduce the number of packages needed by apps (count how many copies of ember-cli-htmlbars and ember-cli-babel you have).

For apps, I agree with:

we should discourage adding runtime dependencies for apps to devDependencies instead of dependencies

But most apps don't have any runtime dependencies. If you do ember b, and then rm -rf node_modules, and then serve dist to a browser, your app still runs. There are no runtime dependencies. Your addons may be used at runtime, but the actual addon NPM packages are only needed during the build.

The exception is Fastboot. Fastboot does imply having some runtime dependencies. Using dependencies for this would simplify and improve fastboot, which today tries to generate a whole separate package.json.

Draggha and others added some commits Jul 1, 2019

Edward Faulkner
spec change: explicit .hbs is no longer required
In the process of implementing TypeScript support in Embroider, I realized we really need to required stage3 to accept customized resolvable file extensions. And once we have that, we may as well use it for .hbs too, at which point the explicit extension is not important anymore.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.