Difficulties in getting statarted with Glimmer

[evil-shrike]

Hi. I apologize for creating a noob issue here but I just can't find a proper place.

I'm interesting in learning and applying Glimmer. Possible in some non-default shape. I read through https://glimmerjs.com/ walked through the demo. But it's hard to move on after this.

Here's some questions/thoughts:

• There're many repos here in glimmerjs organization, but it's hard to understand which one is for what. It'd be nice to have some landing repo with all info. Like Home.
• The simplest demo app installs 20 npm packages. It's a bit scary. It'd nice to have some description what is every package for. How do they relate and depend to/on each other.
• Where to ask questions? There're only 2 questions on StackOverflow with tag glimmerjs. It's strange as Glimmer was released on March as I can remember.
• There are unfinished guides in https://github.com/glimmerjs/glimmer-vm/blob/master/guides/, they have nothing in common with guides on site https://glimmerjs.com/guides/. Are they abandon?
• Is it possibly to use Glimmer without any builder/bundler/etc? Just like a library?
• Are there any plans to release decent documentation?

[locks]

There're many repos here in glimmerjs organization, but it's hard to understand which one is for what. It'd be nice to have some landing repo with all info. Like Home.

We're working on that. It's hard striking a balance between developer ergonomics while developing the project and end user clarity.

The simplest demo app installs 20 npm packages. It's a bit scary. It'd nice to have some description what is every package for. How do they relate and depend to/on each other.

Someone needs to do the work of creating a README for each package and documenting it. I think we will create a quest issue to address this.

Where to ask questions? There're only 2 questions on StackOverflow with tag glimmerjs. It's strange as Glimmer was released on March as I can remember.

There or #-glimmer on the Ember slack group.

There are unfinished guides in https://github.com/glimmerjs/glimmer-vm/blob/master/guides/, they have nothing in common with guides on site https://glimmerjs.com/guides/. Are they abandon?

Those are documentating the internals of the VM, which have been changing quite a lot, hence the current lack of documentation! They are very much separate from the guides about using the Glimmerjs library.

Is it possibly to use Glimmer without any builder/bundler/etc? Just like a library?

Can you be more specific? Do you mean if you can just include a script tag? It could be made to work, but we only provide the npm packages for you to use as you see fit.

Are there any plans to release decent documentation?

I am sorry that you find the documentation insufficient. We try the hardest we can with the time that we have. If you're interested in contributing back material as you continue learning, it would be helpful to the project.

I am closing the issue as I believe I've addressed all the questions, even if the answers are not super satisfactory :x

[evil-shrike]

Well I just can say from a newcomer's point of view (but who have decent understand of Handlebars): after reading and walking through the tutorial on https://glimmerjs.com/guides/ there should be a next step. The tutorial shows how to create an app from scratch with some "black magic". I understand that it's important to have the simplest possible working demo which just works. But then I want details. So after walking though a tutorial with "less effort" I'd like to dig into a tutorial with "less magic" approach. Do a simple step and understand what's going on.

Is it possibly to use Glimmer without any builder/bundler/etc? Just like a library?

Can you be more specific?

All that stuff with index.html which is a template processed in build-time is a bit weird. Obviously I have already some back-end so I need to understand how to integrate glimmer's stuff into it. I hope that stuff with building index.html is optional and just for convenience. Glimmer has nothing like JSX and building should be mandatory (besides TS compiling). For me it looked that these's tight coupling between library and build tools. I hope it's wrong impression.

but we only provide the npm packages for you to use as you see fit.

that's nice, it's just code after all. I should be able to build (if any) it on my own.. For example I can see that all npm packages have AMD-builds of scripts. So can I just import and load them via RequireJS without building at all.

Also let me ask a more practical question . I'll understand if you point me to some other place. Anyway ) What I actually have in mind is replacing Handlerbars with Glimmer. I have my own dirty-checking and Observables mechanisms. Particularly objects fire "get" and "change" events when values are read and changed. This mechanism rerender HB-based views as objects are changed. Is it possible to integrate our objects with Glimmer? Can tracked mechanism be overridden or extended?

[tomdale]

Hey @evil-shrike, thank you for taking the time to write up this feedback. It's very valuable because our top priority is making sure people like you who want to hack on projects are successful and feel like they know how to move forward.

There're many repos here in glimmerjs organization, but it's hard to understand which one is for what. It'd be nice to have some landing repo with all info. Like Home.

You're right, it is very confusing at the moment. Right now all the low level "Glimmer VM" packages are in the glimmer-vm monorepo. We have plans to do the same thing with a glimmer.js monorepo that includes all of the application-level packages.

The simplest demo app installs 20 npm packages. It's a bit scary. It'd nice to have some description what is every package for. How do they relate and depend to/on each other.

We follow the "small modules" philosophy so each unit of responsibility is broken up into a separate package. I agree though that while this makes things flexible, it can make it much harder to understand the system as a whole. I think a written "tour" of how an application works end-to-end would help people develop the right mental model.

Where to ask questions? There're only 2 questions on StackOverflow with tag glimmerjs. It's strange as Glimmer was released on March as I can remember.

Stack Overflow is great, as is @locks' suggestion of #-glimmer in the Ember community Slack. One way or another, we should document the answer to this question on the website as we do for Ember.

There are unfinished guides in https://github.com/glimmerjs/glimmer-vm/blob/master/guides/, they have nothing in common with guides on site https://glimmerjs.com/guides/. Are they abandon?

I was literally begging @chancancode to pick these back up last night. 😁

Is it possibly to use Glimmer without any builder/bundler/etc? Just like a library?

It sure is. You should be able to import the various Glimmer libraries as normal npm packages into Rollup, webpack, or whatever else. Ecosystem compatibility is important so if a Glimmer package doesn't work with your module loader, please let us know.

Everything you need to bootstrap a Glimmer application is in these two files:

1. https://github.com/glimmerjs/glimmer-blueprint/blob/master/files/src/index.ts
2. https://github.com/glimmerjs/glimmer-blueprint/blob/master/files/src/main.ts

(These are from the blueprint generated when you run ember new my-app -b @glimmer/blueprint.)

From my perspective, the trickiest thing about getting a Glimmer app working outside of the default setup is building the resolution map. The resolution map is basically just a POJO that tells the Glimmer VM where to find a given component. So for example, if in my template I type <my-component />, the resolution map POJO contains an entry for the my-component's Handlebars template and optionally its backing JavaScript object.

I tried to document how this works and how you can build your own here: https://github.com/glimmerjs/resolution-map-builder.

With the default Ember CLI-based build tools, a Broccoli plugin builds the resolution map for you at build time. That said, I also have a spike of a Glimmer app working in webpack that uses the primitives (e.g. buildResolutionMap()) from @glimmer/resolution-map-builder to achieve the same thing.

The way to do this in webpack is to write a simple loader function that returns the resolution map for the whole app when you import the resolution map.

Then in your webpack config you can do something like:

{
  module: {
    rules: {
      test: 'config/module-map.ts',
      use: {
        loader: path.resolve(__dirname, 'path/to/your/loader')
      }
    }
  }
}

Are there any plans to release decent documentation?

Yes. 😂 Let me know what would be most useful for you and we can try to prioritize it.

[evil-shrike]

@tomdale (and @locks) thanks for you comments.

Are there any plans to release decent documentation?

Yes. 😂 Let me know what would be most useful for you and we can try to prioritize it.

It's hard to tell what exactly is more needed when you don't understand anything :) But I tried to form some questions list:

Application

What is Application? What are revolver, moduleMap, registry (main.ts) How an application should be setup (index.ts). Why so many things are needed: setPropertyDidChange, registerInitializer, renderComponent, boot? What do they do. Is it required to use Application? Can components be used w/o Application?
Anyway it should be clearly described relation between Application and components.

As I understand registry is a set of components filled up by resolver. But can it be filled dynamically (in runtime not build-time)?

Components & Templates

It's clear that a component is a class derived from Component with a HB-template. Why base class is needed? Is it just interface to implement or something more? How can a component create a child component? Obviously by its tag in template (i.e. statically) but what else? What to do if a component should create another component dynamically? For example given a list of objects and we need to open a nested object editor based on object's data (entity type).

Components have templates in .hbs files. Who when and how processes them? When template's string is parsed and executed? Is it possible to have dynamic templates (to change template content)?

Is it possible to extend template syntax? For example I need to use functions as properties (like this.parent.name where parent is a function)

Data and dirty-tracking (DT)

What Glimmer does with objects in properties and arguments. All that smart things that happen in object, object-model, object-reference packages.

How object graphs are processed. For example a component has a tracked property which is assigned with a complex object (with nested objects). Will tracking work for the whole graph?

The following paragraph is more about design than documentation: Suppose it will work (I hope) and probably that nested objects also should have @tracked decorators to dirty-tracking works. But it means component should control all objects assigned to its properties. Because if not then they won't have @tracked and in case they are changed runtime error happens. I understand it's desirable that UI components have their own shape of data separated from data/dto objects. But it's often would mean a lot of work for manually copying data. We use data objects in our ui components and so it's unclear how we could adopt Glimmer with its requirements for shape of objects (@tracked). So it'd nice to have (and documented) some extensibility mechanism which would allow us to notify glimmer that properties were changed.

DI

These's some DI in Glimmer as I can understand but it's not even mentioned in the doc.

Pipeline

By default the pipeline builds everything into a single file app.js. How can it be fine tuned? For example to separate glimmer itself and app code onto different files.

Integrations

How to implement a view (component) on Glimmer in an arbitrary app:

• App uses AMD (requirejs) modules, how to add a module with Glimmer component
• App uses es6 modules and is built with webpack, how to add a module with Glimmer component.

It's related to my question:

Is it possibly to use Glimmer without any builder/bundler/etc? Just like a library?

(also I asked on SO - https://stackoverflow.com/questions/45033667) If I import all Glimmer packages by myself, setup resolution-map I'll have to load templates from server as strings but what to do next? I'll have to compile them and initialize components in some way...

[tomdale]

@evil-shrike Thank you so so much for writing all of this down. I'm especially impressed given, as you said, it's hard to enumerate the things you don't know you don't know.

I will turn your list into my documentation TODO and try to knock them out one by one. Regarding DI specifically, I tried to flesh out the README for https://github.com/glimmerjs/glimmer-di which I hope is useful. Ideally you don't need to know too much about application/environment/etc. internals to get an app running.

[tomdale]

Literally my todo list.

[Turbo87]

You're right, it is very confusing at the moment. Right now all the low level "Glimmer VM" packages are in the glimmer-vm monorepo. We have plans to do the same thing with a glimmer.js monorepo that includes all of the application-level packages.

FWIW I don't think moving towards a monorepo will improve the situation here... it might even make things worse 🤔

[tomdale]

@turbo87 Why?

[Turbo87]

because in a monorepo it is very easy to get overwhelmed by the amount of code in the project and the boundaries are often not as clear as when separate repos/projects are used. one example of this is https://github.com/facebook/jest which has a ton of code and different packages but would probably be a lot easier to grok if it was distributed in separate packages.

the other disadvantage I see with a monorepo is that all subpackages would need to be in version lockstep which seems unnecessary for the uncoupled projects that we have right now. I know that lerna can handle different versions too, but that seems like a quite complicated mental model to me and I don't see that many advantages of a monorepo that justify all the disadvantages.

[tomdale]

@Turbo87 If you create a single repo and throw every single package inside of it, I agree that has the same problem.

one example of this is https://github.com/facebook/jest which has a ton of code and different packages but would probably be a lot easier to grok if it was distributed in separate packages.

I don't think I agree that a ton of flat packages on GitHub is any better or worse than a ton of flat packages in a monorepo.

Just to be clear, we've been using a monorepo with this glimmer-vm repository since the beginning. Despite some growing pains, in my experience it is categorically easier to coordinate a coupled change across e.g. the compiler and the runtime than it is to coordinate a change between @glimmer/application and @glimmer/component, which are in separate repos.

When it comes to Glimmer, where we try to move as much preprocessing to the build step as possible, it's just fundamental that you have tightly coupled changes between the compiler code and the runtime code. In those cases, a monorepo helps a lot, and you often need to bump version numbers in tandem as well. The fact that Lerna can help us deploy these packages without a short window where dependencies are broken is a big improvement, IMO.

Having used Lerna and monorepos in two projects now, I find the mental model around coordinating releases much simpler than the alternative, where you have chains of PRs with implicit dependencies ("Please merge and release 0.7.2 of <some-dep> before merging this"). I think we can avoid the confusion around package boundaries by grouping related packages into their own monorepos and keeping separate packages separate where appropriate. For example, glimmer-vm can contain all of the low-level VM code, glimmer.js contains all of the developer-facing API that serves a similar role to how Ember consumes Glimmer, and we can keep utility packages separate so people can easily find them and grab them for their own tools.

[Turbo87]

Having used Lerna and monorepos in two projects now, I find the mental model around coordinating releases much simpler than the alternative

seems that our experiences differ quite a bit. whenever I tried to contribute to a lerna project I was pretty frustrated in the end because nothing worked as expected and everything had to be done differently from a "normal" Node project.

what you call an advantage of having tight coupling between the packages is in my eyes a disadvantage. having separate packages/projects forces you to create propery boundaries while with lerna it just doesn't matter so much because you're always releasing at the same time anyway.

to finish off: the tooling around monorepos is unfortunately in a far worse state than for normal projects and I think having a monorepo will ulitmately scare off potential contributors because the project looks different from most other JS projects they see on GitHub

[tomdale]

@evil-shrike First pass at describing the constituent packages here: https://github.com/glimmerjs/glimmer.js