@jsee_dev/elemen.ts NPM

Elemen.TS

A lightweight TypeScript library to build simple but dynamic SPA (Single Page Application).

Introduction

Ok, you might want to ask : another library like tons of others, what for ?

And this would be legitimate :wink:

Well, then you might want to know the reason why I made it. I was working on a web app that needed a back office, and I had the idea of making it myself from about scratch - because I enjoy building things that way, and because there is nothing better to strengthen your skills - using a front library that I would write myself. Also, I had the time to do it, and that is something.

So my purpose with this library is to simplify the building of simple - potentially rudimentary - interfaces, but with advanced dynamic features and the power of native TypeScript. 100% object oriented, this easy-to-use library will come in handy in many situations. Let's take a tour.

Setting up a new project

In this part, we will use Parcel as our bundler. Parcel natively features all we need to get started, and especially automatic TypeScript compiling. If you plan not to use Parcel, then you will have to install and configure a TypeScript compiler yourself.

Installation

Before we install Elemen.TS, let's make our environment ready :

If you use yarn :

# Initiate the project
$ yarn init -y

# Install parcel and parcel plugins
$ yarn add --dev parcel parcel-reporter-static-files-copy

If you use npm :

# Initiate the project
$ npm init -y

# Install parcel and parcel plugins
$ npm install --save-dev parcel parcel-reporter-static-files-copy

Almost done ! See ? Easy peasy.

Now in order to be able to serve static files, we will make a bit of configuration. Parcel needs to connect to the plugin we installed.

Create a .parcelrc file next to your package.json. It should look like this :

// .parcelrc

{
  "extends": ["@parcel/config-default"],
  "reporters": ["...", "parcel-reporter-static-files-copy"]
}

When it's done, go to your package.json file to set a few things :

// package.json

{
  "source": "src/index.html", // The entry point for Parcel, that would normally be an HTML document
  "staticFiles": {
    "staticPath": "src/assets", // The path of your static files
    "staticOutPath": "assets", // The build path of your static files inside the build folder (default: ./dist)
    "watcherGlob": "**" // ** enables full watching for change.
  },
}

For advanced tweaking of this plugin we're using, please visit the related github page here.

We're good to go with Parcel now ! They claim it to be (close to) zero configuration, so let's experiment...

To make your app running there are a few commands to know, which you can - sorry you should definitely - set as package.json scripts.

# DEV MODE. Bundles everything up and creates a dev server. Pretty cool, huh ?
$ parcel

# BUILD MODE. Bundles everything up and optimizes for production. Wicked.
$ parcel build --public-url ./

AND last but not least, install Elemen.TS (WTF is that again? here)

If you use yarn :

$ yarn add @jsee_dev/elemen.ts

If you use npm :

# Initiate the project
$ npm install @jsee_dev/elemen.ts

Usage

Project structuring

To start with, create an HTML file as your entry point. For the record, we're building Single Page Applications, which implies a one and only HTML file.

This page will contain at least a link to your TypeScript main file. Parcel will automatically compile/transpile it to JS during the building process. Note that you can also use Sass files the same way !

Also, like in many SPA libraries, you must set a root mounting point inside the body of your page. That's where your top level components will be inserted.

For example :

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Sensational Prime Application</title>
  <link rel="stylesheet" href="style.scss">
  <script src="scripts/main.ts" type="module" defer></script>
</head>
<body>
  <div id="root">
  </div>  
</body>
</html>

Cool, now let's dive into the core principles of Elemen.TS (to myself : "Relax. Everything's gonna be fine").

The "Goodbye Nobody" example

I was kind of bored with the classic "Hello World". How about that ? :blush:
To goal here will be to display a simple text element at the center of our page.

When working with Elemen.TS, we're seeing our web content in terms of components, each one of them made of elements. And we'll adopt an element-first approach, instead of trying to build things globally.

So first things first, let's make our Text element :

API Reference

Contributing

Although there are no guidelines about this topic at the moment, this project is wide open to contributors. Feel free to get in touch with me if you're interested !