DEV Community: Nhan Lam

Features, future-proof and interoperable in TiniJS apps

Nhan Lam — Sat, 04 May 2024 06:27:23 +0000

TiniJS adheres to the web standards! 🤝

With TiniJS Framework, beside the basic concepts such as Project Convention, App, Components, Pages, etc. and essential features such as Router, State Management, Back-end Solutions, etc. Our apps will definitely need more specific features for many different use cases.

Because TiniJS is based on the web standards, therefore in theory, anything that works in the browsers will work in TiniJS apps.

In this article, we will explore how to add features in a future-proof manner our TiniJS apps. To get started, you can download a starter template, or run:

npx @tinijs/cli@latest new my-app -t blank

The app instance

As in previous introduction guide of how to Get started with the TiniJS framework, we can see that a TiniJS app is started with an app root defined in ./app/app.ts, the file contains a class named AppRoot which extends the TiniComponent class and is decorated with the @App() decorator. The app root is where we initiate the app and incorporate features, a minimal app constructor looks like this:

import {html, css} from 'lit';
import {App, TiniComponent} from '@tinijs/core';

@App()
export class AppRoot extends TiniComponent {
  protected render() {
    return html`<h1>Hello, world!</h1>`;
  }

  static styles = css``;
}

From anywhere across our app, we can access the app instance using one of the following methods.

Using DOM methods:

// app-root is the only elem in the body
const app = document.body.firstElementChild;

// custom app-root placement
// <app-root id="xxx"></app-root>
const app = document.getElementById('xxx');

Using util and decorator:

import {getApp, UseApp} from '@tinijs/core';

import type {AppRoot} from '../app.ts';

/*
 * Via util
 */
const app = getApp();
const router = app.router;
const meta = app.meta;
// any other hosted by the app root

/*
 * Or, via decorator
 */
@Page({})
export class AppPageXXX extends TiniComponent {

  @UseApp() app!: AppRoot;

  onCreate() {
    const config = this.app.config;
    const ui = this.app.ui;
    // any other hosted by the app root
  }

}

Depend on the patterns you choose to add features to an app, the AppRoot plays a role as a host for defining such features (pattern 2 and 3) as we will see in the next section.

Add future-proof features

Features or dependencies in TiniJS apps are available in common forms:

Constants - any value, live in app/consts folder
Utilities - single responsible functions (in app/utils)
Services - groups of related utils (in app/services)

Those features are not limited to be used with TiniJS Framework, once written it can be use with any other frameworks or no framework.

But when it comes to work with dependencies in TiniJS apps, there are 3 main patterns to be considered, we can use one or all of them in our apps.

Pattern 1: Imports

Just simply import the utils and services directly to your components, pages. This is the common and most convenient way to work with utils and services.

You can use the generate command of Tini CLI to quickly scaffold consts, utils and services, run npx tini generate const|util|service <name>.

Step 1: Define consts, utils and services (in one or more files):

// define consts in app/consts folder
export const FOO = 'foo';

// define utils in app/utils folder
export function foo() {
  return 'foo';
}

// define services in app/services folder
class FooService {
  foo() {
    return 'foo';
  }
}
export const fooService = new FooService();

Step 2: Use consts, utils and services:

// in pages, components, ...
import {FOO} from '../consts/foo.js';
import {foo} from '../utils/foo.js';
import {fooService} from '../services/foo.js';

Pattern 2: Provide/Inject

TiniJS also provides a dependency injection mechanism (called Lazy DI) that allows you to lazy load and inject utils and services to your components, pages.

Step 1: Define dependencies (preferably in their own files):

// consts
export const FOO = 'foo';
export default FOO;
export type FooConst = typeof FOO;

// utils
export function foo() {}
export default foo;
export type FooUtil = typeof foo;

// services
export class FooService {}
export default FooService;

Step 2: Provide dependencies in app/app.ts:

import type {DependencyProviders} from '@tinijs/core';

export const providers: DependencyProviders = {
  'FOO': () => import('./consts/foo.js'),
  'foo': () => import('./utils/foo.js'),
  'fooService': () => import('./services/foo.js'),
  // services depend on other dependencies or values
  'otherService': {
    provider: () => import('./services/other.js'),
    deps: [
      'fooService', // a string means using dependencies
      () => 'value', // a function means using values
    ],
  }
};

@App({ providers })
export class AppRoot extends TiniComponent {}

Step 3: Inject dependencies:

import {Inject} from '@tinijs/core';

import type {FooConst} from '../consts/foo.js';
import type {FooUtil} from '../utils/foo.js';
import type {FooService} from '../services/foo.js';

@Page({})
export class AppPageXXX extends TiniComponent {

  @Inject() FOO!: FooConst;
  @Inject() foo!: FooUtil;
  @Inject() fooService!: FooService;

  // lazy load dependencies are available started from onInit() lifecycle hook
  onInit() {
    // this.FOO
    // this.foo()
    // this.fooService.foo()
  }

}

Pattern 3: Plugins via Contexts

Values, utils and services can be provided and consumed using contexts.

Install Lit Context: npm i @lit/context, for usage details please visit https://lit.dev/docs/data/context/.

You can use the generate command of Tini CLI to quickly scaffold contexts, run npx tini generate context <name>.

Step 1: Define plugins in app/contexts:

import {createContext} from '@lit/context';

export type PluginsContext = typeof plugins;

export const pluginsContext = createContext<PluginsContext>(
  Symbol('plugins-context')
);

export const plugins = {
  FOO: 'foo',
  foo: () => 'foo',
  fooService: new FooService(),
};

You can also split plugins into their own contexts, so that you can consume them individually.

Step 2: Register plugins in app/app.ts:

import {provide} from '@lit/context';

import {pluginsContext, plugins} from './contexts/plugins.ts';

@App()
export class AppRoot extends TiniComponent {

  @provide({context: pluginsContext}) $plugins = plugins;

}

Step 3: Use plugins:

import {consume} from '@lit/context';

import {pluginsContext, type PluginsContext} from '../contexts/plugins.ts';

@Page({})
export class AppPageXXX extends TiniComponent {

  @consume({context: pluginsContext}) $plugins!: PluginsContext;

  onCreate() {
   // this.$plugins.FOO
   // this.$plugins.foo()
   // this.$plugins.fooService.foo()
  }

}

Interoperable with other frameworks

Let admits the undeniable fact that we the JavaScript users are very proud about our framework of choice, there is even a war between developers to decide which framework is the best. Imagine telling a React developer to include the Vue or Angular runtime in their apps, it is outraged for sure.

Stop waging wars, be excellent to each other. 🩷

The TiniJS Framework is different, it is the first of its kind, which is designed to be used in conjunction with other frameworks as well, it means we may use other frameworks in TiniJS apps and in the other hand using TiniJS features in apps built using other frameworks. Interoperable is a comprehensive topic, we will explore more along the way with future articles. But, below is a basic introduction about the aspect.

For demonstration, we will use Vue 3 in a TiniJS app, install npm i vue.

import {ref, createRef, type Ref} from 'lit/directives/ref.js';
import {createApp} from 'vue/dist/vue.esm-bundler.js';

@Page({})
export class AppPageXXX extends TiniComponent {

  private readonly vueAppRef: Ref<HTMLDivElement> = createRef();

  onFirstRender() {
    const vueApp = this.vueAppRef.value!;
    createApp({
      template: `
        <div>
          <h1>Hello Vue 3!</h1>
          <p>Nice to have you here.</p>
        </div>
      `
    }).mount(vueApp);
  }

  protected render() {
    return html`<div ${ref(this.vueAppRef)}></div>`;
  }

}

For more features and stuffs, please visit https://tinijs.dev.

Thank you for spending time with me. If there was anything not working for you, please leave a comment or open an issue or ask for help on Discord, I'm happy to assist.

Wish you all the best and happy coding! 💖

Router, pages, layouts and async data in TiniJS apps

Nhan Lam — Sat, 27 Apr 2024 07:43:54 +0000

Welcome again, friends! 🥳

In the previous topic, we explored about how to get started with the TiniJS Framework, if you have not read it yet, please see Getting started with TiniJS framework.

Today topic we will explore:

The Tini Router and alternatives
Working with Pages and layouts
Employ route guards
Scroll to anchors inside Shadow DOM
Title and meta tags management
Fetch and render async data

To get started, you can download the Blank starter template, or run:

npx @tinijs/cli@latest new my-app -t blank

Pages

Pages in TiniJS apps are special components which purpose are to represent views or endpoints of the app. Creating and working with pages is very similar to how we would work with components.

To quickly create a page, we can use the Tini CLI to generate it.

npx tini generate page xxx

Or, create a ./app/pages/xxx.ts file manually, a page looks like this:

import {html, css} from 'lit';
import {Page, TiniComponent} from '@tinijs/core';

@Page({
  name: 'app-page-xxx',
})
export class AppPageXXX extends TiniComponent {

  protected render() {
    return html`<p>This is a page!</p>`;
  }

  static styles = css``;
}

Beside the @Page() decorator, everything else would work the same as any component. But, please note the name: 'app-page-xxx' property, it plays a role later when we setup the Tini Router.

Layouts

Layouts in TiniJS apps are also special components which purpose are to share common elements between pages. You can think of layouts as containers of pages.

To quickly create a layout, we can use the Tini CLI to generate it.

npx tini generate layout xxx

Or, create a ./app/layouts/xxx.ts file manually, a layout looks like this:

import {html, css} from 'lit';
import {Layout, TiniComponent} from '@tinijs/core';

@Layout({
  name: 'app-layout-xxx',
})
export class AppLayoutXXX extends TiniComponent {

  protected render() {
    return html`
      <div class="page">
        <header>...</header>
        <slot></slot>
        <footer>...</footer>
      </div>
    `;
  }

  static styles = css``;
}

Beside the @Layout() decorator and the <slot></slot> in the template, everything else would work the same as any component. But, please note the name: 'app-layout-xxx' property, it plays a role later when we setup the Tini Router.

Tini Router

Tini Router is the default way to add routing capability to TiniJS apps. There are also other routers you may use with TiniJS, such as: Vaadin Router and Lit Router.

For today topic, we will only explore the usage of Tini Router, it has several useful features:

Bundle or lazy load pages
Routes with layouts
Many param patterns
Navigate using the a tag
Route guards
404 pages
And more

Define routes

To define routes, we create the file ./app/routes.ts and add the route entries, for example:

import type {Route} from '@tinijs/router';

export const routes: Route[] = [
  {
    path: '',
    component: 'app-layout-default',
    children: [
      {
        path: '',
        component: 'app-page-home',
        action: () => import('./pages/home.js'),
      },
      {
        path: 'post/:slug',
        component: 'app-page-post',
        action: () => import('./pages/post.js'),
      },

      // more app routes
    ],
  },
  {
    path: 'admin',
    component: 'app-layout-admin',
    children: [
      {
        path: '',
        component: 'app-page-admin-home',
        action: () => import('./pages/admin-home.js'),
      },

      // more admin routes
    ],
  },
  {
     path: '**',
     component: 'app-page-404',
     action: () => import('./pages/404.js'),
  },
];

We can model our app routing system in several ways.

Without layout

Serve pages directly without a layout.

export const routes: Route[] = [
  {
    path: '',
    component: 'app-page-home',
  },
  {
    path: 'about',
    component: 'app-page-about',
  },
];

With layouts

Share similar elements between pages.

export const routes: Route[] = [
  {
    path: '',
    component: 'app-layout-default',
    children: [
      {
        path: '',
        component: 'app-page-home',
      },
      {
        path: 'about',
        component: 'app-page-about',
      },
    ],
  },
];

Bundle or lazy load

You can either bundle or lazy load pages and layouts. Please note that for bundled layouts and pages, they must be imported first either in routes.ts or app.ts.

import './layouts/default.js';
import './pages/home.js';

export const routes: Route[] = [

  // bundled layout
  {
    path: '',
    component: 'app-layout-default',
    children: [

      // bundled page
      {
        path: '',
        component: 'app-page-home',
      },

      // lazy-loaded page
      {
        path: 'about',
        component: 'app-page-about',
        action: () => import('./pages/about.js'),
      },
    ],
  },

  // lazy-loaded layout
  {
    path: 'admin',
    component: 'app-layout-admin',
    action: () => import('./layouts/admin.js'),
    children: [
      // ...
    ],
  },
];

Route parameters

Route parameters are defined using an express.js-like syntax. The implementation is based on the path-to-regexp library, which is commonly used in modern frontend libraries and frameworks.

The following features are supported:

Type	Syntax
Named parameters	profile/:user
Optional parameters	:size/:color?
Zero-or-more segments	kb/:path*
One-or-more segments	kb/:path+
Custom parameter patterns	image-:size(\d+)px
Unnamed parameters	(user[s]?)/:id

// courtesy of: https://hilla.dev/docs/lit/guides/routing#parameters

export const routes: Route[] = [
  {path: '', component: 'app-page-home'},
  {path: 'profile/:user', component: 'app-page-profile'},
  {path: 'image/:size/:color?', component: 'app-page-image'},
  {path: 'kb/:path*', component: 'app-page-knowledge'},
  {path: 'image-:size(\\d+)px', component: 'app-page-image'},
  {path: '(user[s]?)/:id', component: 'app-page-profile'},
];

404 routes

You can define one or more 404 routes to catch not found routes, set path to **.

There are 2 level of 404: layout level and global level. The router will use the layout 404 first if no definition found at the layout level, it will then use the global 404.

export const routes: Route[] = [
  {
    path: '',
    component: 'app-layout-default',
    children: [
      // layout routes

      {
       path: '**',
       component: 'app-page-404-layout-default',
       action: () => import('./pages/404-layout-default.js'),
      },
    ],
  },

  // other routes

  // global 404
  {
     path: '**',
     component: 'app-page-404-global',
     action: () => import('./pages/404-global.js'),
  },
];

Init the Router

After defining routes for the app, next step would be init a router instance and register the routes.

From the app.ts we import the defined routes, create a router instance and add the router outlet to the template.

import {createRouter} from '@tinijs/router';

import {routes} from './routes.js';

@App({})
export class AppRoot extends TiniComponent {

  readonly router = createRouter(routes, {linkTrigger: true});

  protected render() {
    return html`<router-outlet .router=${this.router}></router-outlet>`;
  }

}

Navigate between pages

With the option linkTrigger: true enabled, you can navigate between pages using the a just like normal links.

<a href="/">Home</a>
<a href="/about">About</a>
<a href="/post/post-1">Post 1</a>

You can also use the <tini-link> component provided by the Tini UI when link trigger disabled (not set or linkTrigger: false), it has a similar signature compared to the a tag and other useful stuffs, such as marked as active link.

<tini-link href="/">Home</tini-link>
<tini-link href="/about" active="activated">About</tini-link>
<tini-link href="/post/post-1" active="activated">Post 1</tini-link>

Access router and params

You can also navigate between pages in the imperative manner by using the go() method from a router instance.

import {getRouter, UseRouter, type Router} from '@tinijs/router';

@Page({})
export class AppPageXXX extends TiniComponent {

  // via decorator
  @UseRouter() readonly router!: Router;

  // or, via util
  readonly router = getRouter();

  protected render() {
    return html`<button @click=${() => this.router.go('/')}>Go home</button>`;
  }

}

Access current route and params is similar to access router instance.

import {UseRoute, UseParams, type ActivatedRoute} from '@tinijs/router';

@Page({})
export class AppPageXXX extends TiniComponent {

  // current route
  @UseRoute() readonly route!: ActivatedRoute;

  // route params
  @UseParams() readonly params!: {slug: string};

}

Route hooks and guards

Lifecycle hooks are used to perform actions when a route is activated or deactivated:

onBeforeEnter(): called when the route is about to be activated
onAfterEnter(): called when the route is activated
onBeforeLeave(): called when the route is about to be deactivated
onAfterLeave(): called when the route is deactivated

You can intercept the navigation process by returning a string or a function from the onBeforeEnter and onBeforeLeave hook:

nullish: continue the navigation process
string: cancel and redirect to the path
function: cancel and execute the function

@Page({})
export class AppPageAccount extends TiniComponent {

  onBeforeEnter() {
    if (user) return; // continue
    return '/login'; // redirect to login page
  }

}

You can also perform async actions inside hooks, then it will wait for the actions to be resolved before process further.

Scroll to anchors

Because we use the Shadow DOM to encapsulate our app, the browser seems to be unable to serve us the correct section when we present a link with an anchor fragment /post/post-1#section-a.

Tini Router provides some methods to direct visitors to the respected sections and retrieve section headings for outlined purpose (aka. table of content).

import {ref, createRef, type Ref} from 'lit/directives/ref.js';

@Page({})
export class AppPageXXX extends TiniComponent {

  @UseRouter() readonly router!: Router;

  private _articleRef: Ref<HTMLElement> = createRef();

  onRenders() {
    // will scroll to the #whatever section if presented
    this.router.renewFragments(
      this._articleRef.value!,
      { delay: 500 }
    );

    // will scroll to the #whatever section if presented
    // add extract all the available headings
    // IMPORTANT!!!:
    //   + please don't: never change a local state in onRenders() or updated() or it will cause a render loop
    //   + please do: store 'fragments' in a global state or emit out to the parent component or employ render checkers
    const fragments = this.router
      .renewFragments(this._articleRef.value!, {delay: 500})
      .retrieveFragments();
  }

  protected render() {
    return html`
      <article ${ref(this._articleRef)}>
        ...
      </article>
    `;
  }

}

Async data

Pages are usually rendered based on some async data from server. You can use these techniques to work with such cases.

Task render

The @lit/task package provides a Task reactive controller to help manage this async data workflow.

import {Task} from '@lit/task';

@Page({})
export class AppPageXXX extends TiniComponent {

  @Reactive() productId?: string;

  private _productTask = new Task(this, {
    task: async ([productId], {signal}) => {
      const response = await fetch(`http://example.com/product/${productId}`, {signal});
      if (!response.ok) { throw new Error(response.status); }
      return response.json() as Product;
    },
    args: () => [this.productId]
  });

  protected render() {
    return this._productTask.render({
      pending: () => html`<p>Loading product...</p>`,
      complete: (product) => html`
          <h1>${product.name}</h1>
          <p>${product.price}</p>
        `,
      error: (e) => html`<p>Error: ${e}</p>`
    });
  }

}

For more detail, please see https://lit.dev/docs/data/task/

Section render

Similar to Task Render, Section Render renders a section of a page based on the values of local states. There are 4 render states:

main (complete): all are not undefined and not empty (empty is null or [] or {} or zero-size Map)
error: any instanceof Error
empty: all are empty
loading: else

import {sectionRender, type SectionRenderData} from '@tinijs/core';

@Page({})
export class AppPageXXX extends TiniComponent {

  @Reactive() product: SectionRenderData<Product>;

  async onInit() {
    this.product = await fetchProduct();
  }

  protected render() {
    return sectionRender([this.product], {
      loading: () => html`<p>Loading product ...</p>`,
      empty: () => html`<p>No product found!</p>`,
      error: () => html`<p>Errors!</p>`
      main: ([product]) => html`
        <h1>${product.name}</h1>
        <p>${product.price}</p>
      `,
    });
  }

}

Title and meta tags

To update page title and meta when navigating to different pages, init a meta instance at app.ts.

import {initMeta} from '@tinijs/meta';

@App({})
export class AppRoot extends TiniComponent {

  readonly meta = initMeta({
    metadata: undefined, // "undefined" means use the extracted values from index.html
    autoPageMetadata: true,
  });

}

Static pages

When autoPageMetadata: true for page which is static, meta can be provide via the metadata property.

import type {PageMetadata} from '@tinijs/meta';

@Page({})
export class AppPageXXX extends TiniComponent {

  readonly metadata: PageMetadata = {
    title: 'Some title',
    description: 'Some description ...',
    // ...
  };

}

Dynamic pages

For pages with data comes from the server, we can access the meta instance and set page metadata accordingly.

import {UseMeta, Meta} from '@tinijs/meta';

@Page({})
export class AppPageXXX extends TiniComponent {

  @UseMeta() readonly meta!: Meta;

  async onInit() {
    this.post = await fetchPost();
    this.meta.setPageMetadata(post);
  }

}

Next topic will be: Adding features to TiniJS apps.

Thank you for spending time with me. If there was anything not working for you, please leave a comment or open an issue or ask for help on Discord, I'm happy to assist.

Wish you all the best and happy coding! 💖

Getting started with TiniJS framework

Nhan Lam — Sat, 20 Apr 2024 07:20:26 +0000

Good weekend, friends! 😚

In the previous post, I have introduced you to a project that I'm currently working on - the TiniJS Framework, if you haven't read it yet, I invite you to check it out - I've created yet another JavaScript framework.

Today we are going to explore the basic concepts of a TiniJS app, including project structure, dev/build tools and components.

To get started, you can download a starter template, or run npx @tinijs/cli@latest new my-app, or try the example apps on Stackblitz:

Photo Gallery App: https://stackblitz.com/edit/try-tinijs
To Do App: https://stackblitz.com/edit/try-tinijs-todo-app

Project structure

For a quick note about the term Projects in the TiniJS platform. Since the TiniJS platform is designed to be as versatile as possible, which means it is able to work with many favorite tools and other frameworks or no frameworks. Therefore, a TiniJS project could be literally any project as long as it involves one or more TiniJS aspects. For example: a Vue app using Tini UI, a React app using Tini Content, a project using Tini CLI expansion, ... More about interoperable will be discussed along the way with future articles.

For this article, we will focus on projects involving an app built using TiniJS core framework. That's being said, let explore TiniJS apps.

A TiniJS app may have any folder structure as you see fit for what you are comfortable to work with. But as a convention, I recommend you use the below structure for most of the case. At the very basic, an app must have two files:

Item	Description
app/`index.html`	The entry point of the single page app, where you define: title, meta tags, includes fonts, init app root, ...
app/`app.ts`	The `app-root` element is where you create a TiniJS client app, register config, setup router, setup UI, ...

As your app grows, we will add different types of code, there are places for different things inside a TiniJS app, we can organize them into these files and folders:

Item	Description
`tini.config.ts`	The main configuration source for various purposes across the TiniJS platform.
app/`routes.ts`	For Tini Router, where you define routing behavior of the app.
app/`providers.ts`	Working with services, utils, ... depend on the pattern, you may choose to provide dependencies at the app level, then lazy load them later and inject to pages and components.
app/`assets`	For static assets such as images, SVG icons, ...
app/`public`	For assets which will be copied as is upon build time and can be accessed from public URLs.
app/`types`	Shared Typescript types.
app/`configs`	Client app configuration files based on environments: development.ts, qa.ts, stage.ts, production.ts, ... when using with the Default Compiler, depend on the target environment, a specific config file will be applied.
app/`components`	Reusable app components implement the `TiniComponent` class.
app/`pages`	App pages for routing purpose.
app/`layouts`	Layouts for pages.
app/`icons`	Reusable icon components.
app/`partials`	Small re-usable html templates which can be included in components and pages.
app/`utils`	Any type of shareable logic functions, depend on the pattern, you can either import or inject them.
app/`services`	Groups of related utilities, you can either import or inject them.
app/`consts`	Shared constants.
app/`classes`	Constructors which are intended to be used to construct objects.
app/`stores`	Stores for global states management.
app/`contexts`	Consumable contexts for mitigating prop-drilling.

When integrate with other tools and frameworks, the specific integrated code will live in its own folder at the same level as the app folder.

Dev and build tools

The development and build workflow of TiniJS are backed by any of your favorite tools. You can either set them up manually or automatically using Tini CLI and official builders. Some of the tools currently available are: Vite, Parcel and Webpack.

In theory, you can use any other tools (Turbo Pack, Gulp, ...). But I don't have time to try them, it is opened up for community contribution.

Vite (recommended, default)

Homepage: https://vitejs.dev/

Option 1: Via Tini CLI (recommended)

Install: npm i -D @tinijs/cli @tinijs/vite-builder
Add scripts:
- dev: tini dev
- build: tini build

Option 2: Or, manually

Install: npm i -D vite
Add scripts:
- dev: vite app
- build: vite build app --outDir www

Parcel

Homepage: https://parceljs.org/

Option 1: Via Tini CLI (recommended)

Install: npm i -D @tinijs/cli @tinijs/parcel-builder
Config tini.config.ts, set build.builder to @tinijs/parcel-builder
Add scripts:
- dev: tini dev
- build: tini build

Option 2: Or, manually

Install: npm i -D parcel @parcel/config-default
Add scripts:
- dev: parcel app/index.html --dist-dir www
- build: parcel build app/index.html --dist-dir www

Additional setup

Either using Tini CLI or setup manually, you need to do these additional setup.

Modify package.json

{
  "browserslist": "> 0.5%, last 2 versions, not dead",
  "@parcel/resolver-default": {
    "packageExports": true
  }
}

Webpack

Homepage: https://webpack.js.org/

Option 1: Via Tini CLI (recommended)

Install: npm i -D @tinijs/cli @tinijs/webpack-builder
Config tini.config.ts, set build.builder to @tinijs/webpack-builder
Add scripts:
- dev: tini dev
- build: tini build

Option 2: Or, manually

Install: npm i -D webpack webpack-cli webpack-dev-server html-bundler-webpack-plugin ts-loader
Add webpack.config.cjs, please see example.
Add scripts:
- dev: webpack serve --history-api-fallback --mode development
- build: webpack build --mode production

Working with Components

Components are basic building blocks of TiniJS apps. They are custom elements which extend the standard HTMLElement - the base class of native HTML elements. Since TiniJS is based on Lit, so it is nice to know how to define a component using LitElement, but it is not required because we will explore the basic concepts together.

Create components

To quickly scaffold a component using Tini CLI, run npx tini generate component <name>, a component file will be created at app/components/<name>.ts.

A TiniJS component looks like this:

import {html, css} from 'lit';
import {Component, TiniComponent} from '@tinijs/core';

@Component()
export class AppXXXComponent extends TiniComponent {
  static readonly defaultTagName = 'app-xxx';

  // Logic here

  protected render() {
    return html`<p>Template here</p>`;
  }

  static styles = css`/* Style here */`;
}

There are 3 main sections:

Logic: class properties and methods for defining properties, internal states, events and other logic.
Template: HTML template with Lit html template literal syntax.
Style: CSS for styling the template.

Using components

To consume components, you must first register them, either globally or locally.

Register components globally at the app level, this is convenient since you only need to do it once per component, but it has the drawback that the initial bundle also includes all the related constructors.

// register components globally in app/app.ts

import {AppXXXComponent} from './components/xxx.js';

@App({
  components: [AppXXXComponent]
})
export class AppRoot extends TiniComponent {}

Components can also be registering locally at layout, app or component level. The benefit is that certain components will come with lazy-load pages instead of app initialization. The drawback is that it is repetitive (I think of auto import in the future, it may help a little).

// register components locally

import {AppXXXComponent} from '../components/xxx.js';

@Component|Page|Layout({
  components: [AppXXXComponent]
})
export class ComponentOrPageOrLayout extends TiniComponent {}

Notice that there is defaultTagName = '...'. It is the default tag name of the component, you can register a component with a different tag name, use this syntax:

// AppFooComponent has the default tag name
static readonly defaultTagName = 'app-foo';

// register a different tag name
{
  components: [
    AppXXXComponent,
    [AppFooComponent, 'bar-baz-qux']
  ]
}

After register, you can use the tag <app-xxx></app-xxx> and <bar-baz-qux></bar-baz-qux> just like they are native HTML tags.

Props and events

Components usually has properties and events for data exchange and interaction.

Properties

Use the decorator @Input() or @property() to define properties.

import {property} from 'lit/decorators/property.js';
import {Input} from '@tinijs/core';

@Component()
export class AppXXXComponent extends TiniComponent {

  // Lit syntax
  @property() prop1?: string;

  // or, TiniJS syntax
  @Input() prop2?: {foo: number};

}

Passing properties to components is similar to set attributes in native HTML elements, string values as in key="value" and non-string as in .key=${varOrValue}.

html`<app-xxx prop1="Lorem ipsum" .prop2=${{ foo: 999 }}></app-xxx>`

Beside define properties, you can also use Contexts as a form of communicating data. Sometime certain values are required by many components in a long-nested chain of components, passing values down the whole chain (aka. prop drilling) would be very annoying. Use contexts to provide and consume such values is more efficient. Please see more detail at https://lit.dev/docs/data/context/.

Events

Use the decorator @Output() to define events.

import {Output, type EventEmitter} from '@tinijs/core';

@Component()
export class AppXXXComponent extends TiniComponent {
  @Output() event1!: EventEmitter<string>;
  @Output() event2!: EventEmitter<{ foo: number }>;

  emitEvent1() {
    this.event1.emit('Lorem ipsum');
  }

  protected render() {
    return html`<button @click=${() => this.event2.emit({ foo: 999 })}></button>`;
  }
}

Event payloads can be accessed via the detail field.

html`
  <app-xxx
    @event1=${({detail: event1Payload}: CustomEvent<string>) => console.log(event1Payload)}
    @event2=${({detail: event2Payload}: CustomEvent<{ foo: number }>) => console.log(event2Payload)}
  ></app-xxx>
`

Handle states

By default, class properties changes won't trigger the UI changes. In order to trigger render() every time a value changes you must implicitly define a state, states can either be local or global.

Local states

The properties defined using @property() or @Input() as we see above are already local states which means changing those properties will trigger render().

To define local states but not in the form of property, use the @state() or @Reactive().

import {state} from 'lit/decorators/state.js';
import {Reactive} from '@tinijs/core';

@Component()
export class AppXXXComponent extends TiniComponent {

  // Lit syntax
  @state() state1?: string;

  // or, TiniJS syntax
  @Reactive() state2: number = 123;

  protected render() {
    return html`
      <div>${this.state1}</div>
      <div>${this.state2}</div>
    `;
  }
}

Global states

States can also be organized in some central places (aka. stores). You can use Tini Store (very simple, ~50 lines) or other state management solutions such as MobX, TinyX, ...

Getting started with Tini Store by install npm i @tinijs/store. Then create a store:

import {createStore} from '@tinijs/store';

export const mainStore = createStore({
  foo: 'bar'
});

After creating a store, you now can access its states, subscribe to state changes and mutate states.

import {Subscribe} from '@tinijs/store';

import {mainStore} from './stores/main.js';

/*
 * Access states
 */

const foo = mainStore.foo;

/*
 * Mutate states
 */

// assign a new value
mainStore.foo = 'bar2';

// or, using the 'commit' method
mainStore.commit('foo', 'bar3');

/*
 * Subscribe to state changes
 */

@Component()
export class AppXXXComponent extends TiniComponent {

  // Use the @Subscribe() decorator
  // this.foo will be updated when mainStore.foo changes it is reactive by default
  @Subscribe(mainStore) foo = mainStore.foo;

  // use a different variable name
  @Subscribe(mainStore, 'foo') xyz = mainStore.foo;

  // to turn of reactive, set the third argument to false
  @Subscribe(mainStore, null, false) foo = mainStore.foo;

  // Or, subscribe and unsubscribe manually
  onInit() {
    this.unsubscribeFoo = mainStore.subscribe('foo', value => {
      // do something with the new value
    });
  }
  // NOTE: remember to unsubscribe when the component is destroyed
  onDestroy() {
    this.unsubscribeFoo();
  }

}

Use Signals

Another method for managing states is using Signals. Signals are an easy way to create shared observable state, state that many elements can use and update when it changes. Please see more detail at https://www.npmjs.com/package/@lit-labs/preact-signals.

Lifecyle hooks

Custom elements created by extending HTMLElement as well as LitElement have their lifecycle hooks for tapping into when needed, please see https://lit.dev/docs/components/lifecycle/ for more detail.

There are some other hooks supported by TiniComponent, includes: OnCreate, OnDestroy, OnChanges, OnFirstRender, OnRenders, OnInit, OnReady, OnChildrenRender, OnChildrenReady. Here is a quick summary of them.

OnCreate

Alias of connectedCallback() without the need of calling super.connectedCallback(). The very beginning of a component, the element has got connected to the DOM (more detail).

import {type OnCreate} from '@tinijs/core';

export class Something extends TiniComponent implements OnCreate {
  onCreate() {}
}

OnDestroy

Alias of disconnectedCallback() without the need of calling super.disconnectedCallback(). The end of an element, got removed from the DOM (more detail).

import {type OnDestroy} from '@tinijs/core';

export class Something extends TiniComponent implements OnDestroy {
  onDestroy() {}
}

OnChanges

Alias of willUpdate() of LitElement. Used to computed values using in the render() (more detail).

import {type OnChanges} from '@tinijs/core';

export class Something extends TiniComponent implements OnChanges {
  onChanges() {}
}

OnFirstRender

Alias of firstUpdated() of LitElement. The render() has run the first time (more detail).

import {type OnFirstRender} from '@tinijs/core';

export class Something extends TiniComponent implements OnFirstRender {
  onFirstRender() {}
}

OnRenders

Alias of updated() of LitElement. Changes has been updated and rendered (more detail).

import {type OnRenders} from '@tinijs/core';

export class Something extends TiniComponent implements OnRenders {
  onRenders() {}
}

OnInit

Can be used in interchangeable with OnCreate. When use with Lazy DI injection, injected dependencies available starting from onInit(), usually used to handle async tasks.

import {type OnInit} from '@tinijs/core';

export class Something extends TiniComponent implements OnInit {
  async onInit() {}
}

OnReady

Similar to OnFirstRender but it only counts after any async tasks in OnInit has been resolved and render (first stateful render).

import {type OnReady} from '@tinijs/core';

export class Something extends TiniComponent implements OnReady {
  async onReady() {}
}

Next topic: Working with pages, layouts, meta management and the Router.

Thank you for spending time with me. If there was anything not working for you, please leave a comment or open an issue or ask for help on Discord, I'm happy to assist.

Wish you all the best and happy coding! 💖

I've created yet another JavaScript framework

Nhan Lam — Sat, 13 Apr 2024 13:57:46 +0000

It's 2024 and you've created yet another JavaScript framework. Seriously man!

When talking about another Javascript framework, you may laugh and think that there are tons of proven options out there why bother creating another one? 🤷‍♂️

Let me share with you my personal story which leads to the development of a new Javascript framework. But if you don't care about my pathetic story, here is the TLDR:

TiniJS is a meta framework powered by the Web Components technology based on the Google Lit library.

You can start by trying out an example on Stackblitz. Or downloading a starter template. Or initialize an app using the CLI, run npx @tinijs/cli@latest new my-app and follow the instruction.

For more detail, please see the Get started section below or visit https://tinijs.dev/.

The story

Joke aside, I'm not an expert in Javascript, but for a little bit about my background so you may know my anoyance story regarding front-end web development. I used to be an Angular developer back in the version 1 of it and currently working mainly with Vue and accasionally jQuery. I had these 3 PITA (Pain In The *beep*) experience which motivated me to experiment with the TiniJS framework.

PITA #1 - BUILDING A GOOD UI/UX IS HARD, IT IS TEDIOUS AND TIME CONSUMING!

Back in around 2010, there are two distint kinds of websites: the one with a ton of texts, links, barely any images here and there; and the others are with overwhelmed graphical elements such as GIF images, Flash background, rainbown cursors, ...

People tend to have the stereo type that back-end is hard and front-end is easy. It's kinda true, but not entirely, I mean, who am I to blame, right? Because with a little bit knowledge of HTML and CSS, you can pretty much build a static website very easily. But, in order to build a good UI/UX, there is much more to be considered. You have to be a master of many more things, and they are not easy at all!

PITA #2 - CSS FRAMEWORKS ARE LACK OF FUNCTIONALITIES AND CUSTOMIZING THEM IS NOT VERY EFFICIENT!

People realized the difficulty of front-end development and started to build CSS frameworks to help with the problem. Bootstrap is one of the pioneers of this trend, other popular ones are: Foundation, Semantic UI, Bulma, Skeleton, Pure CSS, ... Those CSS frameworks are great, no doubt about that, they help us to build a good UI/UX faster, but they also have their own limitations.

First, despite the fact that all the frameworks provide certain ways to customize the style, but overall, I feel that it is not very easy and reusable to me.

Second, is the lack of functionalities. I mean, they are mainly CSS, they provide some functions, usually as plugins to JQuery. Most of the cases you have to write your own Javascript to make a feature works.

PITA #3 - JAVASCRIPT FRAMEWORKS ARE OVERWHELMING AND SOMEWHAT REDUNDANT!

Enter the modern era of web development, Javascript frameworks are the new trend. But the problem is that we have so many choices, it is both a blessing and a curse. They provide great functions but not very interoperable, you can't just take a piece of code from one framework and use it in another. Especially, creating a UI system with separated packages for specific frameworks is a very daunting task.

Every time I start a project or do some kind of front-end work, the fragmentation of front-end web is somewhat painful to me. That seems to be the way of life, there is no avoid, isn't it? Please don't get me wrong, I'm not against any framework, I tend to choose solutions and not technologies, so if it works for you, just go with it. But I wonder to myself is there any way to somehow unify or lessen the gap in front-end development experience? 🤔

Introducing TiniJS

That is the reason why I experiment with the TiniJS framework for a while. It is a collection of tools for developing web/desktop/mobile apps using the native Web Component technology, based on the Lit library. Thank you the Lit team for creating a great tool assists us working with standard Web Component easier.

It is aimed to be as much standard, small and versatile as possible. Not really comparable to other frameworks and meta-frameworks, but overall, it has similar capabilities and also in the other hand, key differences. It is both a replacement choice and a complement to other frameworks. You may use TiniJS to build a various type of apps: landing pages, SPAs, PWAs, desktop apps, mobile apps, ... Feature-wise, anything works in Javascript should work fine in a TiniJS app.

The whole system consists of several parts, this is a quick introduction.

Please note that not all the parts available now, the project is at an early stage, some are previously experiments, I try my best to bring them live as soon as possible. But I have limited time and resource, so please bear with me and perhaps please lend me a hand if possible. 🙇‍♂️
The plan for V1 and its roadmap can be found at https://github.com/tinijs/tinijs
[Update - 2024/05/01] Version 0.18.x adds PWA module, Content module and Server module and many improvements.

Core

At the core, TiniJS provides a conventional project structure with a streamline development pipeline. There are folders for organizing stuffs, a local server for development, upon distribution, you can choose Vite or Parcel or Webpack to build the production.

The core also includes: the Router for navigating between pages, a simple Store for global state management, PWA supported, ...

You can try example projects:

UI system

TiniJS has an UI library where I aim to provide every commonly used components and blocks and even whole pages. Components are architected in a special way where they are custom elements to be used not only with TiniJS, but also with other frameworks or no framework.

Working with reusable components is easy, usually in the form of passing props to the custom element tag. Customization can be done via props or CSS ::part() or custom theme family or completely clone a component source, ...

Components are also able to accommodate almost any design systems with as little effort as possible. This is achieved via a theming system; the concept is this:

Components are written only once, they are headless (without specific styles)
Themes are organized into Families (aka. design systems), families define their own base characteristics, for example: Bootstrap, Material, Fluent, Spectrum, ...
Upon the base characteristics, a family have style variants, called Skins, for example, the Bootstrap family may have: Light skin, Dark skin, ...

With the theming concept in mind, any app can have these theming capabilities:

One theme family - could be 80% to 90% of all the web apps exist today have only 1 certain style equivalent to TiniJS 1 theme family.
One theme family + multiple skins - the common use case of this is Light/Dark modes equivalent to TiniJS 1 theme family with multiple skins from the same family.
Multiple theme families - highly personalized apps may have multiple theme families with one or multiple skins from each family, a certain theme will be applied depends on user reference.

For details please visit Tini UI.

Web, PWA, hybrid Desktop/Mobile

A default TiniJS app is a single page application, it's small and fast, it can be deployed straight away as a web app. But you can also turn an TiniJS to one or all of these kinds of apps:

Progressive Web App (PWA) - achieve with a single CLI command
Hybrid Desktop/Mobile apps - using Tauri 2.0 or similar tools (todo: write instruction)

Static and Server

A TiniJS app can be started as a static web no matter big or small without a need of a server or database. You can always use SaaS services for almost any backend needs. I am also developing the Tini Content module - a file-based content management system for managing many types of content easily. Static site generation (SSG) or prerendering is also in the plan.

An optional Nitro server for server/API routes and other server stuffs if you need to handle backend tasks and refer to serve the web app from a Node server instead of a static host. I am limit in development capacity, so server side rendering (SSR) may not be supported in the first version, instead I plan for semi-SSR, where servers will serve single page to users and serve a minimum server-side rendered content to bots.

Features and modules

Feature-wise, since a TiniJS app is based on standard web technology, therefor any libraries and features those work in browser will probably work in a TiniJS app. So, you may not worry about features compared to other frameworks. You can even use other frameworks inside a TiniJS app, for example init and mount a Vue app to an element inside a TiniJS page.

There is also a modular architect so that certain modules can tap into the workflow of a TiniJS app, create a more streamline development pipeline.

Tools

The official CLI tool provides some convenience commands for working with a TiniJS app.

new - create new projects with ready-to-use templates
dev - start local development server
build - build production distribution
preview - preview the production build before deploying
generate - generate components, pages, utils, ...
module - manage Tini Modules

Besides, the CLI is generic enough to be used outside of a TiniJS app, in any project of any kind. It has an expandable architect where you can expand more commands to be used in other automation tasks. Some of the official expansions such as ui command (from Tini UI) to handle UI tasks or content command (from Tini Content) to handle content related tasks, ... You can create a CLI expansion pack for your own purpose privately or sharable.

OK, enough talking, show me some actions! 👌

Get started

Tini (or "Tí nị" in Vietnamese - meaning something very small in an adorable way).

To quickly create a TiniJS project, you can use the CLI to initialize a template.

npx @tinijs/cli@latest new my-app

The above command creates an app by downloading the Bare template. In the future, I would like to provide several starter templates. You can also create your own templates and share them with the community or for your own private use. Currently, these templates available:

Bare (default) - minimum structure of a TiniJS app.
Blank (flag -t blank) - includes router, state management, meta tags management and the Bootstrap theme family.

Now, inside the project you can run npm run dev to start the development server. You may start development by edit the file ./app/app.ts which is the root component of the app. For how to work with custom elements using Lit please visit Lit component, there are some differents between LitElement and TiniComponent, but for now you can modify static styles and render() as you would normally do.

To build the distribution, run npm run build and optionally run npm run preview to preview the production build. You can now deploy the .output folder to any static host.

You may want to check these examples to see more detail how a TiniJS app works.

Gallery App - https://stackblitz.com/edit/try-tinijs
To Do App - https://stackblitz.com/edit/try-tinijs-todo-app
Homepage - https://github.com/tinijs/tinijs/tree/main/apps/tinijs.dev

That is a basic introduction to the TiniJS framework, for more please visit: https://tinijs.dev.

Next topic: The structure of a TiniJS app and work with Components

Thank you for spending time with me. If there was anything not working for you, please leave a comment or open an issue or ask for help on Discord, I'm happy to assist.

Wish you all the best and happy coding! 💖