Interoperability proposal

[idoros]

THIS IS STILL WIP

---

Today Stylable isn't promoting a simple publishing solution for component libraries and we can see several formats, each with it's own pros/cons (formats are not exactly what comes out of Stylable, but work in the same way):

isolated css files

Component view/logic and style are not linked and contain identical duplicate symbols. End project developer is responsible for loading required styles into the browser (some projects offer tools to manually select used assets to combine).

dist

• comp.js: component view/logic
• comp.css: separate styles required for component
• common.css: common styles

benefits	issues
node compatible: no node configuration is required sense style don't load into node	auto order: styles need to be manually combined for composition to override composed parts and components
minimal css: load just required styles	missing css: manually add/remove required styles
	symbol optimization: classes/vars/states are final and cannot be optimized

combined css asset

Library styles are combined into a single asset that the end project developer is responsible to load into the browser. Components view/logic not linked but contain identical duplicate symbols.

dist

• comp.js: component view/logic
• lib.css: library combined styles

benefits	issues
node compatible: no node configuration is required sense style don't load into node	auto order: styles need to be manually combined for composition to override composed parts and components
auto order: load just required styles	minimal css: load all styles even for a single component
	symbol optimization: classes/vars/states are final and cannot be optimized

imported css files

All styles are linked into each view/logic and to each other in the case of commons.

dist

• comp.js: component view/logic
• comp.css: separate styles required for component
• common.css: common styles

benefits	issues
auto order: improved by auto collection by evaluation order	auto order: still misses some composition cases
minimal css: css per entry can be deduced	node compatible: requires hook
	symbol optimization: classes/vars/states are final and cannot be optimized

css-in-js (Stylable)

No css files, everything is generated using Javascript. There are many css-in-js libraries out there with optimization options, this case describes the most trivial case that can be output by Stylable.

dist

• comp.js: component view/logic
• comp.css.js: separate styles required for component
• common.css.js: common styles

benefits	issues
node compatible: only js modules	caching: no css asset to cache
auto order: improved by auto collection by evaluation order	auto order: still misses some composition cases
minimal css: only loaded CSS is evaluated	static: ALL css is parsed as Javascript and then again as CSS costing cpu/memory

stylable source files

Publishing source files removed most of the issues, but make the project "sticky" requiring any project that depend on it to use Stylable as well

dist

• comp.js: component view/logic
• comp.st.css: stylable source file

proposed publish format

Summarizing the mentioned formats, each has it's own issues:

format	node compatible	minimal css	auto order	symbol optimization	caching	static
isolated css	+	*	-	-	+	+
combined css	+	-	+	-	+	+
imported css	-	*	***	-	+	+
css-in-js (Stylable)	+	**	+	****	-	-
stylable source files	-	*	+	+	+	+

* minimal/critical css requires pre-build asset for specific end point or collection in server

** only loaded CSS is evaluated

*** composition styling order is fragile when simply leaning on the component dependency graph

**** css-in-js can optimize symbols, but not in the case of Stylable css-in-js output

Ideally publishing a 3rd party library with components should have single format that Stylable can promote and later be consumed with minimum configuration with or without Stylable.

dist

• comp.js: component view/logic (imports comp.st.css.js)
• comp.st.css.js: component minimal runtime (local->scope mappings and classes/states utils)
• comp.stsrc.css: original stylesheet source
• lib.css: base library css with fixed namespaces decided by the lib owner

dist-extra

configurations

Consuming the format can be in one of two ways:

• Non-stylable project - loads component files that are linked to st.css.js mapping files. The view/logic uses fixed BEM like symbols that are exported by the library, and the developer is responsible to load the lib.css from the library in the client.
• Stylable project - developer initiate @stylable/node in node and configure the plugin in webpack/rollup and gets all the benefits of Stylable

usage	node compatible	minimal css	auto order	symbol optimization	caching	static
non-styalble project	+	-	+	-	+	+
stylable project	+	*	+	+	+	+

benefits

• single publish format
• not "sticky" by default: Stylable can be added later
• loads in node/browser
• configurable symbols: classes/vars/states can be optimized
• simple namespace synchronization between browser and server code

possible additions

• .st.css.src could be replaced with a more processed format to reduce dev/build time
• suggest or provide tooling for
• theme.css: optional theme file(s) that can be
• variant.st.css: optional component variant files
• index.st.css: expose public components style apis, lib variables & (map through browser field to esm/cjs)