copied to clipboard

Preamble

A Quick Forewarning

Elegance is still only in Beta.
There are absolutely no guarantees of backwards compatibility, security or really anything.
As such, elegance isn't really meant for production, yet.

What is Elegance?

Elegance is an opinionated, strict, compiled, fully-typescript,
web-framework designed for building feature-rich, yet fast and efficient web pages.

Elegance is written fully by hand, and dependencies are used very sparsely.
As of writing, esbuild is the only dependency.

A simple, fully-working (non gzipped) elegance page transfers only 4kB of data!For context, an "empty" (gzipped) react app on average transfers roughly 200-300kB of data.

This lack of JS sent to the browser is achieved through not creating unnecessary, wildly complex rude goldberg machines; and compilation instead of interpretation.

How Elegance Works

File Structure

An Elegance.JS projects file structure is akin to that of something like a Next.JS project.
We use filesystem routing, where each directory contains a page.ts file.

Page Files

The page.ts file has two requirements, it must export a page object, which is of type EleganceElement<"body">

export const page = body ({
    style: "background-color: #000; color: #fff;",
},
    h1 ("Greetings Traveler!"),
);

and it must also export a metadata function, which then resolves into an EleganceElement<"head">

export const metadata = () => head (
    title ("The BEST Page Ever!"),
);

Elements are created using simple, ambient global functions.
The above body() call, for example, gets turned into this.

{
    tag: "body",
    options: {
        style: "background-color: #000; color: #fff;",
    },
    children: [
        {
            tag: "h1",
            options: {
                innerText: "Greetings Traveler!",
            },
            children: [],
        },
    ],
}

The estute among you may have noticed that the result can easily be serialized into HTML or JSON.
This is precisely what the Elegance compiler does.

It recursively goes through the page, notes down any points of interest (more on this later),
and then serializes each element.

The resulting data can then either be used to serve static HTML pages,
(which still have all the normal features of Elegance, but won't get re-rendered),
or dynamically server-rendered content.

Metadata is of course a function, so that you may dynamically generate page information.

This is useful for something like a social media page,
where you may want need to fetch information about a post, and then display it in a nice rich embed.

Compilation

Elegance exposes a function called compile() which your project should call to build itself.
This is typically done via the use of the built in build scripts.
However, if you wish to customize your build options, you need just create a file which calls compile.

Compilation handles generating page_data files, HTML, JSON, transpilation of ts into js, etc.

We will explore compilation, state, reactivity, optimization, static generation, hot-reloading, and many of the other features of Elegance in greater-depth later on. However, this is all that you need to know for now.

Installation

NPM

To make an elegance project, first create a directory with a name of your choosing.
For this example, we'll use my-first-webpage
Then, in that directory, issue the following command to initialize an empty NPM project.

npm init -y

After this, install elegance-js by running

npm install elegance-js

And that's it! Elegance.js has been installed into your project.

Your First Page

Making a Project

To bootstrap an Elegance.js project, run the following command in the directory we just made.

npx bootstrap

This will create a few files and directories for you.
Firstly, it creates the aforementioned pages directory, and an example page.ts file.

Then it makes a public directory where you can store files
that you want to be publicly accessible on your website.

Thirdly, it creates an env.d.ts + tsconfig.json
which gives you ambient global typings for the elements that are in Elegance.

Lastly, it creates a file in the pages directory called index.css
which tailwind will automatically compile and put in your dist folder.

Running your project.

There's a few way to run elegance.

The intended way is using our provided scripts.

npx dev

npx prod

npx static

However, you may also serve the files in any way you like.

API Routes will not be available without the built-in Elegance server,
but all static content like event listeners, load hooks, pages, etc, will work.