Document and implement frontend build process for logged-out users; implement the services Apostrophe gives the logged-out browser scope in JavaScript

[boutell]

• There will be an apos object.
• It will have the services currently provided by apostrophe-lean-frontend, including a way to implement widget players.
• It will not have any other dependencies and will support oldish browsers to the degree that apos.lean does.
• It needs a name that won't conflict with the data objects modules attach to apos for logged-in users in 3.x.
• Shall we just keep "apos.lean" as part of our rebranding of apostrophe's frontend as size- and performance-conscious?

[boutell]

We elected to go with apos.utils, and apos.lean has already been merged in 2.x, so we are well down this road.

However we have no frontend build system for logged out users in 3.x yet. Not styles or JavaScript. We have to address that.

Let's talk about three ideas. I'm at least semi-serious about two of them. Here when I talk about src I mean the src folder of every module that has one.

1. src/apos is logged in stuff (already implemented). src/always is pushed all the time. src/always/components registers vue components and src/always/apps pushes js to be run on page load; same rules as src/apos. Vue is always there.

2. src/apos is logged-in stuff (already implemented). src/always is pushed all the time. Specifically, src/always/entry.js gets imported into the bundle that is actually pushed to the browser. A src/always/entry.js file must export a function, which gets invoked on page load. src/always/entry.js is evaluated with babel (ES2015), with support for import and require, so it can pull in other stuff. Polyfills are pushed for browsers that need them, to allow ES2015 code to run. And you can import stuff that you "npm install" at project level, or npm module level.

3. src/apos is logged-in stuff (already implemented). src/always/*.js (everything in that folder) is pushed all the time, in filename sort order. These files are compiled by babel etc. at all. It can't "require" or "import".

PROS AND CONS

PLAN ONE

PROS: seems really shiny at first glance.

CONS: impact on those who don't want Vue is out of the question.

PLAN TWO

PROS: also shiny. You can still go Vue, as long as you npm install it, without taking on Webpack yourself. You can also ignore Vue but write ES2015 code and import other libraries you like (React for example) without tackling Webpack. Our own modules can ship frontend code for logged-out site visitors using ES2015 and imports, etc., without a two-step process where the module has its own build procedure. Such two-step processes sacrifice the chance to avoid duplicate inclusion of the same libraries, so very good to avoid... if we should be shipping big libraries of js for logged-out users at all, that is.

CONS: might be a waste of hard work - users might prefer their own webpack/babel/hot new thing configuration and just push the output to us, like now. Not sure how hard pushing the polyfills only to relevant old browsers without a perf hit in new browsers is going to be. The perf hit in old browsers will be significant, and they are the users whose experience is slowest already. And there's something to be said for writing vanilla js when you're building a website, not a web app. I'm not sure if we can do it and still have a shot at a decent Google Lighthouse score. Requires more research.

PLAN THREE

PROS: very lightweight. Great if all you want is light vanilla js, without giant dependencies creeping in because typing "import" is so easy. Hands down best for the IE11 crowd. No wasted effort if developer prefers to use their own Webpack pipeline anyway. We can get it done in a day.

CONS: if I'm a new developer, I'm learning ES2015. That means that to write any custom JS at all for my Apostrophe site, I have to also master setting up my own Webpack pipeline.

WHAT ABOUT STYLESHEETS?

Hey yeah, what about them? It sounds like for admin stuffs we'll be using inline vue stylesheets of some kind, but that doesn't make sense for the frontend. Should we push src/always/import.sass? With a stock SASS configuration? Or with a certain set of plugins we agree upon... now? We could pull a "plan three" and push everything that matches src/always/*.css, assuming people will SASSify their own.

NAMES

My names for folders and things here are kind of terrible. Let's talk about them, but first let's pick a plan on the merits.

[abea]

Plan 2 seems most promising on its face. Maybe outsourcing polyfilling to something like https://polyfill.io/v3/ could simplify that piece. Maybe it could be built out in phases, but eventually it seems the ability to do fancy ES2015 will be valuable without requiring them to do their own webpack.

[boutell]

Interesting! I'd be hesitant to depend on a specific third party service for everything to work, in an open source CMS...

But, it's built on open source and there are open source solutions based on it:

https://kentcdodds.com/blog/polyfill-as-needed-with-polyfill-service

Perhaps we can roll that in, as long as we're not responsible for the actual curation of polyfills that's not crazy talk.

On Wed, Jun 26, 2019 at 12:09 PM Alex Bea notifications@github.com wrote:

Plan 2 seems most promising on its face. Maybe outsourcing polyfilling to something like https://polyfill.io/v3/ could simplify that piece. Maybe it could be built out in phases, but eventually it seems the ability to do fancy ES2015 will be valuable without requiring them to do their own webpack.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/1589?email_source=notifications&email_token=AAAH27LSJUAU4IKWCU3KRRDP4OIB3A5CNFSM4FOY5RV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODYUA7SY#issuecomment-505941963, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAH27IJZIRKNCCQAVWEFXTP4OIB3ANCNFSM4FOY5RVQ .

--

Thomas Boutell, Chief Software Architect P'unk Avenue | (215) 755-1330 | punkave.com

[boutell]

I'd want to avoid even one synchronous web request hit in latest Chrome and friends, if possible.

On Wed, Jun 26, 2019 at 12:13 PM Tom Boutell tom@punkave.com wrote:

Interesting! I'd be hesitant to depend on a specific third party service for everything to work, in an open source CMS...

But, it's built on open source and there are open source solutions based on it:

https://kentcdodds.com/blog/polyfill-as-needed-with-polyfill-service

Perhaps we can roll that in, as long as we're not responsible for the actual curation of polyfills that's not crazy talk.

On Wed, Jun 26, 2019 at 12:09 PM Alex Bea notifications@github.com wrote:

Plan 2 seems most promising on its face. Maybe outsourcing polyfilling to something like https://polyfill.io/v3/ could simplify that piece. Maybe it could be built out in phases, but eventually it seems the ability to do fancy ES2015 will be valuable without requiring them to do their own webpack.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/1589?email_source=notifications&email_token=AAAH27LSJUAU4IKWCU3KRRDP4OIB3A5CNFSM4FOY5RV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODYUA7SY#issuecomment-505941963, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAH27IJZIRKNCCQAVWEFXTP4OIB3ANCNFSM4FOY5RVQ .

--

Thomas Boutell, Chief Software Architect P'unk Avenue | (215) 755-1330 | punkave.com

--

Thomas Boutell, Chief Software Architect P'unk Avenue | (215) 755-1330 | punkave.com

[boutell]

I lost a massive comment here. :cry:

In a nutshell, this is good and we should follow it:

https://philipwalton.com/articles/loading-polyfills-only-when-needed/

So how do we get babel to help us? It's set up to build a bundle with your code plus the polyfills required for it. We want the polyfills for missing libraries (like Promise) broken out separately for delivery in one file, but our own code with all language features compiled down to ES5 in a separate file. And we want good source code mapping so we can follow a trail of bread crumbs to understand errors despite the compilation.

I think this might work for Babel:

useBuiltIns: false // no polyfills
forceAllTransforms: true // but, go all the way to ES5 language syntax

Then we can create the polyfill bundle probably with a simple task that just builds a source file that contains:

import "core-js/stable";
import "regenerator-runtime/runtime";

Which gives us a full set of polyfills for library features of stable modern javascript, including things needed for babel-compiled async functions to work.

[grdunn]

i like the idea of # 3 because we can be flexible with things like apostrophe-webpack or apostrophe-next-cool-thing that can get folks writing es2105 quickly and we don't have to be opinionated about it.

[boutell]

We agreed to put a day's sprint effort, as in the Friday sprint, into attempting option two. That would consist of myself and another interested developer. We want to see the difficulty and the impact.

[boutell]

Thinking about the easiest way to do this. I like this plan:

• Our build task builds the bundle twice. Once with babel in the config ("babel bundle"). Once without ("pure bundle").
• The initial markup contains NO "script src" tags (well, not forced on the developer by us, anyway).
• At the bottom of the body there is one inline script tag which determines if this is a "modern browser" or not.
• If it's modern, a script tag to load the "pure bundle" is dynamically added. If it's not, a script tag to load the "babel bundle" is dynamically added.

That's the idea. I really like it because:

• We know we can do it; we don't have to learn lots of new babel tricks. Just leave out babel-loader or add it back in. Webpack accounts for "import" and "require" statements, otherwise leaves the code alone. In fact we're doing it now, because we forgot to add babel for our existing "user" webpack bundle and just haven't tried anything besides Chrome for 3.x yet, LOL.
• That moment's delay in determining the need and inserting the script tag is fine because we're building websites here, and it's considered a best practice to render nicely and function reasonably before loading javascript on a website. We're already kinda doing this in 2.x, which loads the bundle at the end of the body, not the beginning; we're only adding a moment of calculation to choose which bundle to load. If this were an app framework with no need for good SSR and SEO, we'd probably choose differently.
• We can apply this approach equally to the "user build" and the "anon build".

In support of this, I think we should reorganize what we've done in src so far as follows:

• In every active module, src/always/entry.js gets imported by a master js file that is passed to webpack as the entry point, no matter who is looking at the website.
• Ditto for src/user/entry.js, if a user is logged in (in this case you also get the "always" stuff).
• src/apos/components moves to src/user/vue-components, src/apos/tiptap-extensions moves to src/user/tiptap-extensions, and if you really want to, you can have these in src/always too, which triggers inclusion of vue and/or tiptap in the anon bundle. It's your choice. We probably won't ever put any vue components or tiptap extensions in "always" ourselves, not in official modules, but if what you're writing is more app and less website, you might like it.
• It should be possible to register another "frontend extension" with its own magic subfolder name and its own special plumbing ,similar to what we do to register Vue and Tiptap components, and the Vue and Tiptap code should use that mechanism rather than cluttering the core of the assets module with more and more special cases.

[abea]

This ship may have already sailed, but the directory levels seem more confusing to me than declaring assets in code. Is this degree of directory structure common for this kind of thing?

[boutell]

Convention over configuration... the existence of the folder is sufficient information, so why make developers do it twice? It's worked out great for DCAD, and for our own team's internal implementation of something similar (pk- stuff). Yes I'm adding another level, but I think it's worth it to keep that automation going.

On Mon, Jul 8, 2019 at 11:28 AM Alex Bea notifications@github.com wrote:

This ship may have already sailed, but the directory levels seem more confusing to me than declaring assets in code. Is this degree of directory structure common for this kind of thing?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/apostrophecms/apostrophe/issues/1589?email_source=notifications&email_token=AAAH27KGAVJD6GKDPPJ63RLP6NMKPA5CNFSM4FOY5RV2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODZNOLXA#issuecomment-509273564, or mute the thread https://github.com/notifications/unsubscribe-auth/AAAH27KCMT4BN6F3Z6LAST3P6NMKPANCNFSM4FOY5RVQ .

--

Thomas Boutell, Chief Software Architect P'unk Avenue | (215) 755-1330 | punkave.com

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.