ember-engines / ember-engines.com

Step-by-step guides for using the ember-engines to create composable apps

Ember Engines guides

This repository holds the guides and tutorials for Ember Engines, a powerful addon that allow multiple logical applications to be composed together into a single application from the user's perspective.

Prerequisites

You will need the following things properly installed on your computer.

• Git
• Node.js (with npm)
• Ember CLI

Local Development

The Ember Engines Guides is a normal Ember application, so if you want to run it locally you follow the standard steps:

• Clone this repository
• cd ember-engines.com
• yarn install
• ember serve
• Visit your app at http://localhost:4200.

If you then edit the Markdown files located in the markdown/guide folder your application should live-update with the content changes.

How this app works

The guides content is in the form of Markdown files in the guides directory. An Ember app processes and serves the Markdown files. If you look at the app directory, you'll see there's not much in it! That's because most of the work is done through a dependency on ember-fr-markdown-file and ember-cli-showdown, to separate markdown files and transform him into valid HTML.

Contributing

Do you know a thing or two about the Ember Engines or addons? Do you wish you knew a thing or do? We'd love to have your help with writing or reviewing to make sure that content is helpful to all knowledge levels. If you're new to writing Markdown, follow this cheat sheet.

Overall project status and tasks that need help are tracked in this Quest issue. Have a read through that and the CONTRIBUTING.md file in order to get started.

Adding more things to the table of contents

See table-of-contents.js in guide engine on this repo. Whatever page added must be named with file name under each topic.

Deploying

Deployments automatically happen once changes have been merged into master. So, make sure you test your changes!

ember-engines.com's Issues

Questions/remarks regarding the migration/deprecation guide

I feel it's not really clear what's actually being deprecated. If you analyse the before and after examples you kind of get the gist of it, but I feel the copy itself could be clearer. Maybe something like:

Defining a dependency on the host's router service as router has been deprecated. Please specify an alternative name. E.g. { 'host-router': 'router' }.

The guide also mentions: we don't want to automatically create either of these services.
Which other service is the guide talking about?

The after example also contains a syntax error: { 'host-router'}: 'router', and I think we should also update the engine name from superBlog to 'super-blog' as camelized engine names are also deprecated (which we should probably also add to the guides?).

Lazy engine doesn't handle query params properly

I stumbled upon that the lazy engine cannot handle the query params very well.

For example, a host app mounted an engine as blog, so /blog will load this engine lazily. Then:

1. If we input /blog?foo=123 directly, BlogController.foo will be null, but it should be 123.
2. If we transition to /blog?foo=123 from the host app, then BlogController.foo will be 123.

Not sure if this is a bug or intentional.

Expose dependency checking

Explain the manual verification of dependencies that is needed right now.

Markdown is not woking as expected

Hi guys
The markdown is working fine on GitHub repo - https://github.com/ember-engines/ember-engines.com/blob/master/tests/dummy/app/templates/docs/bundling.md

but it doesn't work on site or local - https://ember-engines.com/docs/bundling

any idea why it's happening?

cc: @gabrielcsapo @locks

migrate markdown resolver usage to other docs tool

Tools we should consider using for generating the docs in this project:

• ember-cli-addon-docs
• broccoli-static-site-json

Per @villander , this isn't a top priority, but would be nice to have.
@buschtoens graciously offered to help convert to ember-cli-addon-docs 😄

Exporting engine addon services to application?

I have an in-repo-engine that can provide its own service to the root application. However I'm unable to use any services provided by addons within my engine. TLDR:

Engine Service -> Application -> OK
Addon Service -> Application -> OK
Addon Service -> Engine -> OK
Addon Service -> Engine -> Application -> NOT OK

In this specific case I was working on an authentication engine that handled user login/password reset etc, and provided a 'session' service that determined if the user was authenticated or not. The session service is provided by the ember-simple-auth addon. I've tried providing the dependency for ember-simple-auth to both the application and engine, but what I end up with appears to be a duplicate service, not a singleton.

What I'm seeing is that there is no way to provide a shared service from an addon within an engine with the root application. This is unfortunate because it means I can't constrain the domain concerns of 'user authentication' within my auth engine. Is this something that is possible with the current ember engines? Is this a desirable behavior engine will ever support?

standard highlighting for shell examples confuses me

This is markdown nitpicking but would be a nice to have if someone wants to contribute.

If you take a look at some of the embedded markdown, the shell examples are not specified as bash and so the keyword highlighting looks distracting to me.
Check out the create an engine page .

solutions

i. disable highlighting for these ones?
ii. ensure all examples are labeled and this repos styles match?

Creating an Engine page includes fingerprinted reference to engine.js

On http://ember-engines.com/guide/creating-an-engine, I'm seeing

Finally, to make this addon an actual Engine, create a engine-9a8730385358089493240e80cecd95bf.js file under the addon directory:

I'm assuming from looking at the markdown file that this should just be a reference to engine.js, not engine-9a8730385358089493240e80cecd95bf.js. Strangely, some of the other references to engine.js in this file don't have the same problem.

Move CDN from heroku to github pages

@stefanpenner would you be able to help out with this?

Fix deploy to heroku

We currently can’t debug why the docs won’t deploy to heroku.

@dgeb @trentmwillis would you be able to assist?

Add more real use cases with host app & engines

Include a few examples that lists a host app and engines, as well a few dependencies (common and shared) to illustrate points.

Lazy loading - ember-engines/ember-engines#154 (comment)

Quest: Ember Engines Guides MVP Tracking issue

Hello and thanks so much for helping out with the Ember Engines Guides! We need the knowledge you've gained over the years using ember-engines

High level tracking, in progress:

This section is purely for tracking how much work we still have left to do, in a very broad sense.

General

• Almost all docs from README should be moved to ember-engines.com. Having similar but different info in both places is confusing and unmaintainable. [ issue ember-engines/ember-engines/issues/540 ]

• Clarify the philosophy and intended uses for engines. [ issue #57 ]

  Is the "Why Use Engines?" section on http://ember-engines.com/ sufficient?

• Update the "Engines Roadmap" section [ issue #56 ]

  Link to the 1.0 Roadmap

• Include a section on using engines with Fastboot. [ issue #58 ]

• Testing section is completely blank. We need to discuss what's possible today. [ issue #59 ]

• Make Ember Engines more public for beginners in Ember.js [ issue ember-learn/guides-source/issues/701 ]

• Upgrade documentation with Ember CLI Addon Docs, improving UX [ issue #50 ]

Building Engines

• Clarify that engines should always be built together with their host app and other engines, regardless of whether they are lazy or eager. This is required for hosts to understand and properly bundle engine dependencies and routes. [ issue #56 ]

• Explain what will happen when there are dependency mismatches between different engines and/or their host app. [ issue #60 ]

• Explain the dependency deduping that is currently performed. [ issue #16 ]

• Explain the manual verification of dependencies that is needed right now. [ issue #61 ]

• Include a few examples that lists a host app and engines, as well a few dependencies (common and shared) to illustrate points. [ issue #62 ]

Make docs a standalone application.

Migrate docs usage into the main application and do not leverage the dummy app for docs

Re-exporting an in-repo addon?

In Sharing Components and More:

The EngineAddon base class hooks into Ember-CLI's build hooks to automatically re-export addon code into your Engine.

I understand that it works with standalone addons. But what about in-repo addons? What should I do in my package.json if I want EngineAddon to re-export it?

Also, if my component comes with a template, is it going to work? Can templates be imported and exported?

Thanks!

Update guides to use the Engine blueprints

Ref ember-engines/ember-engines#387 (review)

Accidentally fingerprinting of documentation text

On this page:

https://ember-engines.com/docs/lazy-loading

The text reads:

Lazy engines are built in the same way as eager engines, but their assets are not combined back into the host application's vendor-b8fae49b3b61342eec0bbbd72949609f.js file. This means that they are run through a separate and unique build process from what a default addon will go through, though it reaches out to the upstream implementation in Ember CLI where possible.

Most likely, broccoli-asset-rev saw the string vendor.js and tried to helpfully replace it with a fingerprinted version for you.

There's not much to be done upstream in broccoli-asset-rev, it uses a fundamentally unsound strategy. You can probably play tricks, like I think you can set outputPaths.vendor.js on your EmberApp to a name other than vendor.js so your own vendor file will have a different name that doesn't match the docs.

Clarify the philosophy and intended uses for engines

Ember Engines just want to separate a big app into many apps manually to isolation concerns
& responsibilities, one type of microservices on front-end with emberJS.

the docs need to make sure to de-emphasize code-splitting / lazy-loading a bit
I think engines have been overused for this because they have been the only way to achieve it
and this will change with embroider

Strange heading

Looks like something that's autogenerating headings is hashing a title in this section?

Use ember-cli-addon-docs for built site

The current site does not allow us to search for information and is cumbersome. When you click into a section, it does not maintain a left rail of all the other options. What are the thoughts on using the default https://github.com/ember-learn/ember-cli-addon-docs to get a better user experience with the docs?

Include a section on using engines with Fastboot

We need add a sections of how Engines works out of the box with Fastboot

Improve documentation on engine-addon development workflow

I have started out with in-repo engines, which were really easy to setup and get started.
Now, I wanted to use the lazy loading feature, so I migrated them to dedicated addons. However, it turned out that wasn't as straight-forward as I imagined it to be. So I figured the things I "missed" there could also be missed by others, so they might as well go into the README. I'll make a PR with the information I gathered, but wanted to verify a few things so that the information I write there is correct ;)

All dependencies of the host app need to go into the engine's devDependencies
All dependencies of the engine need to go into the engine's dependencies
a.) Everything in the dependencies will be included in the lazy loaded bundle
b.) Nested dependencies do not work correctly. For example, if an engine has a dependency A, which itself has the dependency "ember-d3" (which loads D3.js), then D3.js will not be correctly loaded in the engine. Instead, you need to also include ember-d3 as dependency of your engine.
c.) Remove the ember-disable-prototype-extensions addon from the engine
"ember-engines" should additionally to devDependencies, also go into "peerDependencies"
The engine's dummy app should be setup like the host app

(Moved from ember-engines/ember-engines#307)

Add `ember g in-repo-engine` to guides section.

Should be mentioned on http://ember-engines.com/guide/creating-an-engine.

`resetNamespace` undocumented for Ember > 2.1.0

I saw that the resetNamespace option is mentioned in the guides of ember-engines but not documented anymore for newer versions of Ember (emberjs/guides@fff43ef).

Could you give us some insights why this is so?

Add more information about how to use workspaces

Using workspaces is extremely useful and powerful feature. Instead of using ember-addon.paths the doc calls out how to use these, but should go in more in depth.

https certificate is not secure

Visit via https shows a certificate error

This server could not prove that it is ember-engines.com; its security certificate is from *.herokuapp.com. This may be caused by a misconfiguration or an attacker intercepting your connection.

We need clarify roadmap & lazy/eager engines

1. Clarify that engines should always be built together with their host app and other engines, regardless of whether they are lazy or eager. This is required for hosts to understand and properly bundle engine dependencies and routes.

2. Update the "Engines Roadmap" section with - https://discuss.emberjs.com/t/engines-1-0-roadmap/14914

Add Testing section

Wee need clarify how test a engine & host app + engine

Add section about dependency mismatches

Explain what will happen when there are dependency mismatches between different engines and/or their host app.

Duplicated example in guide at "Linking Within An Engine"

In Linking Within An Engine the following example is duplicated:

Previously we mentioned that each Engine has it's own application route, that route corresponds to the mount point when within the Engine. So, if you wanted to go to super-blog (or the root of the Engine) from within the Engine itself, you would do something like:

{{#link-to "application"}}Blog Home{{/link-to}}

Or, maybe even:

{{#link-to "application"}}Blog Home{{/link-to}}