LEGO (Lightweight Embedded Gluten-free Objects) is a NodeJS tool to build ๐ fast, โป๏ธ reactive, ๐ก native web-components that are easy to digest ๐ฑ for your browser.
Lego is:
Lego is not (and will never be):
View the demo and their source ๐งช.
Lego is inspired from the native Web-Component spec and Riot.
Itโs just much lighter with simplicity, source that are easy to read, to hack and to maintain. The core lib is only 61 LOC! Lego is as light as 3Kb for the full bundle!
Demo: view in action
Lego is based on npm and the latest node.
You need to install the compiler with npm i @polight/lego
Create a file called bricks/hello-world.html:
<template>
<p>Hello ${state.name}</p>
</template>
<script>
init() { this.state = { name: "World!" } }
</script>
Compile with npx lego bricks
And use it in your index.html
<script src="./dist/index.js" type="module"></script>
<hello-world />
Run a local web server (ie: python3 -m http.server
) and display your index.html (ie: http://localhost:8000).
bricks/user-profile.html
<template>
<div :if="state.registered">
<h1>${state.firstName} ${state.lastName}'s profile</h1>
<p>Welcome ${state.firstName}!</p>
<section :if="state.fruits.length">
<h3>You favorite fruits:</h3>
<ul>
<li :for="fruit in state.fruits">${fruit.name} ${fruit.icon}</li>
</ul>
</section>
<button :if="!state.registered" @click="register">Register now</button>
</div>
</template>
<script>
init() {
this.state = {
registered: false,
firstName: 'John',
lastName: 'Doe',
fruits: [{ name: 'Apple', icon: '๐' }, { name: 'Pineapple', icon: '๐' }]
}
}
register() {
this.render({ registered: confirm('Do you want to register?') })
}
</script>
Compile this component: npx lego bricks
index.html
<user-profile></user-profile>
<script src="./dist/index.js" type="module"></script>
Run your webserver and see your little app!
When developing you may want to automatically watch files changes. In that case pass the
-w
flag:npx lego -w bricks
Tip: you probably want to store this task with a shortcut like
npm run watch
. To do so just add"watch": "lego -w bricks"
in you package.json scripts.
A component can optionally have 3 parts: some HTML in a <template>
tag, some JavaScript
in a <script>
tag and some CSS in a <style>
tag.
An HTML template is written within a <template>
tag.
These superpowers can be recognized with their :
or @
prefixes.
The possible directives are:
:if
to display a tag based on a condition:for
to repeat a tag:
to evaluate a string@
to bind an eventNote that
:if
and:for
attributes, when used in the same tag should be used with an order in mind:<a :if="user" :for="user in state.users">
wonโt work, but<a :if="state.users.length" :for="user in state.users">
will first evaluate if theusers
array has items, or<a :for="user in users" :if="user">
will check that each individual user has a value.
<a :if="state.isAdmin" :for="user in state.users">
wonโt loop at all ifisAdmin
is false.
:if
DirectiveConditionally display a tag and its descendants.
Example: <p :if="state.count < 5">Less than 5</p>
will be displayed if the condition is met.
:for
DirectiveRepeat a tag based on a property.
The syntax is as follow: :for="item in state.items"
.
The item value will be available trough ${item}
within the loop.
If you need an incremental index i
, use :for="item, i in state.items"
.
Example: <li :for="attendee in state.attendees">${attendee}</li>
with a state as
this.state = { attendees: ['John', 'Mary'] }
will display <li>John</li><li>Mary</li>
:
Custom DirectiveA custom directive will interpret in JS whatever you pass as value.
<template>
<a :href="this.getUrl('144')">Visit Profile</a>
</template>
<script>
getUrl(id) { return `/user/${id}` }
</script>
outputs
<a href="/user/144">Visit Profile</a>
Example: <input type=checkbox :checked="state.agreed" :required="state.mustAgree">
.
With the following state: this.state = { agreed: false, mustAgree: true }
would render
<input type=checkbox required="required">
.
@
Directive for binding Events<template>
<button @click="sayHi" name="the button">click</button>
<script>
sayHi(event) {
alert(`${event.target.getAttribute('name')} says hi! ๐๐ผ`)
}
</script>
The state
is where the reactiveness takes place.
declare a state
object in the init()
function with default values:
init() {
this.state = {
user: { firstname: 'John', lastname: 'Doe' },
status: "Happy ๐"
}
}
Displaying a state value is as simple as writing ${state.theValue}
in your HTML.
When you need your component to react, call the this.render()
method
with your updated state:
itemSelected(event) {
this.render({ selected: "apple", isAdmin: true })
}
This will refresh your component where needed.
When state
is just mutated, the changed(changedProps)
is called.
This changed()
method is called before (re-)rendering.
Attributes declared on the components will be all be accessible through the state
.
If the property is initialized in the this.state
, the attribute will be reactive:
<x-user status="thinking ๐ค"><x-user>
status
will therefore be reactive and the thinking ๐ค attribute value will overwrite the Happy ๐ default status.
โ ๏ธ A property that is not declared in the state
wonโt be reactive.
These properties can be accessed through this.getAttribute()
from within the component.
After all, these components are just native! ๐ก
Slots are part of the native web-component. Because Lego builds native web-components, you can use the standard slots as documented.
Example:
index.html
<user-profile>
<span>This user is in Paris</span>
<user-profile>
bricks/user-profile.html
<template>
<h1>User profile</h1>
<p>important information: <slot></slot></p>
</template>
Will write โฆ<p>important information: <span>This user is in Paris</span></p>
CSS is much more fun when itโs scoped. Here it come with the web-components.
Here again, no trick, just the full power of web-components and scoping styles. Well, you should know that the css is reactive too! ๐ฒ
Writing CSS is as easy as
<template>
<h1>Bonjour!</h1>
</template>
<script>
init() {
this.state = { fontScale: 1 }
}
</script>
<style>
:host {
font-size: ${state.fontScale}rem;
}
h1 {
padding: 1rem;
text-align: center;
}
</style>
:host
is a native selector
for web-components.
It allows to select the current component itself.
You can use variables in your CSS just like in your templates.
Example:
<template>
<h1>Bonjour<h1>
</template>
<script>
init() {
this.state = { color: '#357' }
}
</script>
<style>
h1 {
color: ${ state.color };
}
</style>
will apply the #357
color onto h1
.
LEGO_URL=</url/to/lego.min.js> npx lego <source_path> <target_file_path>
Would compile the source_path file or folder (recursively) into target_file_path js file using lego.min.js from the declared url.
As mentioned before, when developing you probably want to watch for changes with the -w
option: npx lego -w <source_path> <target_file_path>
source_path: either a file or a directory (relative or absolute). If itโs a directory, it will recursively read all the .html files and compile them into the target_file.
target_file_path: (default: components.js) the path (relative or absolute) to a .js file. That file will be created and contain all the components.
The name of the file will be the name of the component.
Example: components/x-button.html will create <x-button>
component.
However in some cases you may want to give your component a different name than the file.
To do so, you may give your template a name with the name
attribute.
Example:
components/x-button.html:
<template name="my-super-button"></template>
Will create a <my-super-button>
component.
Note that because it builds native web-components, the naming convention must respect the ones from the standards (lowercase, with a dash in the name, starting with a letter, โฆ)
Just install node dev dependencies (npm install
) and run the tests (npm test
).
Because Lego is actual native web-components, all its native possibilities (like slots), :host and whatever exists or will exist are on board.
Lego is based on native customElements. Support for customElement is spreading and shall increase in time.
When building a web-app you may have control of the browsers. If youโre building a more general website you may need to increase the overall browser compatibility and install the custom-element polyfill.
It is still fully compatible with native custom elements. No magic behind the scene, no complexity, just a couple of useful methods to write native web-components easier.
Using a compiled component has no dependency, nothing extra injected in the browser. Compiling depends on jsdom.