OC templates architecture, status-quo, lessons learned and next steps

[nickbalestra]

The path to OC templates

In the past months we spiked and experimented with a template architecture for OC in order to enable building components with reacher client-side libraries other than the currently supported engines (handlebars and jade). One of the goal of this new API is to make react a first class citizen of OC without having to lock the platform around it but allowing other technologies to be easily swapped in the future if wanted/needed.

In this rather long post (sorry for that), I’ll try to outline what we have on master at the moment, what experiments are running on the templates feature branches, what we learned, and what should be the next steps in order to deliver such vision.

---

At an high level components are made of 3 main parts:
dataProvider (usually server.js)
Template file (now an handlebars or jade file)
Static assets

Ideally component creator should simply care of handling data in order to provide a viewModel within the dataProvider and build the viewLayer using a specific library/fw (i.e. react). The template should hide the complexity away in order to compile/optimize the client bundle, perform server-side-rendering, and all the related wiring. In order to do so, templates should be able to handle at least 2 compilation processes:

• DataProvider
• View

The implementations options for such compilations should be left to template creators, for example one could decide to use the google clojure-compiler, one webpack, one both together or even something different like rollup, in other words compilation should become the sole responsibility of the ‘template’ module and not hard-wired within the CLI anymore.

In order to solve dependencies issues on the registry, for example to perform server-side-rendering, one option I suggest will be to bundle the dataProvider with all the dependencies needed for performing his tasks, this imho totally fit the idea of immutability for published components.(the down-side is dataproviders being bigger in size). This could open interesting opportunities for optimizations, for example the dataProvider bundle could use something like rollup, together with aliasing react to something like preact for a flat, lighter bundle and faster bootrsap performances. On the other side, the client-side bundle should be as light as possible, with all its dependencies delivered via cdn for an aggressive caching strategy and minimal payload. Static assets could also be processed by the template module but I think that for the moment this is not a required/blocking step.

---

Status quo on master

• Browser client.js templates API allowing to register supported template types programmatically and fetch the required dependencies before attempting a client-side rendering.
• Registry exposes templates infos to through context.templates. Templates need to be whitelisted within the registry config. Dev registry automatically does this dynamically.
• Legacy Jade & Handlebars types internally fallback to oc-template-jade and oc-template-handlebars, allowing for already published legacy components to keep working without any needed change.

Template have the following api:

• getInfo()
• render()
• getCompiledTemplate()
• compile()

What can be done with the actual code in production: start prototyping early components built using templates not for production (we used this for some internal projects and during an internal hackathon) with the goal to further investigate API ergonomy for the OC-creator and push forward the effort. In practice: client-side rendering only for new templates, dev only, a bit manual work still required to make it work (current template-dependencies solution sub-optimal).

---

Status quo on /templates branch

• PR for Init method for the cli to support published templates on npm/local as long as they are installable npm modules with the correct API. PR is currently in review. Issues need to be address within the PR:

1. Registry should be able to be run from everywhere, at the moment only the folder running the components is supported.
2. API in flux that needs to be addressed in order to unblock the PR
3. Template dependencies structure should be splitted in compile + client
4. PR for CompileServer() hook API.

What could be done once this land in production (less wiring, templates in devs will work smoothly, only client-side rendering will still supported)

---

Agenda and what still to be addressed

• Split Template API
• Update Jade/Handlebars template accordingly
• Registry should properly register client-templates. How do we want to solve this for dev registry?
• Rebase and update GPT-537 PR
• Update oc-template-react
• Finalizing moving parts in oc and plan deploy accordingly, tests and merge /templates -> master so that client-side rendering of templates (react) will be in production.

What could be done at this point: client-side rendering of templates like oc-template react in production.

• Server-side rendering (SSR MVP Exploration)
• Finalize API, migration
• Unified compilation API compile(data, template, statics)
• Template watchers (Removing watchers/compilers from CLI (CLI will be super lean, totally webpack-free and templates will be handling those aspects) at this point CLI can be decoupled from registry/OC and moved into his own module?
• JADE->PUG Migration how we’ll handle the server compilation for them? Moving what we have now in the CLI to the template?
• Do we want to provide a core/minimal template with the CLI anymore? pros/cons/what?

[mattiaerre]

thank you very much for sharing this w/ us @nickbalestra let me know if there is anything I can do to help you here 😉

[nickbalestra]

Update

• Jade and Handlebars are now structured with a split-module API (compiler/render-info)

next on the roadmap:

DONE:

• Unblock the split-module APIs PR [GPT-646] Split module API #508
• Move out all the webpack/compiling (now called packaging) from the CLI to the templates (done for JADE)

REMAINING THIS WEEK

• Work on the Unified compiled API (server, view, statics)
• Manages all the various packages need for templates to work (template wrapper, webpack-configurator,..) and structure them in a monorepo together with botht the core templates jade and handlebars #17
• Move tests (packageTemplate, packageStatics, packageServer,..) out to relative templates
• Fix/updated tests for all the new modules created
• fix package-components test#20 in base-templates repo
• fix package-components test#20 in oc repo
• port handlebars template to the same arch of the jade template.
• making sure Legacy is handled correctly
• Merge branch to master and release

[nickbalestra]

Done in #525