> Presto is currently under active initial development and available only for preview in its compiled "dist" state. As such, pull requests are not being considered at this time. However, bug reports, feedback, and feature requests are encouraged — the goal of this repository is to create an open discussion. Please submit any considerations of this nature as issues here on GitHub.
Why?
Presto was inspired by Alpine.js, which offers developers the ability to leverage a fully-reactive framework via attributes sprinkled into your existing markup like x-for, x-text, or x-on:click. Using Alpine in-tandem with utility frameworks like Tailwind CSS, developers can rapidly build complete app frontends with little overhead and often without ever writing more than a single .html file.
This ease of use has the potential to come at a cost however, as the HTML source starts to grow very rapidly and with considerable redundancy — especially for SPA-type applications.
The goal of Presto is to break-down your app's HTML into smaller and reusable components without forcing you into adopting a new syntax like Vue or React's JSX. Already have most of your frontend built? Great! Presto works with the HTML you already have. All you have to do is extract the components that you want to reuse and organize.
> #### Why not use React or Vue? > As developers, we each typically have a framework of choice when it comes to creating application views. Each framework comes with its own idiosyncracies; workflows; dependencies; and, often times, a learning curve. Tools like Alpine and Tailwind CSS leverage the universal familiarity of HTML and enable developers to accomplish a bulk of their frontend development in one place, the markup — an approach that is both rapid and increasingly "instinctive" in its execution. > > Presto aims to build on that universal familiarity and seeks to make mangement of frontend components syntactically-natural, central, and accessible to everyone.
Demo App and Video Intro
If you're like most developers and prefer to learn through examples, the Presto demo app, Expresslane, is available here, and the intro video can be viewed on YouTube here.
Install
From npm: Install the CLI tool from npm.
``sh npm i presto --save-dev `
Config
Inside of a Node environment, Presto is a command line utility accessible using the npm command presto with a configuration file that you specify. Create a presto.config.js file in your project's root:
presto.config.js
`js // REQUIRED : Object | Array`
$3
To provision a basic configuration file, with optional sample components, you can use the --init option in your project's directory:
`sh npx presto --init `
$3
By using a JS file as the configuration object, Presto enables developers the ability to leverage the object-oriented nature of JavaScript. In this way, you can declare things like include, props, or pipes as constants, and then pass them into as many or as few config objects that need them:
presto.config.js
`js const include = [ 'resources/presto/shared/*/.html' ];
export default [ { input: 'resources/presto/views/app.html', include, // assigned from const output: { file: 'resources/views/app.html', props, // assigned from const pipes, // assigned from const } },
/ ... /
{ input: 'resources/presto/views/dashboard.html', include, // assigned from const output: { file: 'resources/views/dashboard.html', props, // assigned from const pipes, // assigned from const } } ]
`
Usage
When run on its own, the presto command, by default, will look in your project's root directory for a presto.config.js file. If you wish to specify a different file for various build types, you may use the --config or -c switch to specify a different config:
Eventually, the intention is to use implement the Chokidar file-watcher library to allow for a single command, presto --watch, to run in the background during component development. In this way, as each component is modified and saved, Presto will recompile to reflect changes.
For now, your development workspace can be configured to work with Nodemon watching your Presto directory:
Expression of components in Presto starts by declaring a component definition with native HTML, and then expressing that component in your markup through use of a syntactically-natural custom tag that you define. Starting from the input document in your config, your markup will be compiled as each component is referenced, expressed, and rendered.
$3
Presto output begins with one item, an input document specified as the input property of a config object in presto.config.js. From this input document, Presto will cascade through any component expressions and render them as HTML where they are written. A sample input document might look something like this:
`html
`
As promised, the syntax is plain old HTML. The only difference is that we've included components for Presto to reference and render. This is first done by referencing the components using standard tags with an empty presto attribute:
`html
`
Think of these tags like ES6 import statements. Next, the components are told where to render within the document by expressing each component's custom tag:
`html
`
> #### Why use a generic tag instead of a custom tag? > To take advantage of IDE and editor logic/formatting. Most editors' language servers will offer auto-completion of paths expressed on the href attribute of a tag. This makes it easier for you to ensure that you've typed the correct path to your imported component. > > Eventually, I'd like to extend the existing HTML LSP-compliant language server in VSCode to help with auto-completion of component names and, where necessary, rewriting of component imports when project assets are reorganized. If anyone reading this has experience with LSP in VSCode, and would like to help, please contact me via DM on Twitter.
#### Config-provided Components
If you've defined a string or array of strings on the include property of presto.config.js, you don't need to express your component imports using tags for those component documents which match your given Glob patterns. In the case that a config-provided component has a name conflict with an import-provided component expressed via tag, Presto will use the import-provided component when resolving a component expression.
> #### Unique Component Names > > While making use of import-provided components allows for duplicating component names, this is a practice against which I strongly recommend in most cases. However, an exception to this could be if you were defining a custom table component. In such an instance, you may want to have Data expressed differently under than you would if it were expressed under .
---
$3
The remainder of this README will be written under the assumption that all components are import-provided, but it should be noted that this is not necessary, and you can provide all of your components using the include property on your config object, making things much easier. Use Presto how you want to use it, in whatever way makes your project easier.
---
$3
The input document example included a link to the component
./app.html and then expressed it as within the markup. For this to render correctly, there needs to be a component file present at ./app.html, relative to the index document:
app.html
`html
`
A lot is happening here, but let's start from the top to understand what's being expressed. Most critically, the component document starts with a
tag that provides a handle for the component we're defining — in this case, we're defining an app component that will be expressed as , so the name attribute of our tag is set to "App". The full tag is expressed as:`html
`
For each component name, use of PascalCase (like ES6 classes) is recommended to aid in syntactic visibility, but this is optional and completely up to you. Presto component tags are case-sensitive, so if you declare a component as
App, it must be expressed as , and not as .
> #### Case-insensitive Code Formatters > > Some code formatters will drop capital letters in HTML tag names, especially those names which match existing standards-compliant tags. While Presto recognizes the difference between
and or
and
, you may find that your code formatter replaces upper-cased tag names with lower-cased equivalents. > > If you're using Prettier, you will not experience an issue with casing unless you attempt to express a component using an upper-case name that matches an existing standard HTML tag.
#### Component Nesting
Below the
tag, several tags have been specified. Each of these will correspond to a component document that expresses its export via a , similar to the one defined for the App component.
Within the body of the
App component, there's a mix of native markup as well as Presto component expressions. In this way, a component can yield its HTML wherever it's needed in a document — nested inside of as many or as few expressions as is desired.
$3
In the example
App component document, notice that the Sidebar and Timeline expressions have class attributes applied to them. In this case, we're making use of Tailwind CSS to define the width of each component inside of their parent
. This is a critical aspect of Presto and one that makes component reusability so versatile. To take a look at how this is applied, let's examine the content of an example sidebar.html component:`html
All Notes
::showPreview ::size="large" $$wrap="template" x-for="note in notes" />
`
If you're unfamiliar with Tailwind CSS, the classes we've applied to the inner
in App containing our Sidebar and Editor components provide for a space that occupies the entirety of the browser below the Navigation component — we'll call this space the "content" area. Then, the classes applied to the wrapping
in Sidebar provide for a space that occupies the entire height and width of the content area.
> *The
Modal component is position: absolute; and does not count against our app's vertical space.
However, the sidebar component is just that, a sidebar. It shouldn't occupy the entire content area – only a space to the side of it. By passing the
w-32 class in the class attribute for Sidebar in App, Presto will add w-32 to the class attribute of the wrapping
in Sidebar when it renders its HTML for App. The Tailwind CSS class w-32 will limit the width of Sidebar to 8rem, leaving the remaining space in the content area to be occupied by Editor, on which we've applied a Tailwind CSS class of flex-1.
In this way, our sidebar component can be reused anywhere throughout our app. Attributes that need to be modified based on context can be applied onto the component expression itself rather than hard-coded into the component definition.
$3
Looking at the component document for
Sidebar, you might have noticed that the component expression for NoteThumbnail is looking a little busy. In addition to applying an attribute for Alpine, x-for, the component expression also has a few attributes specific to Presto. To understand what each of these attributes does, let's look at the component document that the NoteThumbnail expression references:
App, we already know that any attributes we apply to a component expression will be applied to the root element within that component. However, those familiar with Alpine know that the x-for attribute can only be applied to a element, and the component definition for NoteThumbnail uses a
as its root.
We could just wrap the root
inside of a within the component definition, but suppose we want to use our thumbnail component elsewhere within our app? With it wrapped inside of a tag, we might lose the ability to reuse it. Instead, the expression for NoteThumbnail in Sidebar applies the Presto $$wrap attribute, which will wrap the component definition in a specified tag (in this case, a tag) before applying any additional attribute logic. In this way, when the component's HTML is rendered, it will look like this:`html
type="checkbox" class="p-2 mx-auto" />
`
Notice that Presto applied the attribute
x-for to the specified wrapper, and not directly onto the
inside the component definition. This is determined by the order in which attributes are declared. When using $$wrap, any attributes that are declared after$$wrap is established will be coalesced onto the wrapper element, and not onto the component's root element.
$3
Examining that output, did you notice anything else? The
class attribute for the last
contained some mustache syntax as {{ showPreview }} which was rendered as: `html
`
This is because a property was passed in the component expression for
NoteThumbnail as ::showPreview. Presto components can receive properties using the syntax ::propName="value" on a component expression. Within the component, these property values are yielded using property tokens:`html
{{ propName }}
{{ propName | pipeName }}
`
Within the
of the component definition, property defaults can be given that are used when the component expression is absent of said property:`html presto name="NoteThumbnail" ::showPreview="hidden" ::showCheck="hidden" ::size="medium" > `
For the property
showPreview, a default value of "hidden" is given (display: none; in Tailwind CSS), but on the component expression for NoteThumbnail, this is overriden to an empty value as ::showPreview. In this way, you can make use of "boolean-style" properties for your components, where a truthy or falsy value is the property default that gets overriden by an empty value on a component expression.
$3
Reviewing the component expression for
NoteThumbnail you'll notice that the ::size property was passed as "large", but was rendered as:`html
`
In this case, before
size was expressed, it was processed by a pipe — a function accepting a single argument and returning a string:`js function size(arg) { return { large: 'h-16', medium: 'h-8', small: 'h-4', }[arg]; } `
Pipes can be useful where you'd like to use more "natural" language to express complex strings of data. In
NoteThumbnail it's being used to convert values of large, medium, and small into Tailwind CSS height classes. Back in the example presto.config.js, the pipe TailwindMxAlign is defined to convert left, right, and center into their margin equivalents — useful when making use of flexbox:`js TailwindMxAlign(arg) { return { left: 'mr-auto', center: 'mx-auto', right: 'ml-auto' }[arg === '' ? 'center' : arg]; } `
As you've probably noticed, there's two places where pipes can be defined. Where a pipe is only needed for a single component, it can be declared in a
.
Slots
Component slots in Presto work exactly as you'd expect. As of this writing, Presto supports one type of slot — the default slot. Named slots are under consideration, so if you'd like to see more development on this, please suggest an implementation strategy by raising an issue.
Within a component document, a default slot can be expressed using the
tag with an empty presto attribute:`html
Some default content goes here.
`
When using a component expression, the
will be fulfilled by including markup between the expression's tags:`html
This is my slot content.
`
If no content is supplied, Presto will render the default content expressed between the
tags in the component definition.
$3
Suppose you've defined a button component that you want to use with a slot:
basicbutton.html
`html
type="button" class="py-2 px-4 bg-{{ fill }}-500 border border-{{ fill }}-500 hover:bg-{{ fill }}-400 text-white transition ease-in duration-200 text-center text-base font-semibold rounded-lg w-{{ width }}" > {{ label }}
`
When you use the
BasicButton expression, you could fulfill the button's label in one of two ways:`html
Click Me!
`
This works because slot processing is the second step that takes place when parsing a component expression — right after the
$$wrap attribute is evaluated. Because the default slot content is the property token {{ label }}, Presto will have access to substitute a given value when evaluating the expression-assigned property ::label.
> #### Why would you want to do this? > > Using a property token as the default slot content can be helpful if you want the ability to globally-manipulate a component's slotted content. Through the use of config-provided property values, you can manage slot content in one location. > > This is also really useful for when using magic properties with Alpine, so please keep reading!
Magic Properties
Saving the best for last, magic properties are what make Presto the perfect companion for Alpine developers. Consider the
BasicButton component definition described above. If you wanted to make it more "Alpine-friendly," you could make some changes:`html
x-for, your component expression would look something like this:`html
`
That works, but it's less than ideal. In the component definition, you've had to do a lot of escaping and now, if you want to reuse the button outside of an Alpine context, you can't because
class is declared as x-bind:class and the button's label is expressed as x-text rather than native HTML. Additionally, you now have to surround static property values with single quotes, like the default values for fill and width.
Is there a better way? Of course there is.
$3
Let's restore the original version of the
BasicButton definition:`html
type="button" class="py-2 px-4 bg-{{ fill }}-500 border border-{{ fill }}-500 hover:bg-{{ fill }}-400 text-white transition ease-in duration-200 text-center text-base font-semibold rounded-lg w-{{ width }}" > {{ label }}
`
Now, instead of mangling the component definition, let's instead change the way that we write the component expression:
`html
`
Take note of the
$ chars added to the expression properties label and fill. When Presto compiles, this is what you'll see:`html
